About CVS

This document explains how to use the Concurrent Versions System (CVS) with the BioCocoa project. To be able to use CVS and contribute code to the BioCocoa project, you will need to have an account at bioinformatics.org, and request to be added to the developer list by the project leader, Peter Schols. You can get more information about the use of CVS with bioinformatics.org projects here.

Getting Started
Setting up ssh keys
Xcode and SVN
Xcode and CVS
Using CVL to perform CVS operations
Moving folders and files
Using CVS from the command-line
Useful links

Getting the BioCocoa project on your computer

To upload/export the BioCocoa project into your computer, open Terminal.app on your machine and make sure that you are using the bash shell by typing bash at the prompt. Now you can excecute the following commands:

First, set these two shell parameters:
```
export CVS_RSH='ssh'
```
```
export CVSROOT=':ext:loginname@bioinformatics.org:/cvsroot'
```
(make sure to replace loginname by your login)
Create a folder on your machine where you want to store the BioCocoa source, e.g.
```
mkdir ~/Desktop/BioCocoa
```
Move to that folder, e.g.
```
cd ~/Desktop/BioCocoa
```
Move the contents of the CVS repository to that folder:
```
cvs checkout BioCocoa -P
```

The entire BioCocoa project will be now be transfered to your local folder. You can monitor what's going on in the Terminal window.

Setting up ssh keys

To be able to use CVS transparently in GUI applications, in particular Xcode and CVL, you will need to set up ssh on your machine and on your account at bioinformatics.org, so that you don't need to type your account password everytime you want to use CVS. After setting this up, you will never be asked for your bioinformatics password anymore. This is how GUI applications can run without having to deal with passwords. One other advantage of doing this is that your scripts will be able to run without human intervention. The disadvantage is that anyone who can access your account on your local Mac OS X box will also be able to access those remote servers which have stored your public key.

Create public/private key pair with the ssh-keygen command

Open Terminal.app on your machine and type the following commands at the prompt:

```
ssh-keygen -t dsa
```
The ssh-keygen process will generate a key pair
```
Enter file in which to save the key:
```
You can choose the proposed file name and path
```
Enter passphrase (empty for no passphrase):
```
Just hit return when you are asked for a passphrase
```
Enter same passphrase again:
```
Hit return a second time.

You will see the following output:

Your identification has been saved in /Users/yourlogin/.ssh/id_dsa.

Your public key has been saved in /Users/yourlogin/.ssh/id_dsa.pub.

The key fingerprint is:

followed by the key that is generated for your local account.

Note that you could choose to type a password, it does not have to be the same as your bioinformatics.org password. However, if you type a password, it will be needed to access your ssh account. This can makes things more complicated, in particular with CVL. You can always change that password or remove it (by replacing it with an empty password), using the command ssh-keygen -p.

Place your public key on the remote host

