How to Download Software With GNU arch
GNU arch is a version control system which is also suitable for software distribution. This memo describes how you can obtain software from the archives stored at arch.enyo.de.
Overview
GNU arch
is a version control system. It is part of the GNU project. I use GNU arch to distribute development versions of my software (and some software that is production-ready, but which I haven't properly released yet).
For generic compilation instructions after you have obtained the source code, refer to the separate How to Compile Downloaded Software document.
Obtaining GNU arch
There are multiple implementations of the arch software. Tom Lord initially wrote a shell script variant called larch. His current C implementation (which is the most widely used implementation) is called tla, or GNU arch.
As of this writing, tla comes in two different versions, the stable 1.0 release and the 1.1 development branch. The 1.0 release lacks some features (such as star merge) which are very convinent in distributed development. Therefore, this memo assumes that you are using the 1.1 branch.
The latest version of GNU arch is available at:
The tarball includes instructions for compiling and installing tla. I usually store the tla binary in /opt/tla and use the following commands to compile and install tla:
$ tar xzf tla-version.tar.gz $ cd tla-version $ cd src $ mkdir =build $ cd =build $ ../configure --prefix=/opt/tla output from ../configure $ make output from make $ make test output from the test suite $ sudo make install Password: log of installation $
Please note that the =build part is crucial; the packaging framework requires a separate build directory.
Initial configuration of tla
Before you can use tla to access remote software archives, you have to perform a few configuration tasks.
Choose your own identity
As a first step, you have to tell tla your identity. (This is required as soon as you create any archive, even if it is a local mirror of a remote archive.) By convention, your identity is your full name, followed by your email address.
$ tla my-id "Hank Mustermann <mustermann@example.com>" $ tla my-id Hank Mustermann <mustermann@example.com> $
Don't worry, this won't publish your email address. However, if you use tla to publish changes, this address will be published, too. This address is not used by tla itself; it just has to be unique among all users and developers. Other developers might send questions, bug reports or code contributions to that address, so it's best to use a working (and stable!) email address nevertheless.
Choose a directory for storing archives
Somewhere in your file system, tla must store archive data. (Every active developer who uses GNU arch needs write access to at least one archive to store his or her changes.) Even if you don't want to start development using GNU arch at once, this directory will be used to keep local mirrors of remote archives. This way, you can use GNU arch even if you don't have Internet access, or the archive server is down.
Let's assume you want to store your archives in the archives subdirectory of your home directory, so let's create it:
$ mkdir ~/archives $
You can use another directory name if you like (such as .archives, to hide it in directory listings). You also don't have to keep all your archives in a single directory.
Registering and mirroring a remote archive
Before you can access a remote archive, you must register it and tell GNU arch about its existence. (Currently, there isn't any naming service like DNS that would automate that step.) In the commands below, I assume that you want to register and mirror my main archive at arch.enyo.de, called fw@deneb.enyo.de--2003-public. The mirror copy is stored in a subdirectory of the ~/archives directory you created in the previous section.
$ tla register-archive fw@deneb.enyo.de--2003-public-SOURCE \
http://arch.enyo.de/fw@deneb.enyo.de--2003-public
$ tla make-archive \
--mirror-from fw@deneb.enyo.de--2003-public-SOURCE \
~/archives/fw@deneb.enyo.de--2003-public
$
The name fw@deneb.enyo.de--2003-public is opaque to GNU arch; it does not try to parse the embedded email address or contact a host under that domain. The -SOURCE suffix indicates the mirroring direction.
The two commands above do not transfer any files; to do that you have to explicitly trigger a mirroring operation. If you want to make a full copy of my archive, do not select any categories (projects stored in an archive):
$ tla archive-mirror fw@deneb.enyo.de--2003-public * mirroring fw@deneb.enyo.de--2003-public-SOURCE to fw@deneb.enyo.de--2003-public with limit (null) ** adding category bgpdns ** adding branch bgpdns--devo ** adding version bgpdns--devo--0.1 ** adding revision bgpdns--devo--0.1--base-0 ** adding revision bgpdns--devo--0.1--patch-1 more output follows $
In most cases, you'll be justed interested in a selected part of the archive, for example my doscan project. In this case, you can restrict the mirror to this part of the archive, using a command like this:
$ tla archive-mirror fw@deneb.enyo.de--2003-public doscan * mirroring fw@deneb.enyo.de--2003-public-SOURCE to fw@deneb.enyo.de--2003-public with limit doscan ** adding category doscan ** adding branch doscan--devo ** adding version doscan--devo--0.1 ** adding revision doscan--devo--0.1--base-0 ** adding revision doscan--devo--0.1--patch-1 ** adding revision doscan--devo--0.1--patch-2 more output follows $
Each time you want to access an updated remote archive, you have to manually issue a tla archive-mirror command. This is a bit cumbersome, but can be easily automated using a script.
If you just want to grab a single revision (and do not plan to follow development), creating a mirror is overkill. In this case, just register the archive with its remote location:
$ tla register-archive fw@deneb.enyo.de--2003-public \
http://arch.enyo.de/fw@deneb.enyo.de--2003-public
$
In this case, there's no need to periodically mirror the archive, either.
Extracting source code to a project tree
So far, you have only worked with entire archives and parts thereof. Now it's time to actually obtain some source code! Suppose you want to download the most recent development version of doscan. Change to a suitable directory and issue:
$ tla get fw@deneb.enyo.de--2003-public/doscan--devo * from import revision: fw@deneb.enyo.de--2003-public/doscan--devo--0.1--base-0 * patching for revision: fw@deneb.enyo.de--2003-public/doscan--devo--0.1--patch-1 * patching for revision: fw@deneb.enyo.de--2003-public/doscan--devo--0.1--patch-2 lots of patches follow * patching for revision: fw@deneb.enyo.de--2003-public/doscan--devo--0.2--patch-60 * making pristine copy * tree version set fw@deneb.enyo.de--2003-public/doscan--devo--0.2 $
Note that the checkout directory has been named after the latest revision:
$ ls -d doscan--* doscan--devo--0.2--patch-60 $
We could have avoided that if we explicitly specified a directory as an argument to tla get:
$ tla get fw@deneb.enyo.de--2003-public/doscan--devo doscan
You can also rename the directory after calling tla get.
For generic instruction on compiling the software in the project tree, refer to the How to Compile Downloaded Software document.
Staying up-to-date
There are two basic ways of merging changes of the remote archive into your checked-out project tree, update and replay. Update first undos all your local changes, then applies the remote changes, and then redos your local changes. Replay just applies the remote changes to your project tree, which might carry local changes.
However, first you have to update your mirror. We assume that you want t follow doscan development, so you mirror only that part of my archive:
$ tla archive-mirror fw@deneb.enyo.de--2003-public doscan archive-mirror output omitted $
We assume that you want to use update (and not replay). Update has the advantage that your local changes conflict with the remote ones, and not vice versa, so you are somewhat less likely to lose remote changes (with which you might be less familiar). In order to start the merge, change to some directory within your project tree (it doesn't need to be the top-level directory) and issue this command:
$ tla update * setting aside local changes temporarily * linting the source tree * reverting changes M Makefile.in * updating for new patches in archive * finding or making doscan--devo--0.2--patch-50 * finding or making doscan--devo--0.2--patch-60 * computing changeset lots of changes here * changeset: ./,,apply-delta-changeset.1071445572.18181.15 * applying changeset still more changes * reapplying local changes * linting the source tree M Makefile.in $
In this case, the file Makefile.in was locally modified, and as the output shows, these changes were temporarily undone while the tree was updated.
If you want to use replay instead of update, just replace tla update with tla replay. (Replay is generally faster because no changeset has to be computed.)
A few notes on GNU arch revision names
If you start getting used to GNU arch, you will see more identifiers of the form fw@deneb.enyo.de--2003-public/doscan--devo--0.2--patch-60. Such names are also called revisions or full revision names (to distinguish them from the last part, see below), and they are structered as follows:
The first part, "
fw@deneb.enyo.de--2003-public" in the example above, extends up to the first slash character "/". It contains the archive name. (The archive name, although usually structured according to GNU arch conventions, is not further parsed by GNU arch.) If you omit the archive part of a revision, GNU arch tries to use a reasonable default.After the slash, the remaining parts are separated by pairs dashes "--". The first of these parts is called the category. Usually, it's the name of the software project. Here it's "
doscan".The next part, "
devo", describes a branch. Like categories, all branches are equal, and there is no default branch. That's the reason why you cannot omit branch names (and category names). The development branch (with the most recent code) is often called "devo", but this is not enforced by GNU arch.Now a version number follows ("
0.2" in our example). Versions ared ordered: Versions with an equal number of components are arranged in the usual lexicographic order ("0.2" is more recent than "0.1"). If the number of components is different, and one version is a prefix of another one, the version with the shorter prefix is more recent. (This contradicts the traditional GNU scheme of assigning version numbers, therefore it's better to avoid this situation). In the remaining case, versions are ordered lexicographically.You can omit the version part in revision names. In this case, GNU arch will choose the most recent version. In GNU arch, version numbers only increment if the developer requests such a changes, and they are never automatically assigned, so they can be used reliably to identify separate development processed as reflected by official version numbers.
The last component, "
patch-60", is called the revision. It reflects the patch level within that particular revision. If omitted, the default is the most recent revision.
Where to go from here
If you need more information on GNU arch, refer to the official GNU arch homepage, in particular the tutorial. It covers other important parts of GNU arch, in particular committing changesets to archives.
Revisions
2003-12-14: published