This is Info file /gnu/src/amiga/autoconf-2.1/autoconf.info, produced by Makeinfo-1.55 from the input file /gnu/src/amiga/autoconf-2.1/autoconf.texi. START-INFO-DIR-ENTRY * Autoconf: (autoconf). Create source code configuration scripts. END-INFO-DIR-ENTRY This file documents the GNU Autoconf package for creating scripts to configure source code packages using templates and an `m4' macro package. Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. File: autoconf.info, Node: Run Time, Next: Portable Shell, Prev: Examining Libraries, Up: Writing Tests Checking Run Time Behavior ========================== Sometimes you need to find out how a system performs at run time, such as whether a given function has a certain capability or bug. If you can, make such checks when your program runs instead of when it is configured. You can check for things like the machine's endianness when your program initializes itself. If you really need to test for a run-time behavior while configuring, you can write a test program to determine the result, and compile and run it using `AC_TRY_RUN'. Avoid running test programs if possible, because using them prevents people from configuring your package for cross-compiling. * Menu: * Test Programs:: Running test programs. * Guidelines:: General rules for writing test programs. * Test Functions:: Avoiding pitfalls in test programs. File: autoconf.info, Node: Test Programs, Next: Guidelines, Up: Run Time Running Test Programs --------------------- Use the following macro if you need to test run-time behavior of the system while configuring. - Macro: AC_TRY_RUN (PROGRAM, ACTION-IF-TRUE [, ACTION-IF-FALSE [, ACTION-IF-CROSS-COMPILING]]) PROGRAM is the text of a C program, on which shell variable and backquote substitutions are performed. If it compiles and links successfully and returns an exit status of 0 when executed, run shell commands ACTION-IF-TRUE. Otherwise run shell commands ACTION-IF-FALSE; the exit status of the program is available in the shell variable `$?'. This macro uses `CFLAGS' or `CXXFLAGS', `CPPFLAGS', `LDFLAGS', and `LIBS' when compiling. If the C compiler being used does not produce executables that run on the system where `configure' is being run, then the test program is not run. If the optional shell commands ACTION-IF-CROSS-COMPILING are given, they are run instead and this macro calls `AC_C_CROSS' if it has not already been called. Otherwise, `configure' prints an error message and exits. Try to provide a pessimistic default value to use when cross-compiling makes run-time tests impossible. You do this by passing the optional last argument to `AC_TRY_RUN'. `autoconf' prints a warning message when creating `configure' each time it encounters a call to `AC_TRY_RUN' with no ACTION-IF-CROSS-COMPILING argument given. You may ignore the warning, though users will not be able to configure your package for cross-compiling. A few of the macros distributed with Autoconf produce this warning message. To configure for cross-compiling you can also choose a value for those parameters based on the canonical system name (*note Manual Configuration::.). Alternatively, set up a test results cache file with the correct values for the target system (*note Caching Results::.). To provide a default for calls of `AC_TRY_RUN' that are embedded in other macros, including a few of the ones that come with Autoconf, you can call `AC_C_CROSS' before running them. Then, if the shell variable `cross_compiling' is set to `yes', use an alternate method to get the results instead of calling the macros. - Macro: AC_C_CROSS If the C compiler being used does not produce executables that can run on the system where `configure' is being run, set the shell variable `cross_compiling' to `yes', otherwise `no'. File: autoconf.info, Node: Guidelines, Next: Test Functions, Prev: Test Programs, Up: Run Time Guidelines for Test Programs ---------------------------- Test programs should not write anything to the standard output. They should return 0 if the test succeeds, nonzero otherwise, so that success can be distinguished easily from a core dump or other failure; segmentation violations and other failures produce a nonzero exit status. Test programs should `exit', not `return', from `main', because on some systems (old Suns, at least) the argument to `return' in `main' is ignored. Test programs can use `#if' or `#ifdef' to check the values of preprocessor macros defined by tests that have already run. For example, if you call `AC_HEADER_STDC', then later on in `configure.in' you can have a test program that includes an ANSI C header file conditionally: #if STDC_HEADERS # include #endif If a test program needs to use or create a data file, give it a name that starts with `conftest', such as `conftestdata'. The `configure' script cleans up by running `rm -rf conftest*' after running test programs and if the script is interrupted. File: autoconf.info, Node: Test Functions, Prev: Guidelines, Up: Run Time Test Functions -------------- Function declarations in test programs should have a prototype conditionalized for C++. In practice, though, test programs rarely need functions that take arguments. #ifdef __cplusplus foo(int i) #else foo(i) int i; #endif Functions that test programs declare should also be conditionalized for C++, which requires `extern "C"' prototypes. Make sure to not include any header files containing clashing prototypes. #ifdef __cplusplus extern "C" void *malloc(size_t); #else char *malloc(); #endif If a test program calls a function with invalid parameters (just to see whether it exists), organize the program to ensure that it never invokes that function. You can do this by calling it in another function that is never invoked. You can't do it by putting it after a call to `exit', because GCC version 2 knows that `exit' never returns and optimizes out any code that follows it in the same block. If you include any header files, make sure to call the functions relevant to them with the correct number of arguments, even if they are just 0, to avoid compilation errors due to prototypes. GCC version 2 has internal prototypes for several functions that it automatically inlines; for example, `memcpy'. To avoid errors when checking for them, either pass them the correct number of arguments or redeclare them with a different return type (such as `char'). File: autoconf.info, Node: Portable Shell, Next: Testing Values and Files, Prev: Run Time, Up: Writing Tests Portable Shell Programming ========================== When writing your own checks, there are some shell script programming techniques you should avoid in order to make your code portable. The Bourne shell and upward-compatible shells like Bash and the Korn shell have evolved over the years, but to prevent trouble, do not take advantage of features that were added after UNIX version 7, circa 1977. You should not use shell functions, aliases, negated character classes, or other features that are not found in all Bourne-compatible shells; restrict yourself to the lowest common denominator. Even `unset' is not supported by all shells! The set of external programs you should run in a `configure' script is fairly small. *Note Utilities in Makefiles: (standards.info)Utilities in Makefiles, for the list. This restriction allows users to start out with a fairly small set of programs and build the rest, avoiding too many interdependencies between packages. Some of these external utilities have a portable subset of features, as well; for example, don't rely on `ln' having a `-f' option or `cat' having any options. `sed' scripts should not contain comments or use branch labels longer than 8 characters. Don't use `grep -s' to suppress output, because `grep -s' on System V does not suppress output, only error messages. Instead, redirect the standard output and standard error (in case the file doesn't exist) of `grep' to `/dev/null'. Check the exit status of `grep' to determine whether it found a match. File: autoconf.info, Node: Testing Values and Files, Next: Multiple Cases, Prev: Portable Shell, Up: Writing Tests Testing Values and Files ======================== `configure' scripts need to test properties of many files and strings. Here are some portability problems to watch out for when doing those tests. The `test' program is the way to perform many file and string tests. It is often invoked by the alternate name `[', but using that name in Autoconf code is asking for trouble since it is an `m4' quote character. If you need to make multiple checks using `test', combine them with the shell operators `&&' and `||' instead of using the `test' operators `-a' and `-o'. On System V, the precedence of `-a' and `-o' is wrong relative to the unary operators; consequently, POSIX does not specify them, so using them is nonportable. If you combine `&&' and `||' in the same statement, keep in mind that they have equal precedence. To enable `configure' scripts to support cross-compilation, they shouldn't do anything that tests features of the host system instead of the target system. But occasionally you may find it necessary to check whether some arbitrary file exists. To do so, use `test -f' or `test -r'. Do not use `test -x', because 4.3BSD does not have it. Another nonportable shell programming construction is VAR=${VAR:-VALUE} The intent is to set VAR to VALUE only if it is not already set, but if VAR has any value, even the empty string, to leave it alone. Old BSD shells, including the Ultrix `sh', don't accept the colon, and complain and die. A portable equivalent is : ${VAR=VALUE} File: autoconf.info, Node: Multiple Cases, Next: Language Choice, Prev: Testing Values and Files, Up: Writing Tests Multiple Cases ============== Some operations are accomplished in several possible ways, depending on the UNIX variant. Checking for them essentially requires a "case statement". Autoconf does not directly provide one; however, it is easy to simulate by using a shell variable to keep track of whether a way to perform the operation has been found yet. Here is an example that uses the shell variable `fstype' to keep track of whether the remaining cases need to be checked. AC_MSG_CHECKING(how to get filesystem type) fstype=no # The order of these tests is important. AC_TRY_CPP([#include #include ], AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4) if test $fstype = no; then AC_TRY_CPP([#include #include ], AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3) fi if test $fstype = no; then AC_TRY_CPP([#include #include ], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX) fi # (more cases omitted here) AC_MSG_RESULT($fstype) File: autoconf.info, Node: Language Choice, Prev: Multiple Cases, Up: Writing Tests Language Choice =============== Packages that use both C and C++ need to test features of both compilers. Autoconf-generated `configure' scripts check for C features by default. The following macros determine which language's compiler is used in tests that follow in `configure.in'. - Macro: AC_LANG_C Do compilation tests using `CC' and `CPP' and use extension `.c' for test programs. - Macro: AC_LANG_CPLUSPLUS Do compilation tests using `CXX' and `CXXCPP' and use extension `.C' for test programs. - Macro: AC_LANG_SAVE Remember the current language (as set by `AC_LANG_C' or `AC_LANG_CPLUSPLUS') on a stack. Does not change which language is current. Use this macro and `AC_LANG_RESTORE' in macros that need to temporarily switch to a particular language. - Macro: AC_LANG_RESTORE Select the language that is saved on the top of the stack, as set by `AC_LANG_SAVE', and remove it from the stack. This macro is equivalent to either `AC_LANG_C' or `AC_LANG_CPLUSPLUS', whichever had been run most recently when `AC_LANG_SAVE' was last called. Do not call this macro more times than `AC_LANG_SAVE'. - Macro: AC_REQUIRE_CPP Ensure that whichever preprocessor would currently be used for tests has been found. Calls `AC_REQUIRE' (*note Prerequisite Macros::.) with an argument of either `AC_PROG_CPP' or `AC_PROG_CXXCPP', depending on which language is current. File: autoconf.info, Node: Results, Next: Writing Macros, Prev: Writing Tests, Up: Top Results of Tests **************** Once `configure' has determined whether a feature exists, what can it do to record that information? There are four sorts of things it can do: define a C preprocessor symbol, set a variable in the output files, save the result in a cache file for future `configure' runs, and print a message letting the user know the result of the test. * Menu: * Defining Symbols:: Defining C preprocessor symbols. * Setting Output Variables:: Replacing variables in output files. * Caching Results:: Speeding up subsequent `configure' runs. * Printing Messages:: Notifying users of progress or problems. File: autoconf.info, Node: Defining Symbols, Next: Setting Output Variables, Up: Results Defining C Preprocessor Symbols =============================== A common action to take in response to a feature test is to define a C preprocessor symbol indicating the results of the test. That is done by calling `AC_DEFINE' or `AC_DEFINE_UNQUOTED'. By default, `AC_OUTPUT' places the symbols defined by these macros into the output variable `DEFS', which contains an option `-DSYMBOL=VALUE' for each symbol defined. Unlike in Autoconf version 1, there is no variable `DEFS' defined while `configure' is running. To check whether Autoconf macros have already defined a certain C preprocessor symbol, test the value of the appropriate cache variable, as in this example: AC_CHECK_FUNC(vprintf, AC_DEFINE(HAVE_VPRINTF)) if test "$ac_cv_func_vprintf" != yes; then AC_CHECK_FUNC(_doprnt, AC_DEFINE(HAVE_DOPRNT)) fi If `AC_CONFIG_HEADER' has been called, then instead of creating `DEFS', `AC_OUTPUT' creates a header file by substituting the correct values into `#define' statements in a template file. *Note Configuration Headers::, for more information about this kind of output. - Macro: AC_DEFINE (VARIABLE [, VALUE]) Define C preprocessor variable VARIABLE. If VALUE is given, set VARIABLE to that value (verbatim), otherwise set it to 1. VALUE should not contain literal newlines, and if you are not using `AC_CONFIG_HEADER' it should not contain any `#' characters, as `make' tends to eat them. To use a shell variable (which you need to do in order to define a value containing the `m4' quote characters `[' or `]'), use `AC_DEFINE_UNQUOTED' instead. The following example defines the C preprocessor variable `EQUATION' to be the string constant `"$a > $b"': AC_DEFINE(EQUATION, "$a > $b") - Macro: AC_DEFINE_UNQUOTED (VARIABLE [, VALUE]) Like `AC_DEFINE', but three shell expansions are performed--once--on VARIABLE and VALUE: variable expansion (`$'), command substitution (``'), and backslash escaping (`\'). Single and double quote characters in the value have no special meaning. Use this macro instead of `AC_DEFINE' when VARIABLE or VALUE is a shell variable. Examples: AC_DEFINE_UNQUOTED(config_machfile, "${machfile}") AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups) AC_DEFINE_UNQUOTED(${ac_tr_hdr}) Due to the syntactical bizarreness of the Bourne shell, do not use semicolons to separate `AC_DEFINE' or `AC_DEFINE_UNQUOTED' calls from other macro calls or shell code; that can cause syntax errors in the resulting `configure' script. Use either spaces or newlines. That is, do this: AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf") or this: AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf") instead of this: AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf") File: autoconf.info, Node: Setting Output Variables, Next: Caching Results, Prev: Defining Symbols, Up: Results Setting Output Variables ======================== One way to record the results of tests is to set "output variables", which are shell variables whose values are substituted into files that `configure' outputs. The two macros below create new output variables. *Note Preset Output Variables::, for a list of output variables that are always available. - Macro: AC_SUBST (VARIABLE) Create an output variable from a shell variable. Make `AC_OUTPUT' substitute the variable VARIABLE into output files (typically one or more `Makefile's). This means that `AC_OUTPUT' will replace instances of `@VARIABLE@' in input files with the value that the shell variable VARIABLE has when `AC_OUTPUT' is called. The value of VARIABLE should not contain literal newlines. - Macro: AC_SUBST_FILE (VARIABLE) Another way to create an output variable from a shell variable. Make `AC_OUTPUT' insert (without substitutions) the contents of the file named by shell variable VARIABLE into output files. This means that `AC_OUTPUT' will replace instances of `@VARIABLE@' in output files (such as `Makefile.in') with the contents of the file that the shell variable VARIABLE names when `AC_OUTPUT' is called. Set the variable to `/dev/null' for cases that do not have a file to insert. This macro is useful for inserting `Makefile' fragments containing special dependencies or other `make' directives for particular host or target types into `Makefile's. For example, `configure.in' could contain: AC_SUBST_FILE(host_frag)dnl host_frag=$srcdir/conf/sun4.mh and then a `Makefile.in' could contain: @host_frag@ File: autoconf.info, Node: Caching Results, Next: Printing Messages, Prev: Setting Output Variables, Up: Results Caching Results =============== To avoid checking for the same features repeatedly in various `configure' scripts (or repeated runs of one script), `configure' saves the results of many of its checks in a "cache file". If, when a `configure' script runs, it finds a cache file, it reads from it the results from previous runs and avoids rerunning those checks. As a result, `configure' can run much faster than if it had to perform all of the checks every time. - Macro: AC_CACHE_VAL (CACHE-ID, COMMANDS-TO-SET-IT) Ensure that the results of the check identified by CACHE-ID are available. If the results of the check were in the cache file that was read, and `configure' was not given the `--quiet' or `--silent' option, print a message saying that the result was cached; otherwise, run the shell commands COMMANDS-TO-SET-IT. Those commands should have no side effects except for setting the variable CACHE-ID. In particular, they should not call `AC_DEFINE'; the code that follows the call to `AC_CACHE_VAL' should do that, based on the cached value. Also, they should not print any messages, for example with `AC_MSG_CHECKING'; do that before calling `AC_CACHE_VAL', so the messages are printed regardless of whether the results of the check are retrieved from the cache or determined by running the shell commands. If the shell commands are run to determine the value, the value will be saved in the cache file just before `configure' creates its output files. *Note Cache Variable Names::, for how to choose the name of the CACHE-ID variable. * Menu: * Cache Variable Names:: Shell variables used in caches. * Cache Files:: Files `configure' uses for caching. File: autoconf.info, Node: Cache Variable Names, Next: Cache Files, Up: Caching Results Cache Variable Names -------------------- The names of cache variables should have the following format: PACKAGE-PREFIX_cv_VALUE-TYPE_SPECIFIC-VALUE[_ADDITIONAL-OPTIONS] for example, `ac_cv_header_stat_broken' or `ac_cv_prog_gcc_traditional'. The parts of the variable name are: PACKAGE-PREFIX An abbreviation for your package or organization; the same prefix you begin local Autoconf macros with, except lowercase by convention. For cache values used by the distributed Autoconf macros, this value is `ac'. `_cv_' Indicates that this shell variable is a cache value. VALUE-TYPE A convention for classifying cache values, to produce a rational naming system. The values used in Autoconf are listed in *Note Macro Names::. SPECIFIC-VALUE Which member of the class of cache values this test applies to. For example, which function (`alloca'), program (`gcc'), or output variable (`INSTALL'). ADDITIONAL-OPTIONS Any particular behavior of the specific member that this test applies to. For example, `broken' or `set'. This part of the name may be omitted if it does not apply. Like their names, the values that may be assigned to cache variables have a few restrictions. The values may not contain single quotes or curly braces. Usually, their values will be boolean (`yes' or `no') or the names of files or functions; so this is not an important restriction. File: autoconf.info, Node: Cache Files, Prev: Cache Variable Names, Up: Caching Results Cache Files ----------- A cache file is a shell script that caches the results of configure tests run on one system so they can be shared between configure scripts and configure runs. It is not useful on other systems. If its contents are invalid for some reason, the user may delete or edit it. By default, configure uses `./config.cache' as the cache file, creating it if it does not exist already. `configure' accepts the `--cache-file=FILE' option to use a different cache file; that is what `configure' does when it calls `configure' scripts in subdirectories, so they share the cache. Giving `--cache-file=/dev/null' disables caching, for debugging `configure'. *Note Subdirectories::, for information on configuring subdirectories with the `AC_CONFIG_SUBDIRS' macro. `config.status' only pays attention to the cache file if it is given the `--recheck' option, which makes it rerun `configure'. It is wrong to try to distribute cache files for particular system types. There is too much room for error in doing that, and too much administrative overhead in maintaining them. For any features that can't be guessed automatically, use the standard method of the canonical system type and linking files (*note Manual Configuration::.). The cache file on a particular system will gradually accumulate whenever someone runs a `configure' script; it will be initially nonexistent. Running `configure' merges the new cache results with the existing cache file. The site initialization script can specify a site-wide cache file to use instead of the default, to make it work transparently, as long as the same C compiler is used every time (*note Site Defaults::.). File: autoconf.info, Node: Printing Messages, Prev: Caching Results, Up: Results Printing Messages ================= `configure' scripts need to give users running them several kinds of information. The following macros print messages in ways appropriate for each kind. The arguments to all of them get enclosed in shell double quotes, so the shell performs variable and backquote substitution on them. These macros are all wrappers around the `echo' shell command. `configure' scripts should rarely need to run `echo' directly to print messages for the user. Using these macros makes it easy to change how and when each kind of message is printed; such changes need only be made to the macro definitions, and all of the callers change automatically. - Macro: AC_MSG_CHECKING (FEATURE-DESCRIPTION) Notify the user that `configure' is checking for a particular feature. This macro prints a message that starts with `checking ' and ends with `...' and no newline. It must be followed by a call to `AC_MSG_RESULT' to print the result of the check and the newline. The FEATURE-DESCRIPTION should be something like `whether the Fortran compiler accepts C++ comments' or `for c89'. This macro prints nothing if `configure' is run with the `--quiet' or `--silent' option. - Macro: AC_MSG_RESULT (RESULT-DESCRIPTION) Notify the user of the results of a check. RESULT-DESCRIPTION is almost always the value of the cache variable for the check, typically `yes', `no', or a file name. This macro should follow a call to `AC_MSG_CHECKING', and the RESULT-DESCRIPTION should be the completion of the message printed by the call to `AC_MSG_CHECKING'. This macro prints nothing if `configure' is run with the `--quiet' or `--silent' option. - Macro: AC_MSG_ERROR (ERROR-DESCRIPTION) Notify the user of an error that prevents `configure' from completing. This macro prints an error message on the standard error stream and exits `configure' with a nonzero status. eRROR-DESCRIPTION should be something like `invalid value $HOME for \$HOME'. - Macro: AC_MSG_WARN (PROBLEM-DESCRIPTION) Notify the `configure' user of a possible problem. This macro prints the message on the standard error stream; `configure' continues running afterward, so macros that call `AC_MSG_WARN' should provide a default (back-up) behavior for the situations they warn about. PROBLEM-DESCRIPTION should be something like `ln -s seems to make hard links'. The following two macros are an obsolete alternative to `AC_MSG_CHECKING' and `AC_MSG_RESULT'. - Macro: AC_CHECKING (FEATURE-DESCRIPTION) This macro is similar to `AC_MSG_CHECKING', except that it prints a newline after the FEATURE-DESCRIPTION. It is useful mainly to print a general description of the overall purpose of a group of feature checks, e.g., AC_CHECKING(if stack overflow is detectable) - Macro: AC_VERBOSE (RESULT-DESCRIPTION) This macro is similar to `AC_MSG_RESULT', except that it is meant to follow a call to `AC_CHECKING' instead of `AC_MSG_CHECKING'; it starts the message it prints with a tab. It is considered obsolete. File: autoconf.info, Node: Writing Macros, Next: Manual Configuration, Prev: Results, Up: Top Writing Macros ************** When you write a feature test that could be applicable to more than one software package, the best thing to do is encapsulate it in a new macro. Here are some instructions and guidelines for writing Autoconf macros. * Menu: * Macro Definitions:: Basic format of an Autoconf macro. * Macro Names:: What to call your new macros. * Quoting:: Protecting macros from unwanted expansion. * Dependencies Between Macros:: What to do when macros depend on other macros. File: autoconf.info, Node: Macro Definitions, Next: Macro Names, Up: Writing Macros Macro Definitions ================= Autoconf macros are defined using the `AC_DEFUN' macro, which is similar to the `m4' builtin `define' macro. In addition to defining a macro, `AC_DEFUN' adds to it some code which is used to constrain the order in which macros are called (*note Prerequisite Macros::.). An Autoconf macro definition looks like this: AC_DEFUN(MACRO-NAME, [MACRO-BODY]) The square brackets here do not indicate optional text: they should literally be present in the macro definition to avoid macro expansion problems (*note Quoting::.). You can refer to any arguments passed to the macro as `$1', `$2', etc. To introduce comments in `m4', use the `m4' builtin `dnl'; it causes `m4' to discard the text through the next newline. It is not needed between macro definitions in `acsite.m4' and `aclocal.m4', because all output is discarded until `AC_INIT' is called. *Note How to define new macros: (m4.info)Definitions, for more complete information on writing `m4' macros. File: autoconf.info, Node: Macro Names, Next: Quoting, Prev: Macro Definitions, Up: Writing Macros Macro Names =========== All of the Autoconf macros have all-uppercase names starting with `AC_' to prevent them from accidentally conflicting with other text. All shell variables that they use for internal purposes have mostly-lowercase names starting with `ac_'. To ensure that your macros don't conflict with present or future Autoconf macros, you should prefix your own macro names and any shell variables they use with some other sequence. Possibilities include your initials, or an abbreviation for the name of your organization or software package. Most of the Autoconf macros' names follow a structured naming convention that indicates the kind of feature check by the name. The macro names consist of several words, separated by underscores, going from most general to most specific. The names of their cache variables use the same convention (*note Cache Variable Names::., for more information on them). The first word of the name after `AC_' usually tells the category of feature being tested. Here are the categories used in Autoconf for specific test macros, the kind of macro that you are more likely to write. They are also used for cache variables, in all-lowercase. Use them where applicable; where they're not, invent your own categories. C language builtin features. `DECL' Declarations of C variables in header files. `FUNC' Functions in libraries. `GROUP' UNIX group owners of files. `HEADER' Header files. `LIB' C libraries. `PATH' The full path names to files, including programs. `PROG' The base names of programs. `STRUCT' Definitions of C structures in header files. `SYS' Operating system features. `TYPE' C builtin or declared types. `VAR' C variables in libraries. After the category comes the name of the particular feature being tested. Any further words in the macro name indicate particular aspects of the feature. For example, `AC_FUNC_UTIME_NULL' checks the behavior of the `utime' function when called with a `NULL' pointer. A macro that is an internal subroutine of another macro should have a name that starts with the name of that other macro, followed by one or more words saying what the internal macro does. For example, `AC_PATH_X' has internal macros `AC_PATH_X_XMKMF' and `AC_PATH_X_DIRECT'. File: autoconf.info, Node: Quoting, Next: Dependencies Between Macros, Prev: Macro Names, Up: Writing Macros Quoting ======= Macros that are called by other macros are evaluated by `m4' several times; each evaluation might require another layer of quotes to prevent unwanted expansions of macros or `m4' builtins, such as `define' and `$1'. Quotes are also required around macro arguments that contain commas, since commas separate the arguments from each other. It's a good idea to quote any macro arguments that contain newlines or calls to other macros, as well. Autoconf changes the `m4' quote characters from the default ``' and `'' to `[' and `]', because many of the macros use ``' and `'', mismatched. However, in a few places the macros need to use brackets (usually in C program text or regular expressions). In those places, they use the `m4' builtin command `changequote' to temporarily change the quote characters to `<<' and `>>'. (Sometimes, if they don't need to quote anything, they disable quoting entirely instead by setting the quote characters to empty strings.) Here is an example: AC_TRY_LINK( changequote(<<, >>)dnl <<#include #ifndef tzname /* For SGI. */ extern char *tzname[]; /* RS6000 and others reject char **tzname. */ #endif>>, changequote([, ])dnl [atoi(*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) When you create a `configure' script using newly written macros, examine it carefully to check whether you need to add more quotes in your macros. If one or more words have disappeared in the `m4' output, you need more quotes. When in doubt, quote. However, it's also possible to put on too many layers of quotes. If this happens, the resulting `configure' script will contain unexpanded macros. The `autoconf' program checks for this problem by doing `grep AC_ configure'. File: autoconf.info, Node: Dependencies Between Macros, Prev: Quoting, Up: Writing Macros Dependencies Between Macros =========================== Some Autoconf macros depend on other macros having been called first in order to work correctly. Autoconf provides a way to ensure that certain macros are called if needed and a way to warn the user if macros are called in an order that might cause incorrect operation. * Menu: * Prerequisite Macros:: Ensuring required information. * Suggested Ordering:: Warning about possible ordering problems. * Obsolete Macros:: Warning about old ways of doing things. File: autoconf.info, Node: Prerequisite Macros, Next: Suggested Ordering, Up: Dependencies Between Macros Prerequisite Macros ------------------- A macro that you write might need to use values that have previously been computed by other macros. For example, `AC_DECL_YYTEXT' examines the output of `flex' or `lex', so it depends on `AC_PROG_LEX' having been called first to set the shell variable `LEX'. Rather than forcing the user of the macros to keep track of the dependencies between them, you can use the `AC_REQUIRE' macro to do it automatically. `AC_REQUIRE' can ensure that a macro is only called if it is needed, and only called once. - Macro: AC_REQUIRE (MACRO-NAME) If the `m4' macro MACRO-NAME has not already been called, call it (without any arguments). Make sure to quote MACRO-NAME with square brackets. MACRO-NAME must have been defined using `AC_DEFUN' or else contain a call to `AC_PROVIDE' to indicate that it has been called. An alternative to using `AC_DEFUN' is to use `define' and call `AC_PROVIDE'. Because this technique does not prevent nested messages, it is considered obsolete. - Macro: AC_PROVIDE (THIS-MACRO-NAME) Record the fact that THIS-MACRO-NAME has been called. tHIS-MACRO-NAME should be the name of the macro that is calling `AC_PROVIDE'. An easy way to get it is from the `m4' builtin variable `$0', like this: AC_PROVIDE([$0]) File: autoconf.info, Node: Suggested Ordering, Next: Obsolete Macros, Prev: Prerequisite Macros, Up: Dependencies Between Macros Suggested Ordering ------------------ Some macros should be run before another macro if both are called, but neither *requires* that the other be called. For example, a macro that changes the behavior of the C compiler should be called before any macros that run the C compiler. Many of these dependencies are noted in the documentation. Autoconf provides the `AC_BEFORE' macro to warn users when macros with this kind of dependency appear out of order in a `configure.in' file. The warning occurs when creating `configure' from `configure.in', not when running `configure'. For example, `AC_PROG_CPP' checks whether the C compiler can run the C preprocessor when given the `-E' option. It should therefore be called after any macros that change which C compiler is being used, such as `AC_PROG_CC'. So `AC_PROG_CC' contains: AC_BEFORE([$0], [AC_PROG_CPP])dnl This warns the user if a call to `AC_PROG_CPP' has already occurred when `AC_PROG_CC' is called. - Macro: AC_BEFORE (THIS-MACRO-NAME, CALLED-MACRO-NAME) Make `m4' print a warning message on the standard error output if CALLED-MACRO-NAME has already been called. THIS-MACRO-NAME should be the name of the macro that is calling `AC_BEFORE'. The macro CALLED-MACRO-NAME must have been defined using `AC_DEFUN' or else contain a call to `AC_PROVIDE' to indicate that it has been called. File: autoconf.info, Node: Obsolete Macros, Prev: Suggested Ordering, Up: Dependencies Between Macros Obsolete Macros --------------- Configuration and portability technology has evolved over the years. Often better ways of solving a particular problem are developed, or ad-hoc approaches are systematized. This process has occurred in many parts of Autoconf. One result is that some of the macros are now considered "obsolete"; they still work, but are no longer considered the best thing to do. Autoconf provides the `AC_OBSOLETE' macro to warn users producing `configure' scripts when they use obsolete macros, to encourage them to modernize. A sample call is: AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl - Macro: AC_OBSOLETE (THIS-MACRO-NAME [, SUGGESTION]) Make `m4' print a message on the standard error output warning that THIS-MACRO-NAME is obsolete, and giving the file and line number where it was called. THIS-MACRO-NAME should be the name of the macro that is calling `AC_OBSOLETE'. If SUGGESTION is given, it is printed at the end of the warning message; for example, it can be a suggestion for what to use instead of THIS-MACRO-NAME. File: autoconf.info, Node: Manual Configuration, Next: Site Configuration, Prev: Writing Macros, Up: Top Manual Configuration ******************** A few kinds of features can't be guessed automatically by running test programs. For example, the details of the object file format, or special options that need to be passed to the compiler or linker. It is possible to check for such features using ad-hoc means, such as having `configure' check the output of the `uname' program, or looking for libraries that are unique to particular systems. However, Autoconf provides a uniform method for handling unguessable features. * Menu: * Specifying Names:: Specifying the system type. * Canonicalizing:: Getting the canonical system type. * System Type Variables:: Variables containing the system type. * Using System Type:: What to do with the system type. File: autoconf.info, Node: Specifying Names, Next: Canonicalizing, Up: Manual Configuration Specifying the System Type ========================== Like other GNU `configure' scripts, Autoconf-generated `configure' scripts can make decisions based on a canonical name for the system type, which has the form: CPU-COMPANY-SYSTEM `configure' can usually guess the canonical name for the type of system it's running on. To do so it runs a script called `config.guess', which derives the name using the `uname' command or symbols predefined by the C preprocessor. Alternately, the user can specify the system type with command line arguments to `configure'. Doing so is necessary when cross-compiling. In the most complex case of cross-compiling, three system types are involved. The options to specify them are: `--build=BUILD-TYPE' the type of system on which the package is being configured and compiled (rarely needed); `--host=HOST-TYPE' the type of system on which the package will run; `--target=TARGET-TYPE' the type of system for which any compiler tools in the package will produce code. If the user gives `configure' a non-option argument, it is used as the default for the host, target, and build system types if the user does not specify them explicitly with options. The target and build types default to the host type if it is given and they are not. If you are cross-compiling, you still have to specify the names of the cross-tools you use, in particular the C compiler, on the `configure' command line, e.g., CC=m68k-coff-gcc configure --target=m68k-coff `configure' recognizes short aliases for many system types; for example, `decstation' can be given on the command line instead of `mips-dec-ultrix4.2'. `configure' runs a script called `config.sub' to canonicalize system type aliases. File: autoconf.info, Node: Canonicalizing, Next: System Type Variables, Prev: Specifying Names, Up: Manual Configuration Getting the Canonical System Type ================================= The following macros make the system type available to `configure' scripts. They run the shell script `config.guess' to determine any values for the host, target, and build types that they need and the user did not specify on the command line. They run `config.sub' to canonicalize any aliases the user gave. If you use these macros, you must distribute those two shell scripts along with your source code. *Note Output::, for information about the `AC_CONFIG_AUX_DIR' macro which you can use to control which directory `configure' looks for those scripts in. If you do not use either of these macros, `configure' ignores any `--host', `--target', and `--build' options given to it. - Macro: AC_CANONICAL_SYSTEM Determine the system type and set output variables to the names of the canonical system types. *Note System Type Variables::, for details about the variables this macro sets. - Macro: AC_CANONICAL_HOST Perform only the subset of `AC_CANONICAL_SYSTEM' relevant to the host type. This is all that is needed for programs that are not part of a compiler toolchain. File: autoconf.info, Node: System Type Variables, Next: Using System Type, Prev: Canonicalizing, Up: Manual Configuration System Type Variables ===================== After calling `AC_CANONICAL_SYSTEM', the following output variables contain the system type information. After `AC_CANONICAL_HOST', only the `host' variables below are set. ``build', `host', `target'' the canonical system names; ``build_alias', `host_alias', `target_alias'' the names the user specified, or the canonical names if `config.guess' was used; ``build_cpu', `build_vendor', `build_os'' ``host_cpu', `host_vendor', `host_os'' ``target_cpu', `target_vendor', `target_os'' the individual parts of the canonical names (for convenience). File: autoconf.info, Node: Using System Type, Prev: System Type Variables, Up: Manual Configuration Using the System Type ===================== How do you use a canonical system type? Usually, you use it in one or more `case' statements in `configure.in' to select system-specific C files. Then link those files, which have names based on the system name, to generic names, such as `host.h' or `target.c'. The `case' statement patterns can use shell wildcards to group several cases together, like in this fragment: case "$target" in i386-*-mach* | i386-*-gnu*) obj_format=aout emulation=mach bfd_gas=yes ;; i960-*-bout) obj_format=bout ;; esac - Macro: AC_LINK_FILES (SOURCE..., DEST...) Make `AC_OUTPUT' link each of the existing files SOURCE to the corresponding link name DEST. Makes a symbolic link if possible, otherwise a hard link. The DEST and SOURCE names should be relative to the top level source or build directory. For example, this call: AC_LINK_FILES(config/${machine}.h config/${obj_format}.h, host.h object.h) creates in the current directory `host.h', which is a link to `SRCDIR/config/${machine}.h', and `object.h', which is a link to `SRCDIR/config/${obj_format}.h'. File: autoconf.info, Node: Site Configuration, Next: Invoking configure, Prev: Manual Configuration, Up: Top Site Configuration ****************** `configure' scripts support several kinds of local configuration decisions. There are ways for users to specify where external software packages are, include or exclude optional features, install programs under modified names, and set default values for `configure' options. * Menu: * External Software:: Working with other optional software. * Package Options:: Selecting optional features. * Site Details:: Configuring site details. * Transforming Names:: Changing program names when installing. * Site Defaults:: Giving `configure' local defaults. File: autoconf.info, Node: External Software, Next: Package Options, Up: Site Configuration Working With External Software ============================== Some packages require, or can optionally use, other software packages which are already installed. The user can give `configure' command line options to specify which such external software to use. The options have one of these forms: --with-PACKAGE[=ARG] --without-PACKAGE For example, `--with-gnu-ld' means work with the GNU linker instead of some other linker. `--with-x11' means work with X11. The user can give an argument by following the package name with `=' and the argument. Giving an argument of `no' is for packages that are used by default; it says to *not* use the package. An argument that is neither `yes' nor `no' could include a name or number of a version of the other package, to specify more precisely which other package this program is supposed to work with. If no argument is given, it defaults to `yes'. `--without-PACKAGE' is equivalent to `--with-PACKAGE=no'. For each external software package that may be used, `configure.in' should call `AC_ARG_WITH' to detect whether the `configure' user asked to use it. Whether each package is used or not by default, and which arguments are valid, is up to you. - Macro: AC_ARG_WITH (PACKAGE, HELP-STRING, ACTION-IF-TRUE [, ACTION-IF-FALSE]) If the user gave `configure' the option `--with-PACKAGE' or `--without-PACKAGE', run shell commands ACTION-IF-TRUE. Otherwise run shell commands ACTION-IF-FALSE. The name PACKAGE indicates another software package that this program should work with. It should consist only of alphanumeric characters and dashes. The option's argument is available to the shell commands ACTION-IF-TRUE in the shell variable `withval'. The argument HELP-STRING is a description of the option which looks like this: --with-readline support fancy command line editing HELP-STRING may be more than one line long, if more detail is needed. Just make sure the columns line up in `configure --help'. Avoid tabs in the help string. You'll need to enclose it in `[' and `]' in order to produce the leading spaces. - Macro: AC_WITH (PACKAGE, ACTION-IF-TRUE [, ACTION-IF-FALSE]) This is an obsolete version of `AC_ARG_WITH' that does not support providing a help string. File: autoconf.info, Node: Package Options, Next: Site Details, Prev: External Software, Up: Site Configuration Choosing Package Options ======================== If a software package has optional compile-time features, the user can give `configure' command line options to specify whether to compile them. The options have one of these forms: --enable-FEATURE[=ARG] --disable-FEATURE These options allow users to choose which optional features to build and install. `--enable-FEATURE' options should never make a feature behave differently or cause one feature to replace another. They should only cause parts of the program to be built rather than left out. The user can give an argument by following the feature name with `=' and the argument. Giving an argument of `no' requests that the feature *not* be made available. A feature with an argument looks like `--enable-debug=stabs'. If no argument is given, it defaults to `yes'. `--disable-FEATURE' is equivalent to `--enable-FEATURE=no'. For each optional feature, `configure.in' should call `AC_ARG_ENABLE' to detect whether the `configure' user asked to include it. Whether each feature is included or not by default, and which arguments are valid, is up to you. - Macro: AC_ARG_ENABLE (FEATURE, HELP-STRING, ACTION-IF-TRUE [, ACTION-IF-FALSE]) If the user gave `configure' the option `--enable-FEATURE' or `--disable-FEATURE', run shell commands ACTION-IF-TRUE. Otherwise run shell commands ACTION-IF-FALSE. The name FEATURE indicates an optional user-level facility. It should consist only of alphanumeric characters and dashes. The option's argument is available to the shell commands ACTION-IF-TRUE in the shell variable `enableval'. The HELP-STRING argument is like that of `AC_ARG_WITH' (*note External Software::.). - Macro: AC_ENABLE (FEATURE, ACTION-IF-TRUE [, ACTION-IF-FALSE]) This is an obsolete version of `AC_ARG_ENABLE' that does not support providing a help string. File: autoconf.info, Node: Site Details, Next: Transforming Names, Prev: Package Options, Up: Site Configuration Configuring Site Details ======================== Some software packages require complex site-specific information. Some examples are host names to use for certain services, company names, and email addresses to contact. Since some configuration scripts generated by Metaconfig ask for such information interactively, people sometimes wonder how to get that information in Autoconf-generated configuration scripts, which aren't interactive. Such site configuration information should be put in a file that is edited *only by users*, not by programs. The location of the file can either be based on the `prefix' variable, or be a standard location such as the user's home directory. It could even be specified by an environment variable. The programs should examine that file at run time, rather than at compile time. That approach is more convenient for users and makes the configuration process simpler than getting the information while configuring. *Note Variables for Installation Directories: (standards)Directory Variables, for more information on where to put data files.