Audacity Configure Script
|The configure script is the visible face of Audacity's Unix build system, and is used under the bonnet by the 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 of several equally important parts of the build system. The template makefiles (Makefile.in) located in each source directory are processed by configure to create the Makefiles used to compile Audacity. Also, 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 its 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 to generate its configure script. In essence, configure is a large shell script, and Autoconf 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 (containing the source to the main script), and all the files in the m4 directory (which each contain functions used in configure.in).
To perform this compilation, you will need to have Autoconf installed on your system. Autoconf requires the aclocal program which is part of , so this will be needed as well, despite the fact that Audacity doesn't use Automake itself. Several of the libraries we use do use Automake however, so at some point you will end up using it as well.
With all that lot installed in place you can actually do the compilation with the following commands:
$ aclocal -I m4/ $ 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 or in 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 (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 to "yes" if a suitable system copy of the library is available, otherwise "no" and ignore the other NAME_SYSTEM_ variables.
- 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.
- NAME_SYSTEM_OPTOBJS - extra object files that will be needed if the system library is used in Audacity. This provides for whole files that are only compiled if a library is enabled.
- NAME_LOCAL_AVAILABLE - set to "yes" if a suitable local copy of the library is available, otherwise "no" and ignore the other NAME_LOCAL_ variables.
- NAME_LOCAL_LIBS - the LDFLAG linker options needed to use the library. This will include a suitable addition to the linker path to find the library file when Audacity is linked.
- NAME_LOCAL_CXXFLAGS - the CXXFLAGS C++ compiler options needed to use the library. These will include adding the directory with the library header files to the compiler's include path.
- NAME_LOCAL_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.
- NAME_LOCAL_OPTOBJS - extra object files that will be needed if the library is used in Audacity. This provides for whole files that are only compiled if a library is enabled.
- NAME_LOCAL_CONFIG_SUBDIRS - The paths to directories that need to be configured in their own right before Audacity is built. In each of these directories, the Audacity configure script will try to run another configure script if it exists.
- NAME_LOCAL_BUILD - names of things that need to be compiled when Audacity is compiled. This can essentially be any string, because it just becomes a target in lib-src/Makefile.in which will be made before Audacity is compiled. The make rules for these targets will then perform a recursive make into the library subdirectory and compile the library.