autoconf: Configuration Actions

1 
1 4.6 Performing Configuration Actions
1 ====================================
1 
1 `configure' is designed so that it appears to do everything itself, but
1 there is actually a hidden slave: `config.status'.  `configure' is in
1 charge of examining your system, but it is `config.status' that
1 actually takes the proper actions based on the results of `configure'.
1 The most typical task of `config.status' is to _instantiate_ files.
1 
1    This section describes the common behavior of the four standard
1 instantiating macros: `AC_CONFIG_FILES', `AC_CONFIG_HEADERS',
1 `AC_CONFIG_COMMANDS' and `AC_CONFIG_LINKS'.  They all have this
1 prototype:
1 
1      AC_CONFIG_ITEMS(TAG..., [COMMANDS], [INIT-CMDS])
1 
1 where the arguments are:
1 
1 TAG...
1      A blank-or-newline-separated list of tags, which are typically the
1      names of the files to instantiate.
1 
1      You are encouraged to use literals as TAGS.  In particular, you
1      should avoid
1 
1           ... && my_foos="$my_foos fooo"
1           ... && my_foos="$my_foos foooo"
1           AC_CONFIG_ITEMS([$my_foos])
1 
1      and use this instead:
1 
1           ... && AC_CONFIG_ITEMS([fooo])
1           ... && AC_CONFIG_ITEMS([foooo])
1 
1      The macros `AC_CONFIG_FILES' and `AC_CONFIG_HEADERS' use special
1      TAG values: they may have the form `OUTPUT' or `OUTPUT:INPUTS'.
1      The file OUTPUT is instantiated from its templates, INPUTS
1      (defaulting to `OUTPUT.in').
1 
1      `AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk])', for
1      example, asks for the creation of the file `Makefile' that
1      contains the expansion of the output variables in the
1      concatenation of `boiler/top.mk' and `boiler/bot.mk'.
1 
1      The special value `-' might be used to denote the standard output
1      when used in OUTPUT, or the standard input when used in the
1      INPUTS.  You most probably don't need to use this in
1      `configure.ac', but it is convenient when using the command line
1      interface of `./config.status', see *noteconfig.status
1      Invocation::, for more details.
1 
1      The INPUTS may be absolute or relative file names.  In the latter
1      case they are first looked for in the build tree, and then in the
1      source tree.  Input files should be text files, and a line length
1      below 2000 bytes should be safe.
1 
1 COMMANDS
1      Shell commands output literally into `config.status', and
1      associated with a tag that the user can use to tell `config.status'
1      which commands to run.  The commands are run each time a TAG
1      request is given to `config.status', typically each time the file
1      `TAG' is created.
1 
1      The variables set during the execution of `configure' are _not_
1      available here: you first need to set them via the INIT-CMDS.
1      Nonetheless the following variables are precomputed:
1 
1     `srcdir'
1           The name of the top source directory, assuming that the
1           working directory is the top build directory.  This is what
1           the `configure' option `--srcdir' sets.
1 
1     `ac_top_srcdir'
1           The name of the top source directory, assuming that the
1           working directory is the current build directory.
1 
1     `ac_top_build_prefix'
1           The name of the top build directory, assuming that the working
1           directory is the current build directory.  It can be empty,
1           or else ends with a slash, so that you may concatenate it.
1 
1     `ac_srcdir'
1           The name of the corresponding source directory, assuming that
1           the working directory is the current build directory.
1 
1     `tmp'
1           The name of a temporary directory within the build tree,
1           which you can use if you need to create additional temporary
1           files.  The directory is cleaned up when `config.status' is
1           done or interrupted.  Please use package-specific file name
1           prefixes to avoid clashing with files that `config.status'
1           may use internally.
1 
1      The "current" directory refers to the directory (or
1      pseudo-directory) containing the input part of TAGS.  For
1      instance, running
1 
1           AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [...], [...])
1 
1      with `--srcdir=../package' produces the following values:
1 
1           # Argument of --srcdir
1           srcdir='../package'
1           # Reversing deep/dir
1           ac_top_build_prefix='../../'
1           # Concatenation of $ac_top_build_prefix and srcdir
1           ac_top_srcdir='../../../package'
1           # Concatenation of $ac_top_srcdir and deep/dir
1           ac_srcdir='../../../package/deep/dir'
1 
1      independently of `in/in.in'.
1 
1 INIT-CMDS
1      Shell commands output _unquoted_ near the beginning of
1      `config.status', and executed each time `config.status' runs
1      (regardless of the tag).  Because they are unquoted, for example,
1      `$var' is output as the value of `var'.  INIT-CMDS is typically
1      used by `configure' to give `config.status' some variables it
1      needs to run the COMMANDS.
1 
1      You should be extremely cautious in your variable names: all the
1      INIT-CMDS share the same name space and may overwrite each other
1      in unpredictable ways.  Sorry...
1 
1    All these macros can be called multiple times, with different TAG
1 values, of course!
1