SVN setup
The group code is now managed under Subversion (SVN) version control. What follows is a quick setup guide to get you up and running with the Wales Group codes - GMIN, OPTIM and PATHSAMPLE. Once you are set up with the source code and are happy compiling it, you should read the best practice tips on the group version control page.
Getting an account on the SVN server
The SVN server we use is run by the good people in the Unilever Centre, so you should email ucc-support@ch.cam.ac.uk, CCing in David (dw34) to request access to the Wales Group repository. Make sure you include your CRSID, the bit before @cam.ac.uk in your email address.
Once they reply, you should be able to set up your password here after logging into Raven. To check you have access to the repository, try logging in here. If you can't, you've done something wrong! Get help!
Setting up your SVN details
Open a shell on the machine where you plan on using the group code. To make subversion easy to use, you need to specify some locations in your .bashrc file as environment variables. We do this as follows:
vi ~/.bashrc
This opens the vi editor. Press SHIFT+G to go to the bottom of the file, then press I to enter insert mode. Add the following to the bottom:
export SVN=https://svn.ch.cam.ac.uk/svn/wales/groups/wales/ export MYSVN=https://svn.ch.cam.ac.uk/svn/CRSID/
where CRSID is the user name you use to log into Raven with. When you're done, we need to save he changes, press ESC to exit insert mode (check 'Insert' isn't still showing at the bottom!) and then type:
:wq
and press ENTER. This should exit the editor, and return you to the directory you were in before. These variables will now be automatically set when you open a new shell, but for now, we need to load them manually. We do this using the source command:
source ~/.bashrc
We're now ready to check if you have access to the repository from your chosen machine. Lets try listing the contents of the trunk directory. Type the following ($SVN is the environmental variable we set to the location of the Wales Group repository above):
svn ls $SVN/trunk
You will be prompted to validate a security certificate so press p and then ENTER to accept it permanently. Now enter the password you set above (you should only need to do this once!). You should see a list of the directories in the repository, something like this:
AMBER/ AMBERTOOLS/ BLAS/ CHARMM31/ COPYING DISCONNECT/ DOC/ GMIN/ LAPACK/ NAB/ OPTIM/ PATHSAMPLE/ SCRIPTS/
NOTE: The 'trunk' contains the non-developmental version of the group codes.
Finally, before you download the code, you need to set up the log file template. This ensures that everyone submitting changes to the repository writes their log files in a similar fashion. Firstly, we need to edit the SVN config file
vi ~/.subversion/config
There is a section in the config file that begins as follows:
# [helpers] # editor-cmd = editor (vi, emacs, notepad, etc.)
This should be changed to the following:
[helpers] editor-cmd = vim +"r ~/template"
This tell subversion to open the file /home/CRSID/template when it asks for a commit log message to be written. Lets create this file now
vi ~/template
Enter insert mode by pressing i and paste the following into vi:
PROGRAM ------- SUMMARY OF CHANGES ------------------ SUBROUTINES AFFECTED -------------------- KEYWORDS AFFECTED ----------------- KNOWN ISSUES ------------
Save the file by pressing ESC and then typing :wq. You're now good to download the group code :)
'Checking out' the code
The first time you want to access the code, you need to 'check it out'. This will pull the code from the repository into a local directory for your use.
WARNING: It has been found that if you put the svn directory too far from your /home/CRSID/, you will not be able to compile the CHARMM source. This is most likely due to the variable CHARMM uses to contain the locations of files is of a limited length! We hope to fix this problem, but for now you need to ensure it is close enough.
This is the furthest the CHARMM31 directory within the repository can be from your home, without causing errors. Adding one more 'x' to the svn directory name will cause problems.
/home/csw34/svnxxxxxxxxxxx/CHARMM31
As a result, it is HIGHLY recommended that you transfer the code to ~/svn as shown below. This also prevents you from having to edit Makefiles more than is absolutely necessary. The code is checked out as follows:
svn co $SVN/trunk ~/svn
Notice that I'm transferring the code to:
/home/csw34/svn
This path is clearly shorter than that above, and so we should have no problem compiling CHARMM if we choose to do so. You'll need to wait a while for the code to transfer! Once it has finished, you'll see a message like this:
Checked out revision 9853.
The number given is the version number you have just obtained. Whenever changes are make to the code and uploaded to the repository, this number is incremented. It might be increased by more than one between versions as the counter is common for all software on the SVN server, not just ours! That's it! You now have a copy of the group codes. Here are a few notes on its structure for new users.
- GMIN/source contains the GMIN source code itself.
- GMIN/bin contains the GMIN binaries when they are compiled.
- PATHSAMPLE contains the PATHSAMPLE code. It has the same directory structure as GMIN.
- OPTIM contains the OPTIM code. It has the same directory structure as GMIN also.
- AMBER contains the AMBER9 source code.
- NAB contains the AMBER9 nucleic acid builder (NAB) source code.
- LAPACK and BLAS contain the maths libraries used by all the group code.
- CHARMM31 contains the CHARMM source code. You need to compile CHARMM before you compile GMIN with it, and you must use the same compiler in both cases. If you don't you'll get errors. The OPTIM compilation automatically recompiles CHARMM if necessary.
- DOC contains the documentation for GMIN, OPTIM and PATHSAMPLE. Whenever you introduce a new keyword or feature, it should be documented.
- SCRIPTS contains useful scripts developed by members of the group. For example, perm-pdb.py generates an OPTIM perm.allow file from an input PDB.
- AMBERTOOLS contains the full version of Amber Tools 1.2 with our updated LeaP files to fix forcefield problems we have encountered using AMBER9.
Now that you have the source codes, you should try to compile and test it. A brief tutorial on compiling GMIN with CHARMM can be found here.
Committing changes to the repository and keeping up-to-date
Info on the commands you'll need to use to add your changes to the code, and retrieve the updates from the repository can be found on the Theory Sector SVN Page.
RSS feeds
As an added feature, we have set up RSS feeds for the SVN logs. This means that when you commit a change, the source you submitted is automatically diff'd against the previous version, and differences uploaded to the feed, along with the corresponding log message. More info on the feed locations can be found on the group version control page.