Once you have created your private and public keys, you need to place your public key on the remote host in a place where ssh and scp can recognize it. For this, add the contents of your local ~/.ssh/id_dsa.pub file to the file called authorized_keys in the ~/.ssh directory in your remote account at bioinformatics.org (if you don't have such file already, you can create it). You can do this by SFTP'ing to your bioinformatics.org account and by creating a .ssh folder in your Home directory and by adding a authorized_keys file to this dir.

Another option is to use the Terminal (I have not tested that):

```
ssh loginname@bioinformatics.org
```
(make sure to replace loginname with your bioinformatics login)
Type your password
```
cd .ssh
```

echo '--...copy paste the line from you local ~/.ssh/id_dsa.pub file...--' >> authorized_keys

(the line you have to copy is very long, make sure it is all on one line)

```
exit
```

If you are going to access the CVS from different machines, you will have to add one line per machine, so make sure you are on a new line when adding another key to the authorized_keys file.

Using SVN in Xcode

Add a section on using Subversion here

Using CVS in Xcode

To be able to use CVS in Xcode, you need to set up a pair of private/public key on your machine and on your account at bioinformatics.org, as described above. Xcode will then be able to connect to the CVS server without asking a password. You can use the built-in SCM support to work on the project and use CVS in Xcode.

To start using CVS in Xcode, double-click the project icon at the top of the 'Groups and Files' view. In the 'General' tab, check the box 'enable SCM' and choose CVS. Click on the edit button to specify to use ssh.

Look into the SCM smart group on the 'Groups and Files' panel on the left. New files and modified files will appear in this group, as indicated by a letter on the left, 'U' for updated (you have an old version), 'M' for modified (you have modified it and may need to commit), 'A' for new files (need to be added first), 'R' for removal, 'C' for conflict,...

The files for the project itself are in the file package 'BioCocoa.pbproj', which contains 'project.pbxproj' and one file per user, e.g. 'username.pbxuser'. The first file is modified every time the project is modified (adding files, changing target settings,...), the second when a user changes her settings. These files will only appear in the 'SCM' smart group, and should be committed to save changes to the project, or the other developers won't have access to the changes.

Things you can NOT do in Xcode, and for which you will have to use another tool (command line or CVL):

add new folders
manipulate files that are not referenced in the project
update new folders created by others
add new folders

Using CVL to perform CVS operations

As an alternative to Xcode, there are other GUI tools available, including CVL, that you can download from here. The following instructions have been tested with version 3.4.7 (b72).

CVL has instructions to use a remote repository like bioinformatics.org. Here are these instructions:

Install the private/public keys as described above, so that CVL can ssh into the repository without a password. The setup is much easier if you did not set a password on the private key. If you did and want to use it, look into CVL help.
In the Repositories window, click on button Add..., choose the Other repository type, and type the following in the Repository root field:
```
:ext:username@bioinformatics.org:/cvsroot
```
(replace username with... your user name). After clicking OK, CVL will try to connect immediately, and fail, as we haven't finished configuring it. Don't worry.
In the Repositories Window, tab Environment, click on Add to add key CVS_RSH with value /usr/bin/ssh.
If you have already checked out the code, you can open the project using the menu Work Area...Open, and select the BioCocoa folder.
Otherwise, in the Repositories Window, click on Checkout, type 'BioCocoa' in the Module field, and choose a location to checkout the project.

Here are the most important items that you will probably use in the menus:

Work Area...Refresh : refresh the display and the icons on the files; to use every time you made changes to the project, or before working on it to check what other developers may have done.
Work Area...Commit Files : commit all the changes.
Work Area...Update Files : update all the files in the whole project to match the most recent version.
File...Commit : commit only the selected files.
File...Mark File for addition : to add a file to the repository (you need to commit then).
File...Mark File for removal : to remove a file from the repository (you need to commit then).

Switch off SCM in Xcode if you want to use CVL. Remember to always close your project in Xcode when you update the project file package itself, as Xcode might otherwise get very confused. Never delete a file in Xcode. Only remove the reference. Then you can mark files for removal and commit using CVL.

Moving files and folders

This is quite complicated with CVS. Read a CVS manual before doing it if you are not familiar with CVS.

Using the command-line for CVS

This is not an attempt to write a tutorial for the use of CVS, the reader is referred to the many excellent tutorials that already exist, most of them freely available through the web. And of course 'man cvs' is your friend. However, there are a few useful tips that are listed below. These instructions assume that the user is familiar with the command line.

Use the -P and -d flags for the 'cvs update' command:
```
cvs update -P -d
```
The -P flag wil prune (remove them from the working copy) empty folders, the -d flag makes sure that new directories added by someone else will also be added to your local repository.
When updating resources in a nib file, you have to realize that a nib-file is actually also a folder. So for instance to update the MainMenu.nib file, you would:
```
cd MainMenu.nib
```
In this folder you will find at least three files: info.nib, classes.nib, and keyedobjects.nib. The first two are regular text files, and can be treated by CVS as source code files. However, the keyedobjects.nib file is a binary file, and need some special attention. To update the changes you will need to issue two commands:
```
cvs update -kb keyedobjects.nib
```
```
cvs commit -m "added cool new feature" keyedobjects.nib
```