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