Concurrent Version System (CVS) is used for configuration management of software developed here at Ames Laboratory and also for NWChem at Pacific Northwest National Laboratory. Off-site users are required to used this system when doing development work on the Ames Laboratory code. This makes collaborative work with the SCL developers more facile. As a matter of simple prudence, is advisable to use some sort of configuration management system for any installation of Software, even if the users do not expect to be doing significant development work. Using CVS will retain the ability to correct errors or make modifications to the code in a controlled and traceable manner.
CVS was chosen as the SCL standard configuration management system because is designed to allow many different developers to work independently on a large code, while greatly mitigating the agony of merging independently developed sets of code changes. For developers working on unrelated modules of the code, the effects of changes made elsewhere in the code can in some cases be completely ignored. The identification of overlapping changes is greatly facilitated, allowing efficient and speedy resolution of conflicts.
This section provides a brief introduction and overview of the CVS system. Developers needing more detailed information on specific CVS commands and capabilities are refered to the on-line documentation included in the CVS code package (i.e., the man pages; consult your system administrator if your system does not have them installed.)
CVS is a configuration control package designed to facilitate multiple developers working on the same software package. It is implemented as a layer on top of RCS and provides a number of useful features which RCS alone does not. The two most important of these features are
CVS divorces the directory tree in which development takes place from the directory tree in which the master copy of the sources are kept. The latter directory tree is referred to as the repository, and it has exactly the same structure as the working directory tree. Where the working tree would have source files, the repository has the RCS files for the sources (e.g., source.f,v corresponds to the working directory file source.f).
Users working on a program check it out of the repository into their own directories. The individual working copies are by default created giving the user read and write permission on all of the files and can be used directly. When a developer has completed and tested a set of changes, the revised source file(s) can be checked into the repository. The other developers are unaffected by the change to the repository until they update their local copy of the source or check out a new copy. Anyone checking out a new working copy will always get the latest version present in the repository.
Users can poll the repository for changes at any time, and update their own working copies with the changes that have been entered in the interval between their last checkout or update and the current version. The repository is entirely unaffected by the update command. The user's private working copy is the only thing that is changed. If any changes were merged into the repository between the user's last check-out or update and the current one, dealing with any inconsistencies or overlaps with changes in the local working copies is the user's problem.
When a user checks a revised source file back into the repository, CVS automatically checks for all differences between the copy being checked in and the current version of the file in the repository. If changes in the new file being checked in overlap or conflict with changes that have been merged into the repository since the last check-out or update of the copy being merged, CVS will not automatically merge the new copy into the repository. If the changes do not overlap or conflict, however, CVS will merge the new source over the existing source in the repository.
In most cases, changes made independently by different developers will not conflict and CVS can handle the merger automatically. When they do conflict, the developer must fix the problem(s) and ensure that the new changes mesh properly with changes others have put into the repository. CVS allows users to work independently on the same source files without unduly interfering with each other, but it is still necessary for developers working on functionally related changes to communicate with each other, even if their source code changes do not conflict.
CVS is implemented as a single program invoked by its program name cvs. A number of options can be specified on the command line following the program name. The command line can also include subcommands, which come after any options that may be specified. The syntax of the command line is as follows;
cvs [cvs_options] subcommand [subcommand_options] [arguments]
The man pages list the applicable options for the cvs command itself and for each subcommand.
CVS must be told of the location of the repository. This can be done with the cvs_option -d (e.g., -d /repo) or by setting the environment variable CVSROOT. Although the CVS man pages implicitly assume that a single repository will be used for all projects under CVS control, this is not strictly necessary and it is quite common for major projects to have separate repositories. Different repositories can be defined by the simple expedient of changing the definition of CVSROOT.
CVS is designed to deal with source files organized into modules. A module is basically a collection of source files that form some sort of sensible unit and probably should be worked on as a group. The module can simply be the name of a directory within the repository (e.g. gpshmem or gpshmem/src, or it is defined as a collection of selected bits and pieces of the directories within the repository. For example, it might eventually be desirable allow users to check out any module without getting certain parts of the package, such as internal testing data or experimental segments of the code. Specific modules could be defined in the CVS system to give these results.
The procedure for checking out a working copy of the code stored in CVS repository is very simple. From the directory where the working copy is to be checked out to, a given module can be checked out using the following command;
cvs co module_name
To check out the generalized portable shmem, the command is simply,
cvs co gpshmem
The working version of a module in a local directory can be compared with the source in the repository using the command
cvs diff
This command accepts the same arguments as rcsdiff, and will compare particular files itemized on the command line or the entire directory tree recursively. (The command cvs log is the equivalent of the RCS rlog command and operates similarly to cvs diff.
Changes made to the repository after a particular working copy has been checked out can be merged into the files on the working directory using the command
cvs update
This command is recursive throughout the checked-out directory tree. It flags modified files in the working directory with an "M". Files that have changed in the repository since the last update are marked with a "U". New files in the working directory that do not occur in the repository are marked with a ``?''. There are a number of other codes for other circumstances, which are detailed in the man pages. A particularly useful command is the option to check on what has changed since the last update of the working directory, but without merging any of the changes from the repository. This can be done using the command
cvs -n update
To remove a file from a repository controlled by CVS it first must be removed from the directory with the Unix rm command. The command cvs rm is then used to notify CVS. When this (nonexistent) file is checked in at the next update, it will be moved to a special place in the repository where it can be recovered if old versions which require it are checked out, but where it will not appear in future working copies.
To add a new file to a repository controlled by CVS, the command is cvs add. Like cvs rm, the actual addition takes place at the next check-in. As with the first RCS check-in of a file, cvs add will prompt for a description of the file (not a log message; that happens at check-in). New directories must also be added with cvs add, but no description is requested.
The command to check-in changed files is cvs ci or cvs commit. As with cvs diff, CVS will accept particular file names or search recursively through the directory tree looking for files that have been modified. CVS prompts the user for a log message for the files being checked in. If the specific filenames are listed on the command at check-in, only a single log message that applies to all of them is required. If CVS must search and compare to find the files that are being checked in with changes, it prompts for a log message for all of the modified files in a given directory. The EDITOR environmental variable is used to decide which editor to bring up to enter the log message.
CVS automatically tracks which version(s) of the source a newly checked-in working copy is based on. This allows it to determine whether the changes would be checked in on a branch or the main trunk, etc.
To delete an entire working directory, the simplest approach is to use the command cvs release -d gpshmem in the directory above it. This command checks the files in the working directory, looking for changes that have not yet been checked back into the repository. This is to ensure that changes are not accidentally abandoned. If no inconsistencies are found, CVS deletes the entire directory tree. (NOTE: leaving off the -d just does the check without deleting anything.
The above commands provide a convenient starting point for learning how to use CVS. However, users wishing to obtain a more thorough understanding of the capabilities of the system should read through the CVS man pages to get a better feel for everything that can be done. (Hint: If you are unsure of what a command will do, try it first with a -n option on cvs itself. This is like make -n, which reports what it would do if invoked without the -n. But it does not actually do anything.
The following is provided as a quick reference guide to CVS. A more detailed short-form reference is available in man pages. Detailed documentation can be obtained using the command info or the emacs info for CVS. This will be with most LINUX distributions that include CVS. It also comes with the source code at http:/www.cyclic.com
Contact Ricky at rickyk@ameslab.gov to report problems.
CVS version information is "sticky". That is, CVS usually remembers the specific version checked out to a working directory. This can be confusing, since the output of such commands as cvs update, etc., will not always refer to the latest (or head) version. Changes can magically disappear. This may be desirable. Or it may not be. The option -A forces the system to look at the lastest version when doing the update. The form of the command is
cvs update -A
If CVS is interrupted, or there is an NFS problem, it may occasionally leave locked files in the CVS repository, causing subsequent commands to wait forever, printing messages indicating it is waiting for someone to relinquish access to a specific directory. Fixing this requires deleting files from the repository. Contact Ricky rickyk@ameslab.gov for help.
Other requrements are: