NorduGrid CVS repository Howto (cheat-sheet)

Getting access to NorduGrid CVS

Write to regarding access to the NorduGrid CVS repository: explain in some details what and why you'd like to contribute.

Access is done through SSH so you must generate a public/private key pair if you do not already have that.

The public key should along with a preferred username be sent to waananen@nbi.dk.

It is possible to share use the same keys with both clients on UNIX (eg. openssh) and Windows. On Linux the ssh-keygen utility in openssh can be used to read keys in various formats and export them to formats used by other clients.

Working with NorduGrid CVS

If you are not familiar with CVS, please read appropriate documentation.

You may use any CVS client tool: either a command-line one, or any of existing GUIs (Cervisia, WinCvs are tested).

On Linux, define CVS_RSH and CVSROOT variables as follows (example for Bourne shells):

export CVS_RSH=ssh
export CVSROOT=:ext:cvs.nordugrid.org:/cvs

If you are using a GUI, enter the values corresponding to the above into configuration

.

The main module is nordugrid. To check out the HEAD revision do, e.g.:

cvs -d:ext:cvs.nordugrid.org:/cvs co nordugrid

Commit Policy

It is good practice not to go and change code in other peoples domain without consulting them first.

If you know the responsible person you can contact him/her directly. Otherwise please use the mailing list to discuss changes.

Adding files to CVS

Adding files to the NorduGrid CVS can be a daring task. Now is probably a good time to get acquainted with basic CVS

and Autotools (Autoconf, Automake and Libtool). Most of the following describes good practice and standard CVS and Autotools procedures.

1. There is a set of top-level directories (modules). This cheat-sheet assumes new files are added under those modules. If a new module has to be added, it must be discussed with all the developers.
2. Identify yourself with one of the modules. The list of such can be found, e.g., in the config.in file in the CVS root: check the list MY_SUBDIRS. Let's assume your code will be located inside a directory <dir>
3. Add your files to <dir> in a usual CVS way, e.g.:

   cvs add myfile

4. Edit the file <dir>/Makefile.am so that it takes into account your files. You will always need Makefile.am, even if it only contains a dummy list of files in the directory (EXTRA_DIST list). Makefile.am will be transformed into Makefile by Autotools, by substituting @...@ variables with proper values. Examples of such variables are:
   • @GLOBUS_INCLUDES@, @DEFAULT_GLOBUS_LOCATION@, @GLOBUS_FLAVOR_NAME@
   • @MYSQL_LIBS@, @MYSQL_INCLUDES@
   • @GSOAP_LIBS@, @GSOAP_INCLUDES@, @GSOAP_LOCATION@
   • @VERSION@
   • ...
5. If you'd rather need a subdirectory <ndir> to accommodate your files, then add it, and add the files into it.
6. Create the file <dir>/<ndir>/Makefile.am, which in the simplest case is just your normal Makefile, or, if you are committing interpretable scripts, the file should contain the line listing the contents of <ndir>: $ cat Makefile.am
   mystuff_DATA = README *.pl
   EXTRA_DIST = $(mystuff_DATA)
7. Edit the file <dir>/Makefile.am to take into account existence of the new subdirectory <ndir>. Make sure that <ndir> is listed in the SUBDIRS list: SUBDIRS = dira dirb dirc <ndir>
8. Edit the file configure.in the root CVS directory:
   • find the block starting with AC_OUTPUT(
   • find the lines <dir>/...
   • add below those the new line: <dir>/<ndir>/Makefile
9. If new files are installed the package management systems (RPM, DEB) need to know about them explicitly. Normally your files will belong to an existing sub-package. If you do not think so, then discuss it with the developers. Currently the sub-packages include:
   • client
   • server
   • devel
   • doc
   • gridmap-utils
   • ca-utils
   • monitor
   If you are adding files to say the client package you would have to edit the file config/nordugrid-client-files.in Note that these files go through Autotools substitutions and thus there must be basically no hard-coded paths.

Documentation

Man pages

Did you add a new executable? If so please write a man page. You can use userinterface/man/ngsub.1 as a template. Remember to add this file as well.

Processed documents

Some documents are produced from a source. For example a LaTeX document example.tex could be turned into a PDF document. During the process of generating the document several auxiliary files are created. They should be listed in the appropriate Makefile.am. Example:

CLEANFILES = example.aux example.log

This will remove the files when doing make clean. On the other hand the final documents (eg. PDF files) should not be removed with this command. They should be listed as:

MAINTAINERCLEANFILES = example.pdf

So that only a make maintainer-clean command will remove them. Also the final produced document should be committed to CVS. In this way developers do not need to re-create the documents when doing make clean. Remember to update the PDF file in CVS whenever changes are made to the source file.

Check your modifications

It is a very good custom to ensure that the nightly CVS build succeeds. Therefore you should check your modifications. Copy the whole tree to a temporary directory. Then go to this new copy and do:

$ cd nordugrid
$ ./bootstrap # (Autotools magic)
$ ./configure
$ make dist

If there were no errors you should have a nordugrid-VERSION.tar.gz in the top-level directory. To test the RPM package building do:

rpmbuild -ta nordugrid-VERSION.tar.gz

This assumes that the standard RPM development is setup correctly. If this commands succeeds (writes a src.rpm file) you changes should be fine.

Go back to the checkout directory and commit the files in the usual way.