This is an old revision of the document!


Accessing the FieldTrip source code through CVS

The source code is managed using CVS (Concurrent Versions System) and the repository is hosted on cvs.fcdonders.nl. The following information is aimed at those people that have been granted write access to the CVS repository. Regular users should use the copy on /home/common/matlab/fieldtrip (inside the DCCN) or the copy on the ftp server (outside the DCCN, see download).

The server that is hosting the FieldTrip CVS repository is only accessible through ssh. That means that you can only access the cvs if you have an ssh account. The default account names and passwords for people working at the DCCN are the same as for the SSH tunnel server. External contributors can apply for an account by sending Robert an email.

To test the access, you should try the following

ssh yourname@cvs.fcdonders.nl

After logging in on the cvs server using ssh, you can change your password with the “passwd” command.

Checking out a local copy -> your working version

On the first checkout you should specify the location of the cvs server. That can be done either with the CVSROOT environment variable, or on the command line itself.

General options are specified like this

CVS [OPTION] command module/file

The command specific options come after the command, like this

cvs command [OPTIONS] module/file

The location of the repository is a general option (-d). So the first time you check out something, it looks like this

export CVS_RSH=ssh
export CVSROOT=:ext:username@cvs.fcdonders.nl:/home/cvsroot
cvs checkout fieldtrip

After the first checkout, you normally would do “cvs update” inside the directory itself. Once checked out, the directory remembers where the cvs repository is, so therefore you only have to specify it once.

The cvs command-line program requires two environment variables to be set: CVSROOT and CVS_RSH. The “export CVS_RSH” command has to be done every time you start a new linux session. The second “export CVSROOT” command only has to be done when you check out something from CVS, which happens only once. Subsequent “cvs update” commands don't need it. You can include the two export commands in your bashrc script.

Commit your changes to existing code to the repository

If you have modified a function, you should send the modifications to the repository like this

cvs commit existingfunction.m

The cvs command will then ask you to write a log message. In the log message you should indicate what you changed. The default editor for writing the log message is vi, which is a very powerful, but also slightly user-unfriendly editor. Once in vi, you should press the “i” button, type the text you want, press escape, type “:wq” and the log message will be recorded. See http://www.linuxjournal.com/article/6542 for a getting started with vi document.

In general it is wise to carefully check the changes prior to committing. You can check the difference between your present working version and the version in the repository like this:

cvs diff existingfunction.m

So in general the safe way of committing your changes to the function is by typing

cvs diff existingfunction.m

cvs commit existingfunction.m

Add a new file to the repository

If you create a new function, you have to add it to the repository like this:

cvs add newfunction.m
cvs commit newfunction.m

The CVS repository layout and the release version directory layout are not identical. The release version of FieldTrip is “built” from the CVS repository using a release script. This script copies the functions from cvs and while copying, it moves them to the appropriate location. Some of the helper functions are required at multiple locations, such as the keyval function (which is present in fieldtrip/private, fieldtrip/forwinv/private and in fieldtrip/fileio/private). All functions are only present once in CVS, the release script creates the multiple copies. That ensures that all copies are always identical to each other.

Building the release versions (i.e. copying all the files to the appropriate location) is done by a set of Linux shell scripts that is present in the release module. The shell scripts are executed automatically in a cronjob. The ftp release version is built once every evening and copied to the ftp server, the inhouse DCCN version is built every 10 minutes and updated on /home/common.

FieldTrip is organized in modules. In the release system the modules are combined, so most FieldTrip users will see FieldTrip as one single coherent package. To avoid code duplication and to allow the contributers to FieldTrip write access to particular pieces of the code, on the CVS repository the code is managed in a structure that follows these modules. For each of the modules there is a corresponding UNIX group that has write access to the corresponding directory in the CVS root directory.

At this moment there are the following modules

Module name Location on the CVS server Location in the FieldTrip release
fieldtrip /home/cvsroot/fieldtrip fieldtrip
fileio /home/cvsroot/fileio fieldtrip/fileio
forwinv /home/cvsroot/forwinv fieldtrip/forwinv
preproc /home/cvsroot/preproc fieldtrip/preproc
specest /home/cvsroot/specest fieldtrip/specest
realtime /home/cvsroot/realtime fieldtrip/realtime
buffer /home/cvsroot/buffer fieldtrip/realtime/buffer
openmeeg /home/cvsroot/openmeeg fieldtrip/external/openmeeg
ctf /home/cvsroot/ctf (*) fieldtrip/external/ctf
yokogawa /home/cvsroot/yokogawa (*) fieldtrip/external/yokogawa
besa /home/cvsroot/besa (*) fieldtrip/external/besa
bci2000 /home/cvsroot/bci2000 (*) fieldtrip/external/bci2000
release /home/cvsroot/release (**)
roboos /home/cvsroot/roboos (***)
classification /home/cvsroot/classification (****) fieldtrip/classification

(*) These external ctf, yokogawa, bci2000 and besa directories contain a copy of the external proprietor specific source code. For ctf and yokogawa, the FieldTrip release version contains p-files (pre-compiled matlab functions). For bci2000 the release version contains mex files.

(**) The release directory on the CVS server does not contain FieldTrip code, but contains the shell scripts that are used for the release management. These scripts copy the individual files from the respective CVS directories to the appropriate directories for the release version. They also make sure that all shared helper functions are located in the private directories.

(***) The roboos directory on the CVS server contains a variety of low-level functions, split over multiple subdirectories. Typically these files will end up in the release version in the private directories. These files are at the moment still only managed by Robert Oostenveld, but will in the future be moved to more appropriate directories in the CVS structure.

(****) The version management of the classification module is done by Marcel van Gerven outside of the CVS server. Merging the classification code into the FieldTrip release system is achieved using rync in a cron job.

The FieldTrip project does not give anonymous access to the CVS server. All access to the server is through ssh accounts that are registered and linked to a particular contributor. Anonymous users of the FieldTrip code should download the latest version of the ftp server.

Assuming that you have a ssh account on the CVS server and that you have checjed that account (see above), the following commands show how to checkout a new working copy of some example sections of the source code:

export CVS_RSH=ssh
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout fieldtrip
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout fileio
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout forwinv
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout preproc
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout specest
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout openmeeg
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout ctf
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout yokogawa
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout bci2000
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout besa
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout realtime
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout buffer
cvs -d :ext:yourname@cvs.fcdonders.nl:/home/cvsroot checkout release
...

Note that you may not be able to check out each module in the list above. Probably you have been given read&write access only to a limiter number of modules, which implies that you can only checkout those modules.

The first line ensures that the cvs client program uses ssh instead of the default rsh. To prevent having top type the “export CVS_RSH=ssh” every time, you can add that line to to your “.bashrc” file. You can do that with a text editor, or using the following command

echo "export CVS_RSH=ssh" >> ~/.bashrc

After adding this to your .bashrc, you should log out and log in again.

After checking out a working copy of the FieldTrip source code, you may want to reorganize the directory structure to make it more resemble the release version. That can be done manually by just moving the directories, or using the following code:

mv forwinv  fieldtrip
mv fileio   fieldtrip
mv preproc  fieldtrip
mv specest  fieldtrip
mv release  fieldtrip
mv realtime fieldtrip
mv buffer   fieldtrip/realtime
mkdir -p    fieldtrip/external
mv ctf      fieldtrip/external
mv yokogawa fieldtrip/external
mv bci2000  fieldtrip/external
mv besa     fieldtrip/external
mv openmeeg fieldtrip/external

If you already have a checked out version of the source code from the old location (which used to be /home/commmon/matlab/cvsroot), you do not have to check out again. There are two CVS administrative files in each directory that you can modify to point to the new repository:

your_path/fieldtrip/CVS/Root               should contain the line ":ext:yourname@cvs.fcdonders.nl:/home/cvsroot"
your_path/fieldtrip/CVS/Repository         should contain the line "fieldtrip"
your_path/fieldtrip/private/CVS/Root       should contain the line ":ext:yourname@cvs.fcdonders.nl:/home/cvsroot"
your_path/fieldtrip/private/CVS/Repository should contain the line "fieldtrip/private"

I.e., in the Root file, you should change the path to the old repository to the new one, including the “:ext:yourname@cvs.fcdonders.nl:” section for the server.

To prevent that you have to type your password ever time you do “cvs update” or “cvs commit”, you can exchange your ssh keys between the mentats and the cvs server. That is explained in more detail on the DCCN intranet.

Frequently asked questions