diff options
Diffstat (limited to 'util/autoconf/autoconf.info-3')
| -rw-r--r-- | util/autoconf/autoconf.info-3 | 1198 |
1 files changed, 0 insertions, 1198 deletions
diff --git a/util/autoconf/autoconf.info-3 b/util/autoconf/autoconf.info-3 deleted file mode 100644 index 0cbd5db..0000000 --- a/util/autoconf/autoconf.info-3 +++ /dev/null @@ -1,1198 +0,0 @@ -This is Info file autoconf.info, produced by Makeinfo-1.55 from the -input file ./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 <stdlib.h> - #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 <sys/statvfs.h> - #include <sys/fstyp.h>], AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4) - if test $fstype = no; then - AC_TRY_CPP([#include <sys/statfs.h> - #include <sys/fstyp.h>], AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3) - fi - if test $fstype = no; then - AC_TRY_CPP([#include <sys/statfs.h> - #include <sys/vmount.h>], 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' - 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 <time.h> - #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. - |