Note : BioPerl switched to using Subversion in January 2008. The CVS repositories described here are no longer actively maintained. CVS at BioPerl is now deprecated.
This page describes how to use the Open Bioinformatics Foundation CVS server and how to perform basic tasks in CVS including, checking out the code, committing changes, checking out a branch, merging changes between branches. You can also track CVS changes via RSS.
|bioperl-live||Core modules including parsers and main objects|
|bioperl-run||Wrapper modules around key applications|
|bioperl-ext||Ext package has C extensions including alignment routines and link to staden IO library for sequence trace reads.|
|bioperl-pedigree||Pedigree package has objects for Pedigrees, Individuals, Markers, & Genotypes|
|bioperl-microarray||Microarray package has preliminary objects for microarray data|
|bioperl-gui||A GUI package which for Perl-Tk objects for a Graphical User Interface. Serves as the basis for Genquire|
|bioperl-db||BioPerl DB is the Perl API that accesses the BioSQL schema|
Browsing CVS repositories
A web interface to viewing the code in the CVS repositories is available from the Open Bioinformatics Foundation
Following code updates
After you follow the directions below you'll see how to keep your local CVS checkout up to date. How do you know when to do a CVS update? Of course you can just do an update every time you start to work on code (or know there has been a bug fix). CVS commit messages and diffs are posted to the bioperl-guts mailing list as well as to the RSS feeds. You can folllow some of those feeds on the Tracking CVS commits page.
Checking out code from any repository
Instructions for downloading any BioPerl repository using anonymous CVS
- What you need to set up:
- cvs on your local machine
- Once these are set up, create a directory for BioPerl:
$ mkdir ~/src; $ mkdir ~/src/bioperl $ cd ~/src/bioperl
- Login to CVS (password is "cvs"):
$ cvs -d :pserver:firstname.lastname@example.org:/home/repository/bioperl login
- Checkout the BioPerl core module, only (the right thing to do for most people):
$ cvs -d :pserver:email@example.com:/home/repository/bioperl checkout bioperl-live
OR checkout a BioPerl package such as bioperl-db
$ cvs -d :pserver:firstname.lastname@example.org:/home/repository/bioperl checkout bioperl-db
OR checkout all the BioPerl repositories with a repository alias
$ cvs -d :pserver:email@example.com:/home/repository/bioperl checkout bioperl_all
- Tell perl where to find BioPerl (set this in your .bash_profile, .profile, or .cshrc):
bash: $ export PERL5LIB="$HOME/src/bioperl" tcsh: $ setenv PERL5LIB "$HOME/src/bioperl"
$ perl -MBio::Perl -le 'print Bio::Perl->VERSION;'
If you wanted to check out the older 1.4 branch of BioPerl (called branch-1-4) into a directory called bioperl-branch-1.4 use the following
$ cvs -d :pserver:firstname.lastname@example.org:/home/repository/bioperl co -d bioperl-branch-1.4 -r branch-1-4 bioperl-live
Checking out code from the repository with a developer account
If you have been given a developer account for read-write access to the repository it will be a login for the machine dev.open-bio.org. You will need
- Secure shell (ssh or ssh2) set up on your local machine
- cvs set up on your local machine
- A local environment variable, CVS_RSH, set to ssh
Change your password
You will want to login into that machine via SSH and changed your password to only something you know. This is done by typing
and following the instructions.
Setting up SSH keys
See Setting up SSH keys.
Checking code in and out
You will want to put one of these commands (depending on your shell) into your .bash_profile or .profile or .login or .cshrc file depending on where you normally put these commands.
setenv CVS_RSH ssh
To checkout the code use the ext protocol instead of pserver (replace USERNAME with your username you were given of course)
$ cvs -d:ext:USERNAME@dev.open-bio.org:/home/repository/bioperl co bioperl-live
Checking in code
After you have made some changes to the code (and of course tested the changes by running the appropriate tests from the t directory), you will want to contribute them back to the code base. You were of course making your changes in the directory where you checked things out with your read-write account (NOT anonymous CVS). To commit changes you simply need to provide a commit message and a list of the files to check in. If you have a lot of changes that are unrelated to each other it is better to commit things in a batch where the commit commment is relevant. Here is an example of checking in changes to a single file called Foo.pm.
cvs commit -m "Changes to handle FooBar situation" Foo.pm
If I wanted to check in all the changes for a particular directory (FooMaker in this example) I could just provide the directory name and CVS will figure out which files have changed and only commit those.
cvs commit -m "Improvements to the interface API and assorted fixes related to testing FrozzBozz" FooMaker
Adding new files
If you made changes that involved creation of new files you will need to first register them with CVS. To do this you issue the cvs add command like this. The ... indicates you could have listed several files at once.
cvs add ModuleName.pm File2 ...
After you have added the files you can commit them to the repository (and provide an appropriate commit message)
cvs commit -m "New module to do some FooMagic" ModuleName.pm File2 ...
It is possible that since the time you started working on your code someone else might make changes and check them in before you do. That's okay, that is really the whole point of CVS, rather than locking a file so only a single person can work on a file, CVS allows separate changes to happen and warns you when there is a conflict. If the conflicting commits are for different parts of the file CVS will merge the changes and no action will be needed by the user. Only if two (or more people) are working on the same part of a file will the user need to get into the file and merge the changes by hand. If you try and commit changes to a file after somone has updated the file in the repository, CVS will notice this and warn you with the filename that is no longer up-to-date.
To explain this more concretely, lets assume we have a file call foo.pm with one line in it
and two users who want to change the line to say: Bob:
Hello cruel world
Hello there world
Bob checks in the changes so the repository has the version of the file according to Bob. Alice goes to check in her changes and gets a message from CVS like this:
cvs commit: Examining . cvs commit: Up-to-date check failed for `foo.pm' cvs [commit aborted]: correct above errors first!
Before she can proceed you have to merge the commited changes with your local changes. She needs to issue the update command first to merge the changes locally from what is in the repository.
cvs update: Updating . RCS file: /home/repository/test/x/foo.pm,v retrieving revision 1.1 retrieving revision 1.2 Merging differences between 1.1 and 1.2 into foo.pm rcsmerge: warning: conflicts during merge cvs update: conflicts found in foo.pm C foo.pm
Her local copy of foo.pm has been updated, the file now looks like this
<<<<<<< foo.pm Hello there world ======= Hello cruel world >>>>>>> 1.2
CVS is indicating where the changes are surrounding the changes by the <<<< and >>>>. The first part is the original text and the second part is the version from CVS. If she wanted to merge the two sentiments into a single file she might change the file to be
Hello there cruel world
And now commit the file
cvs commit -m "Merged the conflict" foo.pm cvs commit: Examining . Checking in foo.pm; /home/repository/test/x/foo.pm,v <-- foo.pm new revision: 1.3; previous revision: 1.2 done
Finally Bob will need to update his version (which can be done at any later time)
cvs update cvs update: Updating . U foo.pm
This is a good reason to make sure your version of the repository is up to date (by issuing the cvs update) command before working on a particular file. Typically just go into your base bioperl directory and type cvs update If you are finding that you are continually having conflicts it may be a good idea to contact the other user who is contributing code so you can coordinate your efforts. If you plan to embark on dramatic changes to a module it is also a good idea to post to the main Mailing list to let everyone know your intentions.
Checking out a branch
To check out a branch we use the tags associated with a branch. In the following example we want to checkout code in the bioperl-live CVS module which is in the /home/repository/bioperl directory on dev.open-bio.org and we want to get code from the BRANCH-1.1 branch tag and create a new directory called bioperl-branch-1.1 where it will go. The following command does all of that.
cvs -d:ext:USERNAME@dev.open-bio.org:/home/repository/bioperl co -r BRANCH-1.1 -d bioperl-branch-1.1 bioperl-live
Merging changes on branch and main trunk
Sometimes a bugfix or a code change needs to propogated to both the branch where it is being fixed and another branch like the main trunk. Rather than having to type in the changes twice you can use the CVS merge capability to merge the changes over. If the changes are in conflict with other more recent changes to a file on the branch this can will require some manual editing, but otherwise merging changes can save you a lot of time.
Here is how to merge changes onto the main trunk assuming you have checked in some changes to a branch called BRANCH-1.1 and you are currently in a directory which is a checkout of the main trunk. Comments are in red are NOT to be typed in.
cvs update -dP # first make sure we are up to date cvs update -j BRANCH-1.1 file1 subdir/file2 directory3 # Merge changes from BRANCH-1.1 for the files file1 and file2 as well as any files changed in directory3
If there are no warnings then you can proceed with testing and then commiting the changes to the main trunk. You may want to run make test or else just
perl -I. -w t/test1.t # run a test that should test out this updated code (you might have to update tests from the branch too!)
If tests pass fine then check in the changes to the main trunk
cvs commit -m "Merged changes from branch: fixed bug #123 and performance boost trick" file1 subdir/file2 directory3
Note that often you will get conflicts from a merge due to the $Id$ header which will have different values on the branch and trunk. One way to avoid this is to check out both the main trunk and branch with the -kkv option turned on.
- Note: This needs to be checked again to be sure that is right way to avoid the issue --jason stajich 14:18, 23 December 2005 (EST).
Packaging code for a release
See also Making a BioPerl release.
Making a branch
You must have tagged the release you want to make a bug fix to. Say we want to make a bug fix to 1.6. Here is what we do:
- Either there is already a bug fix branch at 1.6 or you have to make one. If you are going to make one, it is probably best to post to guts first and ask people there if there is already one built. You can check out the symbolic tags by going cvs log README in the top level directory
- To make a branch in the repository if noone else has for this release do the following which makes a branch in the repository at the 1-6 level called branch-1-6
cvs -d:ext:YOURNAME@dev.open-bio.org:/home/repository/bioperl rtag -r release-1-6-0 -b branch-1-6 bioperl-live
- move to a clean area and checkout the branch-1-6 branch by going
cvs -d /home/repository/bioperl checkout -r branch-1-6 -d branch-1.6 bioperl-live
- Now fix the bug, and then behave as in the standard making a release in this directory... so
- Fix the bug, and check it works in this directory.
- tag the release with a cvs tag release-1-6-1 tag (or something equally appropriate to indicate that this is the Nth bugfix release on the 1.6 branch)
- Export a clean copy of the release using
cvs -d:ext:YOURNAME@dev.open-bio.org:/home/repository/bioperl export -r release-1-6-1 -d bioperl-1.6.1 bioperl-live
- Check this works, tar it up and check it works somewhere else.
Typically we will release bug-fixes off of a branch, so whenever a new stable series is declared, a branch will be made.
- To see what tags a file already as in it do:
cvs log README | more
- To see what branch the local repository is on, do the follow, the sticky tag will be set to something if you are in a branch:
cvs log README | more