Audacity Configure Script
The configure script is the visible face of Audacity's Unix build system, and is used under the bonnet by the Xcode project for Mac OS X as well. This page aims to explain why the script is programmed the way it is, and how to go about adding to and modifying it.
The pieces of the jigsaw
The top level configure script is only one part of the build system. Equally important are the template makefiles (Makefile.in) located in each source directory. These will be processed by configure to create the Makefiles used to compile Audacity. Equally importantly, configure creates src/configunix.h from src/configtemplate.h with the pre-processor defines that will tell the compiler which features are enabled, and which libraries are available to be used.
Each library included in the lib-src/ directory will have all of this in microcosm as it's own build system, run from the main Audacity configure system to prepare each library if it is selected to be built.
The first question is, where does the configure script come from? Like most other open source projects (FFmpeg and Mplayer being exceptions), Audacity uses Autoconf to generate it's configure script. configure is in essence a large shell script, and Autoconf is essentially a specialised compiler for creating these shell scripts from a more practical set of "source code". In Audacity's case, the source files are configure.in and acinclude.m4. configure.in contains the source to the main script, whilst acinclude.m4 contains a collection of functions used in configure.in.
To perform this compilation, you will need to have Autoconf installed on your system. You will also need some supporting functions from the Autoconf Macro Archive, so you should install their macro package. Autoconf requires the aclocal program which is part of Automake, so this will be needed as well, despite the fact that Audacity doesn't use Automake itself. Several of the libraries we use do, however, so at some point you will end up using Automake as well.
With all that lot installed in in place you can actually do the compilation with the following commands:
$ aclocal $ autoconf
This will rebuild the configure script in Audacity, but not touch any of the separate library configure scripts in lib-src/. If you want to rebuild these as well there is a handy wrapper script that works out what needs doing and does it in the right order:
This might be slower, but saves worrying about whether you need to re-run aclocal, or if you have got to all the library directories.
An important part of configure's purpose is to check which libraries are available on your system, which can be found under lib-src/ and which are simply not available. It also has to interpret the various options the builder may have passed to configure and take account of them. In order to keep the complexity of the configure.in file manageable, almost all the libraries used by Audacity are handled in the same way. configure.in contains a list of libraries which it works through, each time running the library check function and interpreting the results. These check functions are all named AUDACITY_CHECKLIB_NAME, and defined in acinclude.m4.
Each follows a similar form. The first function call is to AC_ARG_WITH() which results in the code for the configure options --with-library and --without-library. Within this call AS_HELP_STRING() provides (and formats neatly) the help for the option, displayed when you do configure --help. Next comes a call to AC_DEFINE(), enclosed within if false; . This seems to be completely pointless, except that symbol name and comment given here are extracted and used to create src/configtemplate.h. So the code never gets run, but is essential to generate other parts of the build system.
Next come tests for a system copy of the library (i.e. one that has been installed on the system independently), and for a local copy (one located in lib-src/). No decision is taken on which to use as yet - configure will do this later. However all the information from the tests has to be passed back to configure. Because of the way "functions" in configure end up being implemented, we can pass this information back simply by shoving it into named variables and reading it out from the parent configure script.
For each library NAME the following variables can be set by the check function:
- NAME_SYSTEM_AVAILABLE - set if a suitable system copy of the library is available.
- NAME_SYSTEM_LIBS - the LDFLAG linker options needed to use the library
- NAME_SYSTEM_CXXFLAGS - the CXXFLAGS C++ compiler options needed to use the library
- NAME_SYSTEM_CPPSYMBOLS - the C pre-processor symbols needed to tell Audacity's code to use this library. This will be the same symbol that was used in AC_DEFINE before.