Using CVS

A-A-P home page | A-A-P Recipe Executive
--- | ---
Prev |  | Next

# 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.

Prev | Contents | Next
Version Control | Up | Issue Tracking