## Setting up the CVS

Since we have multiple people doing programming on avida, we are using SourceForge to keep the project organized. The developmental version of avida is maintained there using a program called the "Concurrent Versions System" or CVS. This document will tell you how to setup your account so that you will be able to use the CVS. I'll also give you some instruction on how the CVS works, but you can skip that if you want, and the next document will tell you what you need to type if all you want to do is pull avida out of the CVS. Click here if you want to go directly to the Avida project page on SourceForge (this is not needed to download the source).

### Configuring the CVS

The CVS software now comes with virtually all flavors of Unix and Linux. If you are using a system that does not have it, you may need to look into downloading it first. The rest of this document assumes that you do have CVS available to you.

The first thing you need to do is determine what kind of "shell" you are using. The shell determines how your command line works, and how you configure "environment variables" that let programs know where things are. In this case, you are going to need to set an environment variable to let CVS know where the software repository is, and what protocol to use to access it. To begin with, type "`echo $SHELL`" on the command line.

If the response is /bin/tcsh, you should:

1. In your home directory, open the file .cshrc in a text editor.

2. Move to the end of the file, and add in the lines:

   `setenv CVSROOT anonymous@cvs.avida.sourceforge.net:/cvsroot/avida
   setenv CVS_RSH ssh`

   This will set the needed environment variables. To be able to make changes to the Avida sourcecode directly, you need to get an account on SourceForge, and then substitute your account name for "anonymous" above. You then need to be added as a developer on the project, so make sure to talk with one of the project admin's first.

3. Save the document and exit your text editor.

4. One the command line, type "`source .cshrc`" to update the environment variables for the shell that you're currently logged into. All new shells that you open in the future will automatically read this file.

If your shell is /bin/bash, you should:

1. In your home directory, open the file .bashrc in a text editor.

2. Move to the end of the file, and add in the lines:

   `CVSROOT="anonymous@cvs.avida.sourceforge.net:/cvsroot/avida"
   CVS_RSH=ssh
   export CVSROOT
   export CVS_RSH
   `

   Where you replace username with your own account name from myxo. This will set the needed environment variables.

3. Save the document and exit your text editor.

4. One the command line, type "`source .bashrc`" to update the environment variables for the shell that you're currently logged into. All new shells that you open in the future will automatically read this file.

I'm not as familiar with other shells, so if you are using another one, you're on your own.

Test to make sure this worked. Type "`echo $CVSROOT`" on the command line, and make sure the result is the one you entered above. Do the same for "`echo $CVS_RSH`".

### How to use a CVS

Once you have your environment variables straight, the CVS is very easy to use. The way you send a command to the CVS is by typing "`cvs command`" where you replace command by the command you wish to issue. To get a brand new project called "ecoli_racing" out of the CVS, you would type "`cvs get ecoli_racing`". It would pull all of the files from the CVS, and place them in your current directory.

When a project is downloaded from the CVS, it will also create a new sub-directory inside of each project-directory, called CVS/. This lets future CVS commands know the status of all your files and what project they are part of, so you should never need to tell it again.

Here are some of other commands that you can execute inside of a project that you have retrieved from the CVS:

`cvs update` | This command will incorporate all changes anyone else has made in the project since last time you downloaded it. If you have made any changes to the project yourself, it will merge those changes (discussed more below).
`cvs status` | This command will tell you the status of each file in the CVS. It will let you know if you have made changes to it ("locally modified"), if someone else has made changes ("needs update"), or both ("needs merge").
`cvs commit` | You would use this command to commit all of the changes you have made to the sourcecode so that everyone else can use them. Do not do this lightly!!! Remember, that any bugs that are introduced into the code this way will now affect everyone. Fortunately, the CVS has a logging system that will allow us to back out of any problematic changes, but as long as everyone is careful, that shouldn't be necessary.
`cvs diff` | This command will show you any differences between the file that you have and the current version of the file in the CVS.
`cvs help` | Prints a list of all available CVS commands, with a brief description of each.

If you are just using the CVS in order to have the most up-to-date version of avida, than you should never have any problems with it. An occasional "`cvs update`" when you need a newly implemented feature should do the trick. However, if you are going to edit the code (even if you never plan to commit your changes) there are some other things you need to worry about.

In particular, what happens if both you and someone else edit the source code at the same time? Well, in fact the CVS is very good at handling this. If they are two different files, then there is no problem at all. If they are even the same file, but different sections of it, this isn't a problem either -- the CVS will typically merge the changes smoothly and correctly. The real problem is when two people edit the same part of the same file.

When this happens and you try to update, the CVS will say "Warning: conflicts have occured". As the individual files scoll by, it will let you know which ones need to be manually merged. After the update, when you edit the file, you will see that there will be a ">>>>>>>>>>" on one line in the file, followed by your edits, then a "===========" and the other persons edits, and finally a "<<<<<<<<<<<" to indicate the end of the other persons edits. It is now your job to merge your edits with theirs. In the case of avida, I'd be happy to help with this if it ever ends up being a problem. Most of the time this is caused by two people trying to fix the same bug, and you can just choose one edit or the other and either will work just fine.

For more information on the CVS, see this tutorial

Project hosted by: