[Playerstage-developers] Autotools nano-HOWTO

[brian g. <bg...@po...>]

hi all,

  As i mentioned yesterday, i've moved Player development over to using the
GNU Autotools.  Now, developing with these tools is bit of a change from
the "old" way of just writing Makefiles, and it'll take a little getting
used to.  Fortunately for you, i've done the hard part of setting up the 
project (which, by the way, is a total mindfuck).

-------------------------------------------------------------------------------
Sources of information
-------------------------------------------------------------------------------
Since i'm not documenting the operation of the Autotools, you'll need to look
elsewhere if you want to know how to, for example, change a configure.in or
a Makefile.am.

First off, there is a lot of documentation online, the most important of which
are the manuals for autoconf and automake:

  http://www.gnu.org/manual/autoconf-2.53/autoconf.html
  http://www.gnu.org/manual/automake-1.6.1/automake.html

Be aware that this documentation is for newer versions of the tools than those
that most of us are using.  In particular, automake 1.6 includes several nifty
things that automake 1.4 does not support, so we're not using them right now.

I've also been using the following book:

  "GNU Autoconf, Automake, and Libtool," by Gary Vaughn, Ben Ellison, 
  Tom Tromey, and Ian Taylor.  New Riders, 2000.

I bought a bound copy, but you can browse the whole thing online:

  http://sources.redhat.com/autobook/autobook/autobook_toc.html
-------------------------------------------------------------------------------


-------------------------------------------------------------------------------
Overview of the tools
-------------------------------------------------------------------------------
The Autotools that we're using are: 
  - autoconf
  - automake.  

We're not using libtool right now, because we're not building shared 
libraries.  We're also using some support programs:
  - aclocal
  - autoheader

Together, these programs process some special input files (detailed below)
to produce several outputs:
  - a configure script
  - Makefiles
  - a configuration header config.h 
-------------------------------------------------------------------------------


-------------------------------------------------------------------------------
The input files
-------------------------------------------------------------------------------
Whereas in the old days, we just wrote Makefiles, one in each directory where
something should be compiled or installed, we now write the following:

  - one configure.in at the top-level
  - one Makefile.am in each directory

The configure.in sets up configuration for the whole project, including
package name, version, checks for libraries, and which directories should be
processed.  Also defined in configure.in are any command-line arguments that
the final configure script should process (e.g., --without-sicklms200).

The Makefile.am's are inputs to automake (i.e., 'automakefiles'), kind of like 
abstracted Makefile's.  Whereas you generally had to tell make what you want 
and how to build it, you only have to tell automake what you want; it knows
now to build it, on pretty much any system.
-------------------------------------------------------------------------------


-------------------------------------------------------------------------------
Using the tools
-------------------------------------------------------------------------------
When you first check out from CVS, you should run the 'bootstrap' script,
which has the following contents:

  #!/bin/sh
  set -x
  aclocal
  autoheader
  automake --gnu --add-missing
  autoconf
  ./configure "$@"

Thus it runs all the right things, in the right order, to set up your local
working copy for compilation.  Note that arguments to bootstrap are passed on
to the configure script, so you can do things like:

  $ ./bootstrap --without-sicklms200

Now, after running bootstrap, you've got Makefile's everywhere, and you can
just do:

  $ make

Several useful make targets are automatically defined, including:

  - all
  - install
  - uninstall
  - dist
  - clean
  - maintainer-clean

In particular, try 'make dist'; it knows how to wrap up a nice tarball for
you.  Unpack it somewhere, then do:

  $ configure
  $ make
  $ make install

Cool, huh?
  
Since the interdependencies among the various tools and their various inputs
and outputs are complex, it's difficult to remember what tool to run when
you've changed a given file.  Fortunately, most of this is done for you, and
you can follow two simple rules:

  1. If you just change source files or Makefile.am's, then just run 'make'.

  2. If you change configure.in, if Rule #1 doesn't work, or if in doubt as
     to what to do, then run 'bootstrap.'

In general, you'll only be changing source files and the various
Makefile.am's, so one run of bootstrap should be enough.  From then on, you
can just type 'make' like you used to (source dependency tracking is done
automatically, so 'make dep' is not necessary).

Also, once you've run bootstrap, you can just run the 'configure' script if you
want to change your compilation configuration, e.g.:

  $ ./configure --without-sicklms200 --with-tests

To find out what options configure accepts (i.e., what options i've defined), 
do:

  $ ./configure --help
-------------------------------------------------------------------------------

        hope this helps,
        brian.