Difference between revisions of "Audacity Configure Script"

From Audacity Wiki
Jump to: navigation, search
(Library Checks: more variables to set, and what to set them to.)
(Minor tidy)
Line 1: Line 1:
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.
+
{{Intro|1=The ''configure'' script is the visible face of Audacity's Unix build system, and is used under the bonnet by the {{external|[http://developer.apple.com/tools/xcode/ 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.|2=}}
 +
 
  
 
== The pieces of the jigsaw ==
 
== 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 ''Makefile''s 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.
+
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 ''Makefile''s 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.
  
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 ==
 
== 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 [http://www.gnu.org/software/autoconf/ 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''.
+
The first question is, where does the ''configure'' script come from? Like most other open source projects (FFmpeg and Mplayer being exceptions), Audacity uses {{external|[http://www.gnu.org/software/autoconf/ Autoconf]}} 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 ''acinclude.m4'' (which 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 [http://autoconf-archive.cryp.to/ Autoconf Macro Archive], so you should install their macro package. Autoconf requires the '''aclocal''' program which is part of [http://www.gnu.org/software/automake/ 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.
+
To perform this compilation, you will need to have Autoconf installed on your system. You will also need some supporting functions from the {{external|[http://autoconf-archive.cryp.to/ Autoconf Macro Archive]}}, so you should install their macro package. Autoconf requires the '''aclocal''' program which is part of {{external|[http://www.gnu.org/software/automake/ Automake]}}, so this will be needed as well, despite the fact that Audacity doesn't use Automake itself. Several of the [[AudacityLibraries|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 in place you can actually do the compilation with the following commands:
+
With all that lot installed in place you can actually do the compilation with the following commands:
 
  $ aclocal
 
  $ aclocal
 
  $ autoconf
 
  $ autoconf
Line 17: Line 19:
 
  $ autoreconf
 
  $ 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.
 
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 ==
 
== 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''.
+
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.
 
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.
+
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:
 
For each library '''''NAME''''' the following variables can be set by the check function:
Line 36: Line 39:
 
* '''''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_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_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_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.
 
* '''''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 08:06, 8 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 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.


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 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 acinclude.m4 (which 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 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
$ 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 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.