Chapter 17. Using CVS


A common way to distribute sources and working together on them is using CVS.
This requires a certain way of working.  The basics are explained here.  For
more information on CVS see http://www.cvshome.org.

Obtaining a module

The idea is to hide the details from a user that wants to obtain the module.
This requires making a toplevel recipe that contains the instructions.  Here
is an example:

	CVSROOT = :pserver:anonymous@cvs.myproject.sf.net:/cvsroot/myproject
	:child mymodule/main.aap {fetch = cvs://$CVSROOT}
	fetch:
		:fetch {fetch = cvs://$CVSROOT} mymodule

Executing this recipe will use the "fetch" target.  The ":fetch" command
takes care of checking out the whole module "mymodule".

Note that this toplevel recipe cannot be obtained from CVS itself, that has a
chicken-egg problem.

Fetching

The child recipe "mymodule/main.aap" may be totally unaware of coming from a
CVS repository.  If this is the case, you can build and install with the
recipe, but not fetch the files or send updates back into CVS.  You need to
use the toplevel recipe above to obtain the latest updates of the files.  This
will then update all the files in the module.  However, the toplevel recipe
itself will never be fetched.

To be able to fetch only some of the files of the module, the recipe must be
made aware of which files are coming from CVS.  This is done by using an
"fetch" attribute with a URL-like specification for the CVS server: {fetch
= cvs://servername/dir}.  Since CVS remembers the name of the server, leaving
out the server name and just using "cvs://" is sufficient.  Example:

	SOURCE = foo.c version.c
	INCLUDE = common.h
	TARGET = myprogram
	:attr {fetch = cvs://} $SOURCE $INCLUDE

If you now do "aap fetch" with this recipe, the files foo.c, version.c and
common.h will be updated from the CVS repository.  The target myprogram isn't
updated, of course.

Note: When none of the used recipes specifies a "fetch" target, one will be
generated automatically.  This will go through all the nodes used in the
recipe and fetch the ones that have an "fetch" attribute.

The recipe itself may also be fetched from the CVS repository:

	:recipe {fetch = cvs://}

When using files that include a version number in the file name, fetching
isn't needed, since these files will never change.  To reduce the overhead
caused by checking for changes, give these files a "constant" attribute (with
a value non-empty non-zero value).  Example:

	PATCH = patches/fix-1.034.diff {fetch = $FTPDIR} {constant}

To update a whole directory, omit the "fetch" attribute from individual files
and use it on the directory.  Example:

	SOURCE = main.c version.c
	TARGET = myprog
	:attr {fetch = cvs://} .

Alternatively, a specific "fetch" target may be specified.  The automatic
updates are not used then.  You can specify the "fetch" attribute right
there.

	fetch:
		:fetch {fetch = cvs://} $SOURCE

If you decided to checkout only part of a module, and want to be able to get
the rest later, you need to tell where in the module to file can be found.
This is done by adding a "path" attribute to the cvs:// item in the fetch
attribute.  Example:

	fetch:
		:fetch {fetch = $CVSROOT {path = mymodule/foo}} foo.aap

What will happen is that aap will checkout "mymodule/foo/foo.aap", while
standing in two directories upwards.  That's required for CVS to checkout the
file correctly.  Note: this only works as expected if the recipe is located in
the directory "mymodule/foo"!
If the "path" attribute is omitted, A-A-P will obtain the information from the
"CVS/Repository" file.  This only works when something in the same directory
was already checked out from CVS.


Checking in

When you have made changes to your local project files and want to upload them
all into the CVS repository, you can use this command:

	:cvsdist {file} ... {server}

The list of files must include _ALL_ the files that you want to appear in CVS
for the current directory and below.  Files that were previously not in CVS
will be added ("cvs add file") and missing files are removed ("cvs remove
file").  Then all files are committed ("cvs commit file").

To be able to commit changes you made into the CVS repository, you need to
specify the server name and your user name on that server.  Since the user
name is different for everybody, you must specify it in a recipe in your
~/.aap/startup/ directory.  For example:
	
	CVSUSER_AAP = foobar

The name of the variable starts with "CVSUSER" and is followed by the name of
the project.  That is because you might have a different user name for each
project.

The method to access the server also needs to be specified.  For example, on
SourceForge the "ext" method is used, which sends passwords over an SSH
connection for security.  The name used for the server then becomes:

	:ext:$CVSUSER_AAP@cvs.a-a-p.sf.net:/cvsroot/a-a-p

You can see why this is specified in the recipe, you wouldn't want to type
this for commiting each change!


DISTRIBUTING YOUR PROJECT WITH CVS

This is a short how-to that only explains how to distribute a set of files
(and directories) using CVS.

1. Copy the files you want to distribute to a separate directory

    Mostly you have various files in your project for your own use that you
    don't want to distribute.  These can be backup files and snippets of code
    that you want to keep for later.  Since CVS imports all files it can find,
    best is to make a copy of the project.  On Unix:
    
    	cp -r projectdir tempdir

    Then delete all files you don't want to distribute.  Be especially careful
    to delete "aap" directories and hidden files (starting with a dot).  It's
    better to delete too much than too few: you can always add files later.

2. Import the project to the CVS repository

    Move to the newly created directory ("tempdir" in the example above).
    Import the whole tree into CVS with a single command.  Example:

	cd tempdir
    	cvs -d:ext:myname@cvs.myproject.sf.net:/cvsroot/myproject import mymodule myproject start

    Careful: This will create at least one new directory "mymodule", which you
    can't delete with CVS commands.
    This will create the module "mymodule" and put all the files and
    directories in it.  If there are any problems, read the documentation
    available for your CVS server.

3. Checkout a copy from CVS and merge

    Move to a directory where you want to get your project back.  Create the
    directory "myproject" with this example: 

    	cvs -d:ext:myname@cvs.myproject.sf.net:/cvsroot/myproject checkout mymodule

    You get back the files you imported in step 2, plus a bunch of "CVS"
    directories.  These contain the administration for the cvs program.  Move
    each of these directories back to your original project.  Example:

    	mv myproject/CVS projectdir/CVS
    	mv myproject/include/CVS projectdir/include/CVS

    If you have many directories, one complicated command does them all:

	cd myproject
    	find . -name CVS -exec mv {} ../projectdir/{} \;

4. Publish changes

    After making changes to your project and testing them, it's time to send
    them out.  In the recipe you use for distribution, add one command that
    will publish all the files by updating the module in CVS server.  Example:

	FILES = $SOURCE $INCLUDE main.aap
    	:publishall {publish = :ext:$CVSUSER_MYPROJECT@cvs.myproject.sf.net:/cvsroot/myproject} $FILES

    Careful: $FILES must contain all files that you want to publish in this
    directory and below.  If $FILES has extra files they will be added in CVS.
    Files missing from $FILES will be removed from CVS.
    You must assign $CVSUSER_MYPROJECT your user name on the CVS server.
    Usually you do this in one of your personal A-A-P startup files, for
    example "~/.aap/startup/main.aap".


USING SOURCEFORGE

If you are making open source software and need to find a place to distribute
it, you might consider using SourceForge.  It's free and relatively stable.
They provide http access for your web pages, a CVS repository and a server for
downloading files.  There are news groups and maillists to support
communication.  Read more about it at http://sf.net.

Since you never know what happens with a free service, it's a good idea to
keep all your precious work on a local system and update the files on
SourceForge from there.  If several people are updating the SourceForge site,
either make sure everyone keeps copies, or make backup copies (at least
weekly).

You can use A-A-P recipes to upload your files to the SourceForge servers.  To
avoid having to type passwords each time, use an ssh client and put your
public keys in your home directory (for the web pages) or on your account
page (for the CVS server).  Read the SourceForge documentation for how to do
this.

For uploading web pages you can use a recipe like this:

	FILES =	index.html
		download.html
		news.html
		images/logo.gif
	:attr {publish = scp://myname@myproject.sf.net//home/groups/m/my/myproject/htdocs/%file%} $FILES

Start this recipe with the "publish" target.

For sourceforge, set environment variable CVS_RSH to "ssh".  Otherwise you
won't be able to login.  Do "touch ~/.cvspass" to be able to use "cvs login"
Upload your ssh keys to your account to avoid having to type your password
each time.