CVS is software for maintaining code during its development. CVS enables you to track and, if necessary, reverse changes that occur during development. An individual user can check out copies of these files to their local computer (i.e., create a "working copy"), where they can modify the files, and then update the central CVS repository (database) with these changes. All of this activity is tracked by CVS, enabling users to track their own changes, consolidate them with changes by other users, and even follow multiple concurrent versions of a single project.
FMRIB has a general repository (database) of a wide range files, organized into individual "projects" (e.g., FSL software, simulations, even LaTeX files). We also have a second CVS repository that is dedicated to pulse sequences, which has additional security to protect proprietary information.
Your use of CVS will primarily relate to your own pulse sequence projects, where you will use CVS to:
In addition, we'll use CVS to organize code within FMRIB, to:
There are two aspects to your interaction with CVS: browsing the CVS repository and file transfer. To browse the contents of CVS, it is easiest to use the web interface. However, keep in mind that this web interface is intended for browsing only. To upload and download files, you need to use the cvs software (either on the command line, or via a GUI interface like WinCVS or Tortoise).
File transfer with CVS requires that you have the CVS software installed on your computer, and that you tell this software where the CVS repository is. As mentioned above, there are two main repositories on the FMRIB servers, and you should use the one on jalapeno at /usr/local/share/siemenscvs In general this means that you will need the environment variable CVSROOT set to:
CVSROOT=":ext:jalapeno.fmrib.ox.ac.uk:/usr/local/share/siemenscvs"
In Windows, we recommend using a GUI program like WinCVS. Unfortunately, there is not much of a manual for WinCVS, but it is a fairly intuitive interface, provided you understand the basics of CVS commands. It is worth reading these instructions if you need to install WinCVS.
The repository for Siemens code has a particular structure that you are asked to adhere to. Basically, this amounts to:
External code: product_vXXX
Original Siemens product and other external code for version VXXX is stored here. This area is for storage only, and the files here SHOULD NOT BE CHANGED. All types of external code can go here: pulse sequences (IDEA), recon (ICE) and post-processing (EVA). Siemens product often ships as .zip files, which is the one kind of non-code file that can be imported to the repository.
Internal pulse sequences: idea_vXXX
Pulse sequence projects for version vXXX should in general be made at the level of the sequence subdirectory within seq/. You then check CVS files directly into and out of seq/.
Internal recon and post-processing: ice_vXXX
Projects should in general be made at the level of the subdirectory within IdeaIcePrograms/.
WinCVS basics
As stated above, WinCVS is fairly intuitive provided you understand basic CVS commands. To that end, the following section is recommended reading to bring you up to speed on the basics. A few hints for WinCVS:
:ssh:username@jalapeno.fmrib.ox.ac.uk:/usr/local/share/siemenscvs
Command-line help
To see a list of cvs comands:
To see options for a given command (e.g., cvs checkout), use -h:
cvs checkout: Retrieving code from the repository
The cvs checkout (or, cvs co) command retrieves code from the repository. Let's checkout the project a_ep2d_bold in the idea_vb13a/ part of the repository into the standard seq/ directory.
In WinCVS, select Remove->Checkout Module. In the window that appears, your settings should look like THIS.
On the command-line, execute the following:
This will create a directory called my_ep2d_bold/ within seq/ containing a copy of the code for a_ep2d_bold. If you do not use the -d option, it will create a directory seq/idea_vb13a/a_ep2d_bold/. Note that the new directory also contains a CVS/ directory, hich contains info that CVS uses to keep track of this local copy.
To check out a single file:
cvs import: Adding a directory to the repository
Checking in and out of existing projects is nice, but you'll inevitably want to create new projects. Since new pulse sequences are normally created by copying existing, working sequences, you'll typically want to create a new sequence project from an existing set of files.
Let's create a dummy project to play with. Go to the directory we just checked out. It's important that you only check in the basic code (makefiles, .cpp and .h) since other files will clutter up CVS, and potentially take up a lot of disk space (e.g., compiled binaries change every time you compile!). Remove everything except the files you want in the new CVS project (Makefiles, .cpp and .h), and remove the CVS/ directory (we'll create a new one associated with our new entry in the repository).
Now, use cvs import to create a new project with all the files in the directory. Let's import into the idea_vb13a/ part of the repository and call the project my_project.
In WinCVS, select the folder you're going to import (seq/my_ep2d_bold/) and from the menu bar select Remote -> Import Module. The "Import Filter" dialog may contain some complaints about file types, which you can probably ignore (select "OK"). In the window that appears, your settings should look like THIS. Under "Import Options" you probably want to select "Create CVS directories while importing" so that your newly imported directory registers itself with CVS. After running this command, you should see a checkmark appear on the folder name, indicating that CVS is now tracking this directory (if no checkmark appears, you may not have selected the "Create CVS directories" option described above).
On the command-line, you have to do the import in two stages. First you import the directory:
CVS now knows about your project (you can see it in the repository web-page), but it doesn't know about your local copy. Check a copy out from CVS under a different local name:
Note this new directory is identical to the original, but contains a CVS/ subdirectory. At this point, you should remove the original (which CVS doesn't know about) and work solely with the checked-out copy.
cvs commit: Checking you changes into the repository
Checkout creates a local copy of the code that you can edit, test, etc. Once you've made changes that you want to keep, you should check your code back into the repository. You'll have the opportunity to add a comment to indicate the nature of the change. It is highly recommended that you make these comments useful, as the reason for even minor changes can become difficult to remember. If you can't remember what changes you've made, you can use cvs diff to compare files to the version in the repository.
Make a minor modification to one of the files (e.g., add a comment in a_ep2d.cpp). In WinCVS, this modified file should be displayed with a red file icon. Use cvs diff to view the differences between your local file and the one in the repository (in WinCVS, select Query -> Diff):
Now, commit your changes (being sure to add a comment on the changes, like "added comment to test CVS").
In WinCVS, select the modified file, then select Modify -> Commit. The default options should be fine, so the window that appears should look like THIS.
cvs add: Importing new files to a project
You will often need to add files to an existing project. Adding a file to a project is done in two steps. First, you first need to register it with CVS using cvs add. Create a dummy file (e.g., new_file.cpp) in your working direcotry and add it to CVS. In WinCVS, select Modify -> Add; on the command-line, execute:
Note that cvs add simply alerts CVS that this file exists (it isn't in the repository yet). To actually place it into the repository, you need to commit the change. In WinCVS, select Modify -> Commit; on the command-line, execute:
One cautionary word about cvs add: CVS will accept any kind of file you give it and try to treat it as ascii. If you accidentally check in non-code files (e.g., object files or other compilation targets), CVS will try to track these. Obviously, if CVS keeps over-writing your compilations with files from the repository, this can cause problems. So be careful to only add/import code!!
cvs update: Updating the working directory
The situation occasionally arises that you aren't sure if the code in your working directory is the most up-to-date version (e.g., if someone else may have checked in changes, or if you've done some coding on another machine). In this case, its a good idea to sync your working directory with the repository. You can do this using cvs update. In WinCVS, select Modify->Update; on the command-line, execute:
If cvs update does find differences between your local copy and the repository, it will attempt to merge the files. This often works out, but may result in "conflicts" (e.g., un-mergeable code), which CVS deals with by adding text to your local copy (which will almost certainly break the compilation). Merging conflicts is beyond the scope of this simple introduction, so we simply recommend that you do a "cvs diff" before updating to anticipate problems, and direct you to the manual if you have problems.
cvs tag: Designating "stable" sequences
Some of our sequences are in regular use on the scanner, which means that we need to keep track of sequence versions that are "stable", even if the sequence is under development. The idea is that anyone should be able to retrieve the "stable" source code from CVS in order to compile and install it on the scanner. To distinguish older, stable versions from volatile code under development, we'll just tag versions that we trust as being "stable".
In WinCVS, select Modify->Create a tag... Call the new tag name "stable" and select "Overwrite existing tags with the same name". This first tag establishes this version as THE current stable version, removing this label from the previous "stable" version if one exists. Now create a second tag which is intended to serve as a permanent marker that this WAS a stable version, in the event that we want to return to a previous stable version in the future. Call this second tag stable_YYYY_MM_DD with the appropriate date YYYY_MM_DD.
On the command-line, go to a working directory containing the stable version and execute:
To retrieve the current stable version of a sequence:
We keep product code in its original form in a separate part of the CVS repository, under product_vXXXX/. This part of the repository should be used slightly differently than the rest:
Checking in Siemens product .zip files:
Siemens will usually give you a .zip file containing the entire directory structure for a particular sequence. Check this .zip file into CVS directly, telling CVS to treat it as a binary file using the -kb option when adding it. (NOTE: WinCVS is clever enough to recognize files as text or binary and will generally do the right thing, but also will let you know of its decision.)
First, you need a local working directory for the correct product CVS module. For example, for VA25A code, to check out a local copy of product_va25a/ to the directory local_product
Now place the file you intend to add in the local directory and add it:
You can now commit the file as usual. Be sure to put in a helpful comment
when you commit:
Checking in raw Siemens product code:
If you have just a few files of raw code to check in, you might as well check it in as a standard CVS project (but note that this code still is not intended to be modified!). As above, you can check the entire directory in with one call to cvs import: