Since arch is relatively new, its documentation tends toward the general and the architectural. Tutorials are getting better, and lately the gnu-arch wiki has become an invaluable resource. The following documents are very useful:
So download arch and start reading this tutorial. We hope to keep it strictly relevant to the lnx-bbc project.
To start with, here's the nickel tour for using arch the same way you used to use CVS:
$ tla my-id "My Name <my-email@my-hostname.tld>" $ gpg --gen-key $ mkdir ~/.arch-params/signing/ $ echo 'gpg --default-key "<haesslich@lnx-bbc.com>" --clearsign' > ~/.arch-params/signing/\=default $ echo '/usr/bin/tla-gpg-check gpg_command="gpg --keyserver subkeys.pgp.net --keyserver-options auto-key-retrieve --verify-files -"' > ~/.arch-params/signing/\=default.check
$ tla register-archive sftp://haesslich@arch.lnx-bbc.com/var/www/arch/ $ tla get lnx-bbc-devel@zork.net--gar/lnx-bbc--stable $ tla get lnx-bbc-devel@zork.net--gar/lnx-bbc--research
$ tla update
$ tla commit
That should get you on your feet. To reap the benefits of the distributed workflow that arch allows, read on for the $7 tour.
This section assumes that you have a gargoyle account and are in the src group. That means that you were using CVS to do LNX-BBC development before.
Before you begin playing with arch, it is important to register your e-mail with the client configuration. For example:
$ tla my-id "Ugly Troll <haesslich@zork.net>"
To see if you already have this configured, just run "tla my-id" at the shell.
All examples from here on out will use the mythical user "haesslich".
In CVS, we had two branches: STABLE and HEAD. Of these, HEAD was sort of the "trunk", and STABLE was a more restricted branch off of it. Arch treats all branches as peers, and you will find yourself making new branches in much the same way that you make new directories to store data associated with discrete tasks.
The two official branches on gargoyle are called "stable" and "research", and correspond to STABLE and HEAD from CVS, respectively. The full descriptors right now are lnx-bbc--stable--2.1 and lnx-bbc--research--0.0. Stable was built by first importing RELEASE_lnx-bbc_2_1 to form lnx-bbc--stable--2.1--base-0, and then brought up to the latest STABLE CVS state to form lnx-bbc--stable--2.1--patch-1. Thus, it can be considered to be "version 2.1 patch-level 1" on the road to 2.2 or 3.0.
The branches on gargoyle make use of arch's gnupg support. This means that no checkins to the two official branches will be accepted without a gpg signature! Thus, there are a few steps to take before you begin working with the official branches.
Also, you ought to have gnupg 1.2 or better in order to have the keyserver functions we make use of. If you're running debian stable, consider adding the following line to your /etc/apt/sources.list:
deb http://www.backports.org/debian stable tla gnupg
This is how gargoyle gets its copies of arch and gpg.
We plan to generate a keyring just for the lnx-bbc project, and use that to verify changeset signatures. You ought to make a fresh new key for the lnx-bbc project. We recommend using your @lnx-bbc.com address (the username is your username on gargoyle), since it is somewhat of a role account.
$ gpg --gen-key
I made mine DSA-only, since it is only used for signatures and not encryption.
$ mkdir ~/.arch-params/signing/ $ echo 'gpg --default-key "<haesslich@lnx-bbc.com>" --clearsign' > ~/.arch-params/signing/\=default $ echo '/usr/bin/tla-gpg-check gpg_command="gpg --keyserver subkeys.pgp.net --keyserver-options auto-key-retrieve --verify-files -"' > ~/.arch-params/signing/\=default.check
For your signed changes to be verified by other developers your public key needs to be available on a keyserver. Here's how you put your key on the server:
$ gpg --keyserver subkeys.pgp.net --send-keys haesslich@lnx-bbc.com
Now you're ready to start grabbing sources.
Arch uses a naming scheme that is, truth be told, somewhat overengineered. Archives (think repositories in CVS) are of the form e-mail@host--some-name, so we use the lnx-bbc-devel list as the e-mail, and "gar" for the name. Simply register this archive name with an sftp (ftp over SSH) URI, and you'll have remote access to the archive using the same credentials you used to use for CVS.
$ tla register-archive sftp://haesslich@arch.lnx-bbc.com/var/www/arch/
$ tla abrowse lnx-bbc-devel@zork.net--gar
lnx-bbc-devel@zork.net--gar
lnx-bbc
lnx-bbc--research
lnx-bbc--research--0.0
base-0 .. patch-1
lnx-bbc--stable
lnx-bbc--stable--2.1
base-0 .. patch-1
This may be slow for you, since gargoyle is on a badly lagged network. Fortunately, that is less of a handicap with arch than it was with CVS!
$ tla get lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1
You should have a directory now with a name like "lnx-bbc--stable--2.1--patch-1". Feel free to move it to a more manageable name, or you can specify the directory name as the second option to "tla get".
Arch updates working trees pretty much just like CVS does.
$ cd lnx-bbc--stable--2.1--patch-1 $ tla update
It is possible at this point for you to edit a file and simply "tla commit", if you are in a big hurry. This has the advantage of being the most CVS-like, and probably the most familiar to you.
Doing things that way, however, deprives you of many of the features arch offers. The workflow for an arch project is much more distributed, and allows you to leave several sub-projects and lines of development simmering in parallel.
First you should make an archive to store your personal branches in.
$ tla make-archive --listing haesslich@zork.net--projects ~/.archive/
Since this is your personal archive, you should make it the default.
$ tla my-default-archive haesslich@zork.net--projects
As with "my-id", you can run "tla my-default-archive" on its own to see what your default is.
Each branch you make must have a package (think modules in cvs) to be stored in. You're basically just allocating a name for it the way we allocated lnx-bbc--stable--2.1 for one of ours.
$ tla archive-setup lnx-bbc--uglification-project--0.1 * creating category haesslich@zork.net--projects/lnx-bbc * creating branch haesslich@zork.net--projects/lnx-bbc--uglification-project * creating version haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1
Notice that the three parts of a package's name are called the "category", "branch", and "version".
$ tla tag lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1 lnx-bbc--uglification-project--0.1 gpg: Signature made Tue 13 Apr 2004 04:46:10 PM PDT using DSA key ID 190F5A01 gpg: Good signature from "Nick Moffitt (GARchitect) <nick@lnx-bbc.com>" gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: EB97 A815 2FD2 3960 5F40 AEB3 AC9D F37D 190F 5A01 gpg: Signature made Tue 13 Apr 2004 04:52:31 PM PDT using DSA key ID 190F5A01 gpg: Good signature from "Nick Moffitt (GARchitect) <nick@lnx-bbc.com>" gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: EB97 A815 2FD2 3960 5F40 AEB3 AC9D F37D 190F 5A01 * Archive caching revision * from pristine cache: lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1--patch-1 * patching for revision: haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0 * Made cached revision of haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0
The gpg output at the beginning just tells you that the changesets that stable is made up of are all signed properly, but you don't recognize the signature. The rest of the output shows that the latest version of stable has been packed up and made into a tarball to serve as the base-0 beginning of your new branch.
$ tla get lnx-bbc--uglification-project * from archive cached: haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0 * making pristine copy * tree version set haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1 $ cd lnx-bbc--uglification-project--0.1--base-0/
Now make some changes, working toward some goal. As you complete the sub-components, start maintaining your changelog in another window.
$ vi `tla make-log`
$ tla tree-lint $ tla what-changed * looking for haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0 to compare with * comparing to haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0 M CREDITS
Silence from tree-lint is always a good sign, and what-changed tells us that we edited CREDITS, and that's about all. Now we can check our work into our branch in our local archive. Since haesslich didn't do the "vi `tla make-log`", he has to enter his log now.
$ tla commit 1 Summary: Added haesslich to CREDITS 2 Keywords: ugly credits CREDITS haesslich 3 4 Gave Ugly "haesslich" Troll the CREDIT he deserves! ~ ~ M CREDITS * update pristine tree (haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0 => lnx-bbc--uglification-project--0.1--patch-1) * committed haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--patch-1
Since our local archive doesn't require signatures, there was no gpg magic.
While you work, development does not halt! Barring some sort of code freeze, other developers are checking code into the official branch while you're wrestling with your particular problem. Folding their work into your branch is a good way to resolve conflicts without stopping all your work in other branches, and you can even do it with a separate working copy if you like.
$ tla get lnx-bbc--uglification-project--0.1 merge-copy $ cd merge-copy/ $ tla star-merge lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1
While CVS scatters diff3 options about your files, delimited by sequences of less-than and greater-than signs, arch prefers to simply store conflicts in .rej files. If you don't have any .rej files, then you don't have any conflicts! Otherwise, resolve the conflicts and "tla commit" your merged version into your local archive and branch. Note that the changelogs for the merged changesets will be in your log automatically!
Once you've committed, you can safely update your main development branch and finish what you were doing.
$ cd .. $ rm -rf merge-copy/ $ cd lnx-bbc--uglification-project--0.1--base-0 $ tla update
Remember how we had you check out the gargoyle stable branch in the beginning? Well you really didn't need to use it until now. All you're doing is the reverse of what you did to merge someone else's upstream changes into your local branch:
$ cd lnx-bbc--stable--2.1--patch-1/ $ tla update $ tla star-merge haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1 $ tla commit
Again, when you commit your star-merged changes, you should see all of the changelog entries you wrote while working locally appear in the log for the official branch.
Suppose that you're the maintainer of lnx-bbc--research--0.0, and you just saw someone NUV a package in lnx-bbc--stable--2.1. The resulting revision for stable is now patch-69, and the current revision for research is patch-242.
Since changesets are self-contained, you know that patch-69 contains only the stuff you want to bring over to your branch. Perhaps patch-68 was something that isn't applicable to the research codebase. Perhaps patches 30 through 68 are all judiciously back-ported features from the research branch.
Well you can cherry-pick stable's patch-69 as a changeset you want to apply to the research branch.
$ cd lnx-bbc--research--0.0--patch-242 $ tla replay lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1--patch-69
Resolve any conflicts and commit! You'll even have the stable developer's changelog entry in your commit log!
Arch has the "tla mv" command, which allows you to move a file from one place in a branch to another, retaining its revision history!
Arch uses SFTP as the remote protocol, and it's low-level enough that serious lag can be introduced while talking with gargoyle. To speed things up, you can create a local cache of individual files in the archive, otherwise known as a library.
$ mkdir ~/.arch-library $ tla my-revision-library ~/.arch-library/ $ tla library-config --greedy ~/.arch-library/ $ tla library-add lnx-bbc-devel@zork.net--gar-autobuild/lnx-bbc--research--0.0 $ tla library-add lnx-bbc-devel@zork.net--gar-autobuild/lnx-bbc--stable--2.1
What you will now have is a greedy library that will automatically cache unpacked versions of all the files in those two branches you library-added.
Occasionally you'll be partway into a project on a local branch, and you realize you need help or want to show your work to another developer. Arch to the rescue!
$ tla make-archive --listing --mirror haesslich@zork.net--projects sftp://haesslich@zork.net/home/haesslich/public_html/arch $ tla archive-mirror haesslich@zork.net--projects
Since this was mirrored to the arch subdir of haesslich's public_html on zork.net, he would direct people to do the following:
$ tla register haesslich@zork.net--projects http://zork.net/~haesslich/arch $ tla get haesslich@zork.net--projects/lnx-bbc--uglification-project
The official anonymous mirror for lnx-bbc-devel@zork.net--gar is at http://www.lnx-bbc.com/arch
Currently gargoyle runs two cron jobs that make mirrors. The first one is the script that mails recently checked-in patchsets to lnx-bbc-cvs. That one pushes all new commits to lnx-bbc--research up to the mirror each minute.
The second is the autobuild job, which checks out lnx-bbc--stable and runs a complete build of it. If the build succeeds, the ISO goes up to http://lnx-bbc.com/builds/, a mail goes out about the success, and the version that was built is pushed to the mirror. If the build fails, nothing gets pushed and an error message goes to lnx-bbc-cvs.
Third-party developers have more flexibility and power under arch than they did with CVS.
$ tla register-archive http://www.lnx-bbc.com/arch $ tla get lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1
Then hack away. Feel free to branch off for your own changes as described earlier in this document.
$ tla changes -o ,,my-illustrious-changes $ tar czvf my-illustrious-changes.tar.gz ,,my-illustrious-changes
If you branch off of the mirror and publish your branch as described elsewhere in this document, the LNX-BBC developers can then look at your entire revision history. This is far more powerful than receiving a changeset in e-mail, as we get to play with your archive.
We now have Planet LNX-BBC to keep track of development in various distributed branches. If you wish to have your archive's lnx-bbc branches appear on the planet page, the easiest way is for you to generate the rss out of cron.
First: get tla-rss.sh from the scripts category.
$ tla register-archive http://www.lnx-bbc.com/arch $ tla get scripts--gargoyle-bin
(You can use your sftp archive for this as well)
Then set up a cron job to run tla-rss.sh regularly with an appropriate archive and archzoom URL. If you do not wish to install archzoom on your system, lnx-bbc.com can be made to perform its functions (albeit inefficiently).
*/10 * * * * $HOME/bin/tla-rss.sh -n 25 -u http://psax.org/~dave/archzoom/archzoom.cgi dave@psax.org--projects/lnx-bbc > $HOME/public_html/rss/lnx-bbc.rss
This will make an RSS file every ten minutes with the 25 most recent commmits from each lnx-bbc-- branch in Dave Barry's archive (provided you have registered dave@psax.org--projects). You can specify full version IDs to tla-rss.sh (to specify one branch in isolation), but to date you cannot give it category--branch without also specifying a version.
Finally, come up with a code hobo (A.K.A. hackergotchi head) to appear by your commits. George Moffitt describes the process for turning a cropped head image into a hackergotchi using the GIMP:
I make four copies of the head, layered atop one another. At that point it looks like one head. Then I blur the second layer down by about 5, the next layer beneath that by about 10, and the bottom one by about 15; so you get a nice blur around the edge, but the regular face image is on top.
Make sure the image is a PNG that fades to a transparent background (with alpha channels and all) and that you scale it to 100x100. Also, if you would like your archive to have a special background image beneath the code hobo (such as we do for the official research and stable branches), please make sure that is scaled to 100x100 (though it can be in any format you like).
| Nick Moffitt | http://zork.net/~nick/arch/ |
|---|---|
| "Yosemite" Sam Phillips | http://dasbistro.com/~sam/archives/gar/ |
| Nate "inkblot" Riffe | http://www.movealong.org/~inkblot/arch/projects-2004 |
| Dave "Psykoyiko" Barry | http://psax.org/~dave/arch |