ax_enable_builddir : automatic subdir builds

[Guido Draheim]

I had that idea for a long time but I knew that it would require
some iterations of testing before it works smoothly. Finally, there
was enough time lately to give it a try and here it is - a new macro.

* what is it?
Per default, autoconf/automake builds are done within the source
directory. The macro changes the default to build in a subdirectory
instead, just like you would do
(mkdir linux && cd linux && sh configure && make)

* benefits
there are a number of benefits to use a subdir build, many of which
were covered in earlier threads on the autotools mailinglists. To
hilight some:
- multi user access to the same source repository
- multi arch builds in the same repo in a networked /home
  (shared for both linux and solaris workstations on your campus)
- multi arch builds using cross-compilers, esp. cross mingw,
  from a single source repo
Making a subdir to be the default has simple benefit: you do
not not forget to add $(srcdir) in rules during development
cycles that would prevent any of the above possibilities.
Usually platform portability is tested later in the devel
process, where multi builddir != srcdir is quite nice. As a
real world example: sourceforge compilefarm uses a shared
home for all machines attached and reachable from the login.

* the invokation
using the macro without an argument uses $host as the subdir
name. Using the sourceforge compilefarm example: each
platform will get its own builddir automatically, with the
linux, solaris, freebsd, darwin parts built in their own
area.

Using $host does also match with the recommended style of
crossgcc setup: just use configure --host=i386-mingw32
and the autoconf parts will automatically find any
i386-mingw32-gcc in the path - and start using it.

* the implementation
it just fits into the normal autoconf processing - it just
moves (!!) the config.log and other configure files into
the new subdir, and it modifies some helper variables of
autoconf so that later macro (really: their shell code)
believes it was run as an off-sourcedir configure in
the first place.

* the sourcedir Makefile
For convenience with the usual build procedure, a toplevel
Makefile is created in the sourcedir. This allows still to
run `sh configure && make && make install` as described in
many software documentations. The toplevel Makefile does
have a set of rules that will do nothing else than recurse
into the subdirectory of your buildfiles.

The toplevel subdir-build makefile is derived from the
toplevel sourcedir makefile.in with a simple sed-script,
and the last operation is an appendix of pairs of
$host -> subdir which will be scanned by the executions.
A `tail Makefile` will then tell you what platforms
you have configured (and built?) already.

* multi-variant builds
That's my other intention: to provide an easier way to
create multi-variant builds. The toplevel configure.ac
does have a --with-variant=... option, and the argument
of the ac-macro is expanded to be now
AX_ENABLE_BUILDDIR($host-$with_variant) and the $variant
result to select some other options in the rest of it.

Each configured variant will be listed in the toplevel
Makefile, i.e. there are now multiple $host -> $build
entries in the configure-table, e.g.
$ tail Makefile
#### CONFIGURATIONS FOR TOPLEVEL MAKEFILE:
#### i686-pc-linux-gnu |./Release/i686-pc-linux-gnu
#### i686-pc-linux-gnu |./Release/i686-pc-linux-gnu-fig

When using the normal build-target then only the
last-configured variant for a $host is selected. But
the sed-script to derive the sourcedir makefile from
the sourcedir makefile.in has some other magic: it
creates an "<target>-all" for each make "<target>"
that will run that <target> in _all_ build directories
of the current $host.

In the example, it will recurse into both "fig" and
non-"fig" variant. A final `make install-all` will
install all variants in one go that are valid for
this platform. The config.guess $host can be overridden
with HOST= settings btw, e.g. for crosscompiler setups.

* what else?
I dunno, I am using it now in multiple projects. Btw,
if you want no subdir build then you can always just
--disable-builddir or may be you want to set your own
--enable-build=myowndirname - that's alreay in the
ac-macro as of now. Perhaps you have another idea what
to do with this macro, then please let me hear of it.

http://ac-archive.sf.net/guidod/ax_enable_builddir.html

-- cheers, guido