GROMACS: Fast, Free and Flexible MD

CVS Usage

Tuesday, 13 September 2005

To keep track of changes and different versions of the GROMACS source code we use CVS, Concurrent Version System. CVS is free software and available on all major platforms. You can find manuals, source code and a lot of other CVS information at www.cvshome.org.
If you are using Linux it should be trivial to install a cvs package, but it is probably already present on your system.

Anonymous CVS read-only access

The latest development version of the Gromacs source is available via anonymous CVS. You do not need any special account to retrieve the source, but of course it is read-only. We are usually quite conservative when commiting changes, so the CVS version should be functional and without major bugs, but it is entirely unsupported. We appreciate if you point out bugs or problems, but since this is development software it might take a while to fix them. In other words, check your results VERY carefully if you use CVS for any kind of production runs.

Use the following commands to retrieve the latest CVS source:
(The whole command from 'cvs' to 'login' (and 'gmx' the second time) should be on one line - your browser might wrap the lines in the window below. Just hit return when you are prompted for a password)

$>cvs -z3 -d :pserver:anoncvs@cvs.gromacs.org:/home/gmx/cvs login
Password:
$>cvs -z3 -d :pserver:anoncvs@cvs.gromacs.org:/home/gmx/cvs co gmx

This will create a "gmx" subdirectory with all the Gromacs sources. To create the configure script files you should now run the "./bootstrap" script in the gmx directory. To do this you might need to install or upgrade your versions of autoconf and automake to those provided on this site. Check the developer tools section in the menu to the left!
If you don't give any special command you will check of the HEAD branch, which is the main development branch, heading for the next major Gromacs version. If you only want to check or work with the most recent bugfixes in the stable revision tree you should switch 'branch' to the patches for the stable version instead. This is easy; just write

$>cvs update -A -r release-3-3-patches

in the top gmx directory. The -A flag is just to make sure we remove all sticky tags - a normal 'update' will only get you the most recent version of the branch you are currently working with. You cannot commit any changes as an anonymous user. If you would like to have a bugfix or other modification incorporated into the source it is best to post it to the gmx-developers mailing list.

PLEASE NOTE: To avoid confusing normal users, try to post all CVS-related questions to the gmx-developers list and not the general gmx-users list.
You can also get out the LaTeX source for the manual by checking out the module "doc", and our local regression test suite as the module "gmxtest".
.

Read-Write access with a user ID

If you have been given full write access to the repository, you should have a user name and password. Since the pserver method above transfers all passwords in clear text we are running it in read-only mode. This means you need to use ssh as an external authentication method for CVS if you want to write to CVS. There is built-in support for this, ut we must first tell it which method to use. For bash/zsh-style shells:

$>export CVS_RSH=ssh

or for csh/tcsh shells:

$>setenv CVS_RSH ssh

It is a good idea to assign this environment variable into your login files so you don't have to do it every time you use cvs. It will not interfere with CVS pserver usage on cvs.gromacs.org or other servers. Now execute ssh with the "ext" authentication method (external):

$>cvs -z3 -d :ext:@cvs.gromacs.org:/home/gmx/cvs co gmx

You can get rid of the password prompt completely if you add your public key to the file ~/.ssh/authorized_keys on the server. Use ssh-keygen on the machine you will log in from if you haven't got a key yet.

Some tips for using CVS

There are a couple of things you might need to know in order to get started. anonymous access:

Make your own work directory, e.g. /home/lindahl/gmxwork and cd there before you check out the sources from CVS.
It is no problem to check out several working copies of the source in different places. You might for instance want one on your portable too, or your home macine.
To compile GROMACS from CVS you need to use automake to create the intermediary Makefile.in's, and autoconf to create the configure script. All these steps are performed when you run the "bootstrap" command in the gmx directory. Note that you will probably have to upgrade your installed versions of these programs to those provided on this site.
If you at a later point want to get a new version of the software (after your colleagues have added new features), simply type
cvs update gmx.
If you want to upload your edits to the repository use a command like
cvs commit file1 [file2]
to enter one or more files.
If you want to add or remove a file to/from the repository, use the (by now obvious) command
cvs add/remove file1 [file2]
To make this changes have any effect on the repository you will also have to commit them (cvs will tell you).
If you are done with editing for the few coming weeks use cvs release gmx. CVS will then tell you if there are any changes you haven't committed yet.
You can check out an earlier version(e.g. 1.14) of a file with
cvs update -r 1.14 file.c. Note that this will create a sticky tag on the file, so it will NOT be updated the next time you do a normal update. To remove the sticky tags you must use the -A flag to cvs update, i.e.
cvs update -A.
You can check the differences between your file and the most recent version in the repository by typing
cvs diff -r HEAD file.c.

Brief Guide to Commonly Used CVS Commands

Doug Wright, last update August 29, 1995

Quick Reference

cvs co module = check out a copy of 'module' into your working directory (you only need to do this once)
cvs -R co module = like the command above, except use rCVS to get from a remote host
cvs update = update all the files in the current directory
cvs commit = commit all of the files you have changed to the main repository
cvs add file1 = alert CVS that file1 should be added to the repository at the next 'cvs commit' invocation.
cvs rm file1 = alert CVS that file1 should be removed from the repository at the next 'cvs commit' invocation.

Advanced Commands/Hints

cvs history -Ta -n module = show all tags on 'module'
cvs diff -r HEAD file1 = show difference between my checked out file1 and the most recent version in CVS
cvs rtag tagname module = tag 'module' in CVS with 'tagname' (NOTE: this creates a history entry, the 'cvs tag' command does not)
cvs update -j branchtag = merge 'branchtag' into previously checked out version (NOTE: files added to the branch are not added!)
CVS/Entries = this file shows you the tag and RCS version of what you checked out

Topics covered below

Checking Out a Module for the First Time
Commiting Your Changes to the Main Repository
Getting Updates and Merging Changes from Different Users
Adding New files to an Existing Module
Reverting to Old Versions of Files (Tags)

Checking Out a Module for the First Time

To check out something for the first time use a command like this:

cvs co beget

or if the repository is on a remote computer:

cvs -R co beget

CVS will create a directory called 'beget' in your current working directory and copy all of the files and subdirectories associated with the module 'beget' into it. All of the remaining CVS commands must be issued from the 'beget' directory.

Commiting Your Changes to the Main Repository

You can edit any of the files you want, and when you are ready to commit your changes to the master repository do,

cvs commit

CVS will at some point start an editor (vi or emacs depending on your environment variables) and ask you to enter some text that will be stored as part of a history of changes. If this is successful, then your versions of the files will be copied back to the main site so that everyone can access them.

Getting Updates and Merging Changes from Different Users

If someone else changes the files while you are working on your own copy, you must update your copy with the command

cvs update

to get the new versions. You can chose to update your files at any time. Before committing any files, CVS will check to see if you need to do an update. If you do, CVS prints a message and aborts the commit. If someone else has changed a file that you have also changed, CVS will attempt to merge the new changes into your file. If it is unsuccesful at doing so it will alert you to a 'conflict.' If there is a conflict, the new file will contain sections that have both your changes and the other persons changes. These sections will be flagged by lines like

>>>>>>>>>>>>

and

<<<<<<<<<<<<

The user must then look at the conflicting regions, choose what is correct and edit the file.

Adding New files to an Existing Module

If you create new files, you have to tell CVS to put them into the repository. First do,

cvs add newfile1 newfile2

then do a 'cvs commit'.

The 'add' command alerts CVS to commit the named files at the next invocation of cvs commit.

Reverting to Old Versions of Files (Tags)

Every time you commit a file to CVS it increments a revision number. The first commit is 1.1 then 1.2 and 1.3 etc. (I don't know if or how it ever gets to 2.1). To revert to an old version of a file you can use the version number as a tag as in

cvs co -r 1.6 bbsim/dat/dcha.db

to check out version 1.6 of dcha.db. You could also use the update command

cvs update -r 1.6 dcha.db

but be careful that you don't commit the old version on top of the current version. To see what version number the current file is do

cvs status dcha.db

You can also revert to files that were tagged as a particular version by the user. For example

cvs co -r v200 bbsim/dat

would check out all of the files in dat that were tagged by somebody as version v200. To see what user tags have been created do

cvs history -Ta -n bbsim

Retagging a previous version and adding to it

The following will make "new_tag" which will be the same as "last_tag" even though you are working with the HEAD.

cvs rtag -r last_tag new_tag gnmuon

Don't use tag or it will tag the current directory stuff too. OK, now you can update the files from HEAD that you want to include in the "new_tag":

cvs tag -F new_tag file1 file2 file3

Next >