To install:
	ln -s cobble make-links
	./make-links


This is a little bit of cobble documentation.
===============================================================================
Cobble is a primitive source code control system, targeted at .tar.gz (or
part*) archives ftp'd from around the net.
It has many of the same advantages of most source code control systems: merging
code changes becomes much easier. Cobble is targeted at merging locally written
changes into a single "line" (as opposed to a tree or graph) of baselines.
Cobble's primary advantage over other source code control systems, most of
which allow more flexible source structures, is that cobble uses (optionally
compressed) tar archives or shar archives as baselines, so you needn't keep
large, uncompressed source trees around for long periods of time.
BTW, note that cobble is really a very simple tool, mostly just a wrapper
around patch(1). There really isn't much more to it, than what is described in
this document - and yet the benefits can still be large. If nothing else,
cobble encourages us to be very methodical.
===============================================================================
Cobble uses these steps, to accomplish its job:
    * Cobble looks for an archive to work with. If it is named "foo.tar.gz",
      "foo.tar.bz2", "foo.tar.Z", "foo.tar" or "part*", cobble should detect
      it, and know how to extract it. If cobble finds more than one such
      archive in the current working directory, it complains and exits.
    * It then checks to see if there is an "src" directory under the current
      working directory, and removes it if it does.
    * It then extracts the sources from the detected archive, into a new "src"
      directory, stripping off any prefix directory within the tar or shar
      archive, for consistent naming.
    * It then applies optional patches. Cobble recognizes the patch directories
      described below. Patches found in these directories are automatically
      applied, immediately after an archive is extracted. The patches can be
      compressed (.Z or .gz), but needn't be.
          o internal-patches - Used for patches that should never leave UCI.
            Platform independent.
          o exportable-patches - Used for patches that are suitable for giving
            to people outside UCI.. Platform independent.
          o net-patches - Used for patches that were ftp'd from elsewhere,
            especially by the .tar.gz's maintainer(s).. Platform independent.
          o `systype`-patches - EG "sun4-5-patches" or "sgi-5-patches". Used
            for platform-specific patches. If there's a platform-inspecific way
            of making a change, do that instead. If that's too inconvenient,
            use one of these directories.
    * It then inspects the files that were extracted, for signs of how the
      package should be compiled. By default:
          o if there is a "configure" or "Configure" file, cobble will run it
            (with --prefix=/dcs/packages/gnu), and then run make
          o otherwise, if there is an Imakefile, cobble with "xmkmf -a" and
            then run make
          o otherwise, if there is a plain ol' Makefile (or "makefile"), it
            will just do a make.
          o otherwise, cobble complains, and exits.
          o If you run into a package that is not handled by these simple rules
            (most are), you can tuck bourne shell commands into "local-script"
            next to the .tar.gz, to get them used instead of cobble's default
            build procedure.
                # If your tar archive is named foo-1.01.tar.gz, for example,
                  cobble will set the variable $vers to 1.01, usable from
                  within your local-script and inst script.
===============================================================================
After you've successfully built your sources, it's time to install the
software. You can do this with "do-inst". "do-inst" defaults to running "make
install", but this can be overridden by providing an "inst" script next to the
.tar.gz.
===============================================================================
Moving forward to the next release of your baseline (.tar.gz, .tar.bz2,
&c), assuming that the previous release was fully built using cobble. This
is where the primary benefits of cobble are realized:
    * What I usually do, is to:
         1. cd to the directory containing the .tar.gz or whatever
         2. mkdir -p old
         3. mv the old .tar.gz to old/.
         4. download the new .tar.gz
         5. run cobble. This should make cobble attempt to use the same config
            files that hopefully worked with the last baseline
    * Another option some folks seem to prefer, which I don't think there's
      anything wrong with, is to:
         1. mkdir a fresh directory
         2. download the new .tar.gz to it
         3. copy over the local-script, inst, *-patches directories, and
            cobble-info from a previous release's directory
         4. run cobble
===============================================================================
I like to put this shell function in my ~/.bashrc :
      function cob
      {
      	cobble > output 2>&1 &
      	less -sc output
      }
    * ...and then as soon as less starts up, I type a capital F, to watch the
      results scroll by.
===============================================================================
Advanced cobble usage.
    * If you're in a hurry, you can create a file called "cobble-info" next to
      the .tar.gz, and put the word "systype" in it. This will make cobble
      create, instead of an src directory, one directory for each platform,
      named by `systype`. This allows you to do compiles in parallel. If you do
      this, it is particularly important to remember to remove all the source
      trees when you are done, because it takes up so much more disk space.