autoconf: Common Shell Constructs
1
1 9.1 Common Shell Constructs
1 ===========================
1
1 M4sh provides portable alternatives for some common shell constructs
1 that unfortunately are not portable in practice.
1
1 -- Macro: AS_BOX (TEXT, [CHAR = `-'])
1 Expand into shell code that will output TEXT surrounded by a box
1 with CHAR in the top and bottom border. TEXT should not contain a
1 newline, but may contain shell expansions valid for unquoted
1 here-documents. CHAR defaults to `-', but can be any character
1 except `/', `'', `"', `\', `&', or ``'. This is useful for
1 outputting a comment box into log files to separate distinct
1 phases of script operation.
1
1 -- Macro: AS_CASE (WORD, [PATTERN1], [IF-MATCHED1], ..., [DEFAULT])
1 Expand into a shell `case' statement, where WORD is matched
1 against one or more patterns. IF-MATCHED is run if the
1 corresponding pattern matched WORD, else DEFAULT is run. Avoids
11 several portability issues (⇒Limitations of Shell Builtins
case.).
1
1 -- Macro: AS_DIRNAME (FILE-NAME)
1 Output the directory portion of FILE-NAME. For example, if
1 `$file' is `/one/two/three', the command
1 `dir=`AS_DIRNAME(["$file"])`' sets `dir' to `/one/two'.
1
1 This interface may be improved in the future to avoid forks and
1 losing trailing newlines.
1
1 -- Macro: AS_ECHO (WORD)
1 Emits WORD to the standard output, followed by a newline. WORD
1 must be a single shell word (typically a quoted string). The
1 bytes of WORD are output as-is, even if it starts with "-" or
1 contains "\". Redirections can be placed outside the macro
11 invocation. This is much more portable than using `echo' (⇒
Limitations of Shell Builtins echo.).
1
1 -- Macro: AS_ECHO_N (WORD)
1 Emits WORD to the standard output, without a following newline.
1 WORD must be a single shell word (typically a quoted string) and,
1 for portability, should not include more than one newline. The
1 bytes of WORD are output as-is, even if it starts with "-" or
1 contains "\". Redirections can be placed outside the macro
1 invocation.
1
1 -- Macro: AS_ESCAPE (STRING, [CHARS = ``\"$'])
1 Expands to STRING, with any characters in CHARS escaped with a
1 backslash (`\'). CHARS should be at most four bytes long, and
1 only contain characters from the set ``\"$'; however, characters
1 may be safely listed more than once in CHARS for the sake of
1 syntax highlighting editors. The current implementation expands
1 STRING after adding escapes; if STRING contains macro calls that
1 in turn expand to text needing shell quoting, you can use
1 `AS_ESCAPE(m4_dquote(m4_expand([string])))'.
1
1 The default for CHARS (`\"$`') is the set of characters needing
1 escapes when STRING will be used literally within double quotes.
1 One common variant is the set of characters to protect when STRING
1 will be used literally within back-ticks or an unquoted
1 here-document (`\$`'). Another common variant is `""', which can
1 be used to form a double-quoted string containing the same
1 expansions that would have occurred if STRING were expanded in an
1 unquoted here-document; however, when using this variant, care
1 must be taken that STRING does not use double quotes within
1 complex variable expansions (such as `${foo-`echo "hi"`}') that
1 would be broken with improper escapes.
1
1 This macro is often used with `AS_ECHO'. For an example, observe
1 the output generated by the shell code generated from this snippet:
1
1 foo=bar
1 AS_ECHO(["AS_ESCAPE(["$foo" = ])AS_ESCAPE(["$foo"], [""])"])
1 =>"$foo" = "bar"
1 m4_define([macro], [a, [\b]])
1 AS_ECHO(["AS_ESCAPE([[macro]])"])
1 =>macro
1 AS_ECHO(["AS_ESCAPE([macro])"])
1 =>a, b
1 AS_ECHO(["AS_ESCAPE(m4_dquote(m4_expand([macro])))"])
1 =>a, \b
1
1 To escape a string that will be placed within single quotes, use:
1
1 m4_bpatsubst([[STRING]], ['], ['\\''])
1
1 -- Macro: AS_EXECUTABLE_P (FILE)
1 Emit code to probe whether FILE is a regular file with executable
1 permissions (and not a directory with search permissions). The
1 caller is responsible for quoting FILE.
1
1 -- Macro: AS_EXIT ([STATUS = `$?'])
1 Emit code to exit the shell with STATUS, defaulting to `$?'. This
1 macro works around shells that see the exit status of the command
11 prior to `exit' inside a `trap 0' handler (⇒Limitations of
Shell Builtins trap.).
1
1 -- Macro: AS_IF (TEST1, [RUN-IF-TRUE1], ..., [RUN-IF-FALSE])
1 Run shell code TEST1. If TEST1 exits with a zero status then run
1 shell code RUN-IF-TRUE1, else examine further tests. If no test
1 exits with a zero status, run shell code RUN-IF-FALSE, with
1 simplifications if either RUN-IF-TRUE1 or RUN-IF-FALSE is empty.
1 For example,
1
1 AS_IF([test "x$foo" = xyes], [HANDLE_FOO([yes])],
1 [test "x$foo" != xno], [HANDLE_FOO([maybe])],
1 [echo foo not specified])
1
1 ensures any required macros of `HANDLE_FOO' are expanded before
1 the first test.
1
1 -- Macro: AS_MKDIR_P (FILE-NAME)
1 Make the directory FILE-NAME, including intervening directories as
1 necessary. This is equivalent to `mkdir -p -- FILE-NAME', except
1 that it is portable to older versions of `mkdir' that lack support
11 for the `-p' option or for the `--' delimiter (⇒Limitations
of Usual Tools mkdir.). Also, `AS_MKDIR_P' succeeds if FILE-NAME
1 is a symbolic link to an existing directory, even though Posix is
1 unclear whether `mkdir -p' should succeed in that case. If
1 creation of FILE-NAME fails, exit the script.
1
1 Also see the `AC_PROG_MKDIR_P' macro (⇒Particular Programs).
1
1 -- Macro: AS_SET_STATUS (STATUS)
1 Emit shell code to set the value of `$?' to STATUS, as efficiently
1 as possible. However, this is not guaranteed to abort a shell
1 running with `set -e' (⇒Limitations of Shell Builtins set.).
1 This should also be used at the end of a complex shell function
1 instead of `return' (⇒Shell Functions) to avoid a DJGPP
1 shell bug.
1
1 -- Macro: AS_TR_CPP (EXPRESSION)
1 Transform EXPRESSION into a valid right-hand side for a C
1 `#define'. For example:
1
1 # This outputs "#define HAVE_CHAR_P 1".
1 # Notice the m4 quoting around #, to prevent an m4 comment
1 type="char *"
1 echo "[#]define AS_TR_CPP([HAVE_$type]) 1"
1
1 -- Macro: AS_TR_SH (EXPRESSION)
1 Transform EXPRESSION into shell code that generates a valid shell
1 variable name. The result is literal when possible at m4 time,
1 but must be used with `eval' if EXPRESSION causes shell
1 indirections. For example:
1
1 # This outputs "Have it!".
1 header="sys/some file.h"
1 eval AS_TR_SH([HAVE_$header])=yes
1 if test "x$HAVE_sys_some_file_h" = xyes; then echo "Have it!"; fi
1
1 -- Macro: AS_SET_CATFILE (VAR, DIR, FILE)
1 Set the polymorphic shell variable VAR to DIR/FILE, but optimizing
1 the common cases (DIR or FILE is `.', FILE is absolute, etc.).
1
1 -- Macro: AS_UNSET (VAR)
1 Unsets the shell variable VAR, working around bugs in older shells
1 (⇒Limitations of Shell Builtins unset.). VAR can be a
1 literal or indirect variable name.
1
1 -- Macro: AS_VERSION_COMPARE (VERSION-1, VERSION-2, [ACTION-IF-LESS],
1 [ACTION-IF-EQUAL], [ACTION-IF-GREATER])
1 Compare two strings VERSION-1 and VERSION-2, possibly containing
1 shell variables, as version strings, and expand ACTION-IF-LESS,
1 ACTION-IF-EQUAL, or ACTION-IF-GREATER depending upon the result.
1 The algorithm to compare is similar to the one used by strverscmp
11 in glibc (⇒String/Array Comparison (libc)String/Array
Comparison.).
1