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