Difference between revisions of "Audacity Configure Script"

From Audacity Wiki
Jump to: navigation, search
(a load about how the configure script system works)
 
(Library Checks: more variables to set, and what to set them to.)
Line 26: Line 26:
  
 
For each library '''''NAME''''' the following variables can be set by the check function:
 
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_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_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_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_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.
  
 
[[Category: Linux and Unix Platform]]
 
[[Category: Linux and Unix Platform]]
 
[[Category: For Developers]]
 
[[Category: For Developers]]

Revision as of 20:53, 4 July 2008

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.

Generating Configure

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:

$ autoreconf

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.

Library Checks

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 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.