Using build-configs

This page will describe how to use build-configs to build more complex projects.

The best example is probably tla itself.

Build configs are handy for collecting a bunch of projects, perhaps different categories in one archive or perhaps different archives, into a single directory structure.

Suppose you are using a library, handy.so, in your new program, shake. Handy is not distributed in many Linux distributions, so you want to distribute it's source in the tarball along with shake's source, and your makefile will build handy.so and staticly link to it if necessary. You don't really want to maintain a handy distribution or have it clutter up your shake source tree, but perhaps you're willing to track handy's CVS in arch, or simply make an arch archive category containing the requisite version of handy. You put the projects /shake--main--2.0 and /handy--main--1.5 in your arch archive. Getting /shake--main--2.0 and using build configs will put handy--main--1.5 in the correct location in the source tree so that it can be built, and so that the entire resultant source tree can be tarred up and distributed.

Perhaps you are building a web site. The site requires some supporting programs you've written in perl for another project to be installed in /usr/local. These go in their own archive as you're maintaining them separately from the web site. The site has some web pages you've written. These go in an archive category. The site also requires the 3-rd party tool, frob.php be installed in it's own directory among the web pages you've written. (Think phpMySQLAdmin.) You package up the appropriate version of frob.php into another category in the same archive as the web pages. By making a meta-category for the entire bundle, in the web page's archive, build configs again allow you to collect all projects into a large tree for maintenance or distribution in a tarfile, as in the previous example. But you can also use build configs to install the web pages and frob.php into the requsite places in the webserver's document root.

Here's a map of which archives/versions go where in the overall project tree:

me@example.com--website--05/site-bundle--main--1.0
   |
   |--me@example.com--website--05/web-pages--main--1.0
   |     |
   |     |--me@example.com--website--05/frob.php--stable--3.5
   |
   |--me@example.com--perltools--04/webtools--main--2.1

In cases where you must have separate categories, as in the webserver example where the site itself can be installed from it's archive/version and arch used to update it in-place without a complicated installation script, the config files used by build config provide an explicit method of documenting what categories go where in the tree. It's likely that makefiles could always be substituted for build configs, but who wants to read makefiles to figure out what's going on? It's nice to be able to have your entire tree in one place to work on it.

The above examples assume that none of the 3rd party software is managed with arch, if it is then there's even more reason to want to mix archives in a single build tree.

Build configs require config files. See the section on Multi-tree Projects and Configuration Management in Tom Lord's Arch Tutorial.