Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Repository Conventions Up: Data Repository Previous: Repository Structure

Subsections

Contributing to the Repository

This section describes how to setup and use CVS to contribute to the repository. While it introduces the basic CVS commands, it is not intended as a substitute for existing CVS documentation, e.g. the CVS support page at cyclic.com. Standard CVS documentation should be consulted before attempting to contribute to the repository for the first time.

Setup CVS

It is more difficult to setup things to contribute to the AIPS++ data repository than to mirror it. The first requirement is that the user must have an account on the AIPS++ central server, aips2.nrao.edu, and the user id on aips2.nrao.edu must be a member of the aips2prg group. In addition, CVS and SSH must be installed on your local system. These packages are widely available.

With ssh you create your pair of keys using ssh-keygen. This will create ~/.ssh/identity.pub on your local machine (or ~/.ssh/id_dsa.pub for ssh2 based versions) You then add the contents of this file to ~/.ssh/authorized_keys (~/.ssh/authorized_keys2 for ssh2 based) on aips2.nrao.edu.Make sure authorized_keys is readable only by the user. After that, you are ready to try ssh; try something like:

   yourhost% ssh aips2.nrao.edu which cvs
yourhost% ssh aips2.nrao.edu which co

from your local machine. You must get these to return the path to the cvs and co binaries before going further. These binaries are located in /opt/local/gnu/bin on aips2.nrao.edu. To make this path available, you may need to edit ~/.ssh/environment on aips2.nrao.edu, and add a line like:

    PATH=/usr/bin:/opt/local/bin:/opt/local/gnu/bin

Shell variables, e.g. $PATH, are not expanded.

Once you have resolved all of the problems involved with running remote commands on aips2.nrao.edu, you are ready to check out a piece of the data repository. First you must tell your local cvs installation to go to aips2.nrao.edu for the repository and to use ssh instead of rsh to run remote commands. For the Bourne-like shells, you do this like:

    yourhost% CVS_RSH=ssh
yourhost% CVSROOT=:ext:aips2.nrao.edu:/aips++/cvs
yourhost% export CVS_RSH CVSROOT

for C-like shells, you would do:

    yourhost% setenv CVS_RSH ssh
yourhost% setenv CVSROOT :ext:aips2.nrao.edu:/aips++/cvs

Now to check out a piece of the source from which the data repository is built, you would do something like:

    yourhost% cvs co data/nrao

This would check out the data specific to NRAO. Unlike RCS, when you check out files from CVS the files are not locked. Other users can check out and check in changes to the same files. Checking out the files just provides a copy of the current state of the files to work with. Any conflicts between your changes and changes which have occurred since you checked out the files are addressed at check in time (actually cvs update time).

Using CVS

The format for running CVS commands is:

   yourhost% cvs <COMMAND> <OPTIONS>

As shown above, the command for checking out code is co (abbreviation for checkout). The command for adding new files or directories is add. The command for checking in changes to files is commit. diff is used to print the differences between a local copy and the version resident in the repository.

All commands in CVS are recursive by default. So if you wanted to list all of your changes, you would go to the top of the tree and run:

   yourhost% cvs diff .

which says give me the difference in this directory including every directory beneath this directory.

When you check out files, you can check out all of the repository source:

   yourhost% cvs co data

or only a small portion:

   yourhost% cvs co data/geodetic/IGRF

After you have had code checked out for some time, you may want to bring it up to date with the current state of the code in the CVS repository. You use update to do this, e.g.

   yourhost% cvs update .

update will not trample over your changes. It updates all files files which have not been modified, and where possible it merges in differences to files which you have modified without any problems. Where conflicts occur, it includes your changes and other changes in a diff-like format. When you get a warning about this problem, you must edit the file by hand and reconcile your changes and the other changes.

For more information about CVS, see the support page at cyclic.com.

CVS Example

Checking out a portion of the data repository is the first step toward contributing to the repository. Whether you plan to modify existing data, check-in new data, or remove data, you must first checkout that portion of the repository which you plan to change. As an example, lets assume that we want to check in test data for a new AIPS++ package, foobar. The data we are adding is a table, footest1. So we first checkout the demo portion of the data repository:

    yourhost% cvs co data/demo

This creates a workspace where we can make changes.

Next since foobar tests will need multiple data sets, we want to create the directory to group these data sets:

    yourhost% cd data/demo
yourhost% mkdir foobar
yourhost% cvs add foobar

As discussed in section §4.4, makefile rules for installing tables from the data repository source tree to the repository tree which is exported to end users depend on the actual table being below a directory of the same name. In our case, the tree looks like:

    data                             workspace root directory
    |
    +- demo                          all test and demo data
       |
       +- foobar                     all of our foobar test data
          |
          +- footest1                makefile to install footest1
             |
             +- footest1             actual footest1 data

This duplication of the table (footest1) is done because unlike our simple example some tables are automatically updated with scripts run by the makefiles found in the first level directory, i.e. there is no lower level directory in the data repository source tree.

So we create a footest1 directory which will contain the actual table as well as a makefile to install our table in the export area.

    yourhost% cd foobar
yourhost% mkdir footest1
yourhost% cvs add footest1

We also create a simple makefile which will install our table from the repository source tree to the export tree. It looks like:

    DATA_THISDIR  := $(shell pwd | sed -e 's=^/tmp_mnt/=/=')
    DATA_ROOT := $(shell echo $(DATA_THISDIR)/ | sed -e '{s@/data/.*$$@/data@;}')
    include $(DATA_ROOT)/config/makedefs/basic
    include $(DATA_ROOT)/config/makedefs/install.table

This is also discussed in section §4.4. In the footest1 directory just created, we check in this makefile and our table (which we copy for our work area):

    yourhost% cd footest1
yourhost% cp ../../glishtutorial/t1/makefile .
yourhost% cvs add makefile
yourhost% mkdir footest1
yourhost% cvs add footest1
yourhost% cd footest1
yourhost% cp ~/footest1/table.* .
yourhost% cvs add table.*

Here, the standard table makefile was copied from a table already in the repository, and the table contents were copied from elsewhere, i.e. ~/footest1.

Using add schedules the files for addition to the repository, but none are actually added until we do a commit:

    yourhost% cd ../../..
yourhost% cvs commit -m 'initial check-in of foobar' foobar

The cd gets us to the demo directory, the -m on the commit line supplies the log message and the foobar at the end of the line indicates that the foobar subdirectory and all of its contents should be committed to the repository. After all of this completes successfully, we are through with this workspace (created with the initial cvs co). It can be deleted if it is no longer needed.

Next: Repository Conventions Up: Data Repository Previous: Repository Structure Contents Index