autoconf: Initialization Macros

1 
1 9.3 Initialization Macros
1 =========================
1 
1  -- Macro: AS_BOURNE_COMPATIBLE
1      Set up the shell to be more compatible with the Bourne shell as
1      standardized by Posix, if possible.  This may involve setting
1      environment variables, or setting options, or similar
1      implementation-specific actions.  This macro is deprecated, since
1      `AS_INIT' already invokes it.
1 
1  -- Macro: AS_INIT
1      Initialize the M4sh environment.  This macro calls `m4_init', then
1      outputs the `#! /bin/sh' line, a notice about where the output was
1      generated from, and code to sanitize the environment for the rest
1      of the script.  Among other initializations, this sets `SHELL' to
1      the shell chosen to run the script (⇒CONFIG_SHELL), and
1      `LC_ALL' to ensure the C locale.  Finally, it changes the current
1      diversion to `BODY'.  `AS_INIT' is called automatically by
1      `AC_INIT' and `AT_INIT', so shell code in `configure',
1      `config.status', and `testsuite' all benefit from a sanitized
1      shell environment.
1 
1  -- Macro: AS_INIT_GENERATED (FILE, [COMMENT])
1      Emit shell code to start the creation of a subsidiary shell script
1      in FILE, including changing FILE to be executable.  This macro
1      populates the child script with information learned from the parent
1      (thus, the emitted code is equivalent in effect, but more
1      efficient, than the code output by `AS_INIT',
1      `AS_BOURNE_COMPATIBLE', and `AS_SHELL_SANITIZE').  If present,
1      COMMENT is output near the beginning of the child, prior to the
1      shell initialization code, and is subject to parameter expansion,
1      command substitution, and backslash quote removal.  The parent
1      script should check the exit status after this macro, in case FILE
1      could not be properly created (for example, if the disk was full).
1      If successfully created, the parent script can then proceed to
1      append additional M4sh constructs into the child script.
1 
1      Note that the child script starts life without a log file open, so
1      if the parent script uses logging (⇒AS_MESSAGE_LOG_FD), you
1      must temporarily disable any attempts to use the log file until
1      after emitting code to open a log within the child.  On the other
1      hand, if the parent script has `AS_MESSAGE_FD' redirected
1      somewhere besides `1', then the child script already has code that
1      copies stdout to that descriptor.  Currently, the suggested idiom
1      for writing a M4sh shell script from within another script is:
1 
1           AS_INIT_GENERATED([FILE], [[# My child script.
1           ]]) || { AS_ECHO(["Failed to create child script"]); AS_EXIT; }
1           m4_pushdef([AS_MESSAGE_LOG_FD])dnl
1           cat >> "FILE" <<\__EOF__
1           # Code to initialize AS_MESSAGE_LOG_FD
1           m4_popdef([AS_MESSAGE_LOG_FD])dnl
1           # Additional code
1           __EOF__
1 
1      This, however, may change in the future as the M4sh interface is
1      stabilized further.
1 
1      Also, be aware that use of `LINENO' within the child script may
1      report line numbers relative to their location in the parent
1      script, even when using `AS_LINENO_PREPARE', if the parent script
1      was unable to locate a shell with working `LINENO' support.
1 
1  -- Macro: AS_LINENO_PREPARE
1      Find a shell that supports the special variable `LINENO', which
1      contains the number of the currently executing line.  This macro is
1      automatically invoked by `AC_INIT' in configure scripts.
1 
1  -- Macro: AS_ME_PREPARE
1      Set up variable `as_me' to be the basename of the currently
1      executing script.  This macro is automatically invoked by
1      `AC_INIT' in configure scripts.
1 
1  -- Macro: AS_TMPDIR (PREFIX, [DIR = `${TMPDIR:=/tmp}'])
1      Create, as safely as possible, a temporary sub-directory within
1      DIR with a name starting with PREFIX.  PREFIX should be 2-4
1      characters, to make it slightly easier to identify the owner of
1      the directory.  If DIR is omitted, then the value of `TMPDIR' will
1      be used (defaulting to `/tmp').  On success, the name of the newly
1      created directory is stored in the shell variable `tmp'.  On
1      error, the script is aborted.
1 
1      Typically, this macro is coupled with some exit traps to delete
1      the created directory and its contents on exit or interrupt.
1      However, there is a slight window between when the directory is
1      created and when the name is actually known to the shell, so an
1      interrupt at the right moment might leave the temporary directory
1      behind.  Hence it is important to use a PREFIX that makes it
1      easier to determine if a leftover temporary directory from an
1      interrupted script is safe to delete.
1 
1      The use of the output variable `$tmp' rather than something in the
1      `as_' namespace is historical; it has the unfortunate consequence
1      that reusing this otherwise common name for any other purpose
1      inside your script has the potential to break any cleanup traps
1      designed to remove the temporary directory.
1 
1  -- Macro: AS_SHELL_SANITIZE
1      Initialize the shell suitably for `configure' scripts.  This has
1      the effect of `AS_BOURNE_COMPATIBLE', and sets some other
1      environment variables for predictable results from configuration
1      tests.  For example, it sets `LC_ALL' to change to the default C
1      locale.  ⇒Special Shell Variables.  This macro is
1      deprecated, since `AS_INIT' already invokes it.
1