home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / info / autoconf.info-3 (.txt) < prev    next >
GNU Info File  |  1994-12-22  |  51KB  |  906 lines
  1. This is Info file /gnu/src/amiga/autoconf-2.1/autoconf.info, produced
  2. by Makeinfo-1.55 from the input file
  3. /gnu/src/amiga/autoconf-2.1/autoconf.texi.
  4. START-INFO-DIR-ENTRY
  5. * Autoconf: (autoconf).         Create source code configuration scripts.
  6. END-INFO-DIR-ENTRY
  7.    This file documents the GNU Autoconf package for creating scripts to
  8. configure source code packages using templates and an `m4' macro
  9. package.
  10.    Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc.
  11.    Permission is granted to make and distribute verbatim copies of this
  12. manual provided the copyright notice and this permission notice are
  13. preserved on all copies.
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided that
  16. the entire resulting derived work is distributed under the terms of a
  17. permission notice identical to this one.
  18.    Permission is granted to copy and distribute translations of this
  19. manual into another language, under the above conditions for modified
  20. versions, except that this permission notice may be stated in a
  21. translation approved by the Foundation.
  22. File: autoconf.info,  Node: Run Time,  Next: Portable Shell,  Prev: Examining Libraries,  Up: Writing Tests
  23. Checking Run Time Behavior
  24. ==========================
  25.    Sometimes you need to find out how a system performs at run time,
  26. such as whether a given function has a certain capability or bug.  If
  27. you can, make such checks when your program runs instead of when it is
  28. configured.  You can check for things like the machine's endianness when
  29. your program initializes itself.
  30.    If you really need to test for a run-time behavior while configuring,
  31. you can write a test program to determine the result, and compile and
  32. run it using `AC_TRY_RUN'.  Avoid running test programs if possible,
  33. because using them prevents people from configuring your package for
  34. cross-compiling.
  35. * Menu:
  36. * Test Programs::               Running test programs.
  37. * Guidelines::            General rules for writing test programs.
  38. * Test Functions::        Avoiding pitfalls in test programs.
  39. File: autoconf.info,  Node: Test Programs,  Next: Guidelines,  Up: Run Time
  40. Running Test Programs
  41. ---------------------
  42.    Use the following macro if you need to test run-time behavior of the
  43. system while configuring.
  44.  - Macro: AC_TRY_RUN (PROGRAM, ACTION-IF-TRUE [, ACTION-IF-FALSE [,
  45.           ACTION-IF-CROSS-COMPILING]])
  46.      PROGRAM is the text of a C program, on which shell variable and
  47.      backquote substitutions are performed.  If it compiles and links
  48.      successfully and returns an exit status of 0 when executed, run
  49.      shell commands ACTION-IF-TRUE.  Otherwise run shell commands
  50.      ACTION-IF-FALSE; the exit status of the program is available in
  51.      the shell variable `$?'.  This macro uses `CFLAGS' or `CXXFLAGS',
  52.      `CPPFLAGS', `LDFLAGS', and `LIBS' when compiling.
  53.      If the C compiler being used does not produce executables that run
  54.      on the system where `configure' is being run, then the test
  55.      program is not run.  If the optional shell commands
  56.      ACTION-IF-CROSS-COMPILING are given, they are run instead and this
  57.      macro calls `AC_C_CROSS' if it has not already been called.
  58.      Otherwise, `configure' prints an error message and exits.
  59.    Try to provide a pessimistic default value to use when
  60. cross-compiling makes run-time tests impossible.  You do this by
  61. passing the optional last argument to `AC_TRY_RUN'.  `autoconf' prints
  62. a warning message when creating `configure' each time it encounters a
  63. call to `AC_TRY_RUN' with no ACTION-IF-CROSS-COMPILING argument given.
  64. You may ignore the warning, though users will not be able to configure
  65. your package for cross-compiling.  A few of the macros distributed with
  66. Autoconf produce this warning message.
  67.    To configure for cross-compiling you can also choose a value for
  68. those parameters based on the canonical system name (*note Manual
  69. Configuration::.).  Alternatively, set up a test results cache file with
  70. the correct values for the target system (*note Caching Results::.).
  71.    To provide a default for calls of `AC_TRY_RUN' that are embedded in
  72. other macros, including a few of the ones that come with Autoconf, you
  73. can call `AC_C_CROSS' before running them.  Then, if the shell variable
  74. `cross_compiling' is set to `yes', use an alternate method to get the
  75. results instead of calling the macros.
  76.  - Macro: AC_C_CROSS
  77.      If the C compiler being used does not produce executables that can
  78.      run on the system where `configure' is being run, set the shell
  79.      variable `cross_compiling' to `yes', otherwise `no'.
  80. File: autoconf.info,  Node: Guidelines,  Next: Test Functions,  Prev: Test Programs,  Up: Run Time
  81. Guidelines for Test Programs
  82. ----------------------------
  83.    Test programs should not write anything to the standard output.  They
  84. should return 0 if the test succeeds, nonzero otherwise, so that success
  85. can be distinguished easily from a core dump or other failure;
  86. segmentation violations and other failures produce a nonzero exit
  87. status.  Test programs should `exit', not `return', from `main',
  88. because on some systems (old Suns, at least) the argument to `return'
  89. in `main' is ignored.
  90.    Test programs can use `#if' or `#ifdef' to check the values of
  91. preprocessor macros defined by tests that have already run.  For
  92. example, if you call `AC_HEADER_STDC', then later on in `configure.in'
  93. you can have a test program that includes an ANSI C header file
  94. conditionally:
  95.      #if STDC_HEADERS
  96.      # include <stdlib.h>
  97.      #endif
  98.    If a test program needs to use or create a data file, give it a name
  99. that starts with `conftest', such as `conftestdata'.  The `configure'
  100. script cleans up by running `rm -rf conftest*' after running test
  101. programs and if the script is interrupted.
  102. File: autoconf.info,  Node: Test Functions,  Prev: Guidelines,  Up: Run Time
  103. Test Functions
  104. --------------
  105.    Function declarations in test programs should have a prototype
  106. conditionalized for C++.  In practice, though, test programs rarely need
  107. functions that take arguments.
  108.      #ifdef __cplusplus
  109.      foo(int i)
  110.      #else
  111.      foo(i) int i;
  112.      #endif
  113.    Functions that test programs declare should also be conditionalized
  114. for C++, which requires `extern "C"' prototypes.  Make sure to not
  115. include any header files containing clashing prototypes.
  116.      #ifdef __cplusplus
  117.      extern "C" void *malloc(size_t);
  118.      #else
  119.      char *malloc();
  120.      #endif
  121.    If a test program calls a function with invalid parameters (just to
  122. see whether it exists), organize the program to ensure that it never
  123. invokes that function.  You can do this by calling it in another
  124. function that is never invoked.  You can't do it by putting it after a
  125. call to `exit', because GCC version 2 knows that `exit' never returns
  126. and optimizes out any code that follows it in the same block.
  127.    If you include any header files, make sure to call the functions
  128. relevant to them with the correct number of arguments, even if they are
  129. just 0, to avoid compilation errors due to prototypes.  GCC version 2
  130. has internal prototypes for several functions that it automatically
  131. inlines; for example, `memcpy'.  To avoid errors when checking for
  132. them, either pass them the correct number of arguments or redeclare them
  133. with a different return type (such as `char').
  134. File: autoconf.info,  Node: Portable Shell,  Next: Testing Values and Files,  Prev: Run Time,  Up: Writing Tests
  135. Portable Shell Programming
  136. ==========================
  137.    When writing your own checks, there are some shell script programming
  138. techniques you should avoid in order to make your code portable.  The
  139. Bourne shell and upward-compatible shells like Bash and the Korn shell
  140. have evolved over the years, but to prevent trouble, do not take
  141. advantage of features that were added after UNIX version 7, circa 1977.
  142. You should not use shell functions, aliases, negated character classes,
  143. or other features that are not found in all Bourne-compatible shells;
  144. restrict yourself to the lowest common denominator.  Even `unset' is
  145. not supported by all shells!
  146.    The set of external programs you should run in a `configure' script
  147. is fairly small.  *Note Utilities in Mak