/[autoconf]/autoconf/doc/autoconf.texi
ViewVC logotype

Diff of /autoconf/doc/autoconf.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.697 by akim, Fri Oct 25 11:52:38 2002 UTC revision 1.698 by akim, Sun Oct 27 18:17:28 2002 UTC
# Line 281  Compilers and Preprocessors Line 281  Compilers and Preprocessors
281    
282  Writing Tests  Writing Tests
283    
284    * Language Choice::             Selecting which language to use for testing
285    * Writing Test Programs::       Forging source files for compilers
286  * Examining Declarations::      Detecting header files and declarations  * Examining Declarations::      Detecting header files and declarations
287  * Examining Syntax::            Detecting language syntax features  * Examining Syntax::            Detecting language syntax features
288  * Examining Libraries::         Detecting functions and global variables  * Examining Libraries::         Detecting functions and global variables
289  * Run Time::                    Testing for run-time features  * Run Time::                    Testing for run-time features
290  * Systemology::                 A zoology of operating systems  * Systemology::                 A zoology of operating systems
291  * Multiple Cases::              Tests for several possible values  * Multiple Cases::              Tests for several possible values
 * Language Choice::             Selecting which language to use for testing  
292    
293  Checking Run Time Behavior  Writing Test Programs
294    
 * Test Programs::               Running test programs  
295  * Guidelines::                  General rules for writing test programs  * Guidelines::                  General rules for writing test programs
296  * Test Functions::              Avoiding pitfalls in test programs  * Test Functions::              Avoiding pitfalls in test programs
297    
# Line 5620  something goes wrong in one or more of t Line 5620  something goes wrong in one or more of t
5620  information can help you understand the assumptions behind them, which  information can help you understand the assumptions behind them, which
5621  might help you figure out how to best solve the problem.  might help you figure out how to best solve the problem.
5622    
5623  These macros check the output of the C compiler system.  They do  These macros check the output of the compiler system of the current
5624  not cache the results of their tests for future use (@pxref{Caching  language (@pxref{Language Choice}).  They do not cache the results of
5625  Results}), because they don't know enough about the information they are  their tests for future use (@pxref{Caching Results}), because they don't
5626  checking for to generate a cache variable name.  They also do not print  know enough about the information they are checking for to generate a
5627  any messages, for the same reason.  The checks for particular kinds of C  cache variable name.  They also do not print any messages, for the same
5628  features call these macros and do cache their results and print messages  reason.  The checks for particular kinds of features call these macros
5629  about what they're checking for.  and do cache their results and print messages about what they're
5630    checking for.
5631    
5632  When you write a feature test that could be applicable to more than one  When you write a feature test that could be applicable to more than one
5633  software package, the best thing to do is encapsulate it in a new macro.  software package, the best thing to do is encapsulate it in a new macro.
5634  @xref{Writing Autoconf Macros}, for how to do that.  @xref{Writing Autoconf Macros}, for how to do that.
5635    
5636  @menu  @menu
5637    * Language Choice::             Selecting which language to use for testing
5638    * Writing Test Programs::       Forging source files for compilers
5639  * Examining Declarations::      Detecting header files and declarations  * Examining Declarations::      Detecting header files and declarations
5640  * Examining Syntax::            Detecting language syntax features  * Examining Syntax::            Detecting language syntax features
5641  * Examining Libraries::         Detecting functions and global variables  * Examining Libraries::         Detecting functions and global variables
5642  * Run Time::                    Testing for run-time features  * Run Time::                    Testing for run-time features
5643  * Systemology::                 A zoology of operating systems  * Systemology::                 A zoology of operating systems
5644  * Multiple Cases::              Tests for several possible values  * Multiple Cases::              Tests for several possible values
 * Language Choice::             Selecting which language to use for testing  
5645  @end menu  @end menu
5646    
5647    @node Language Choice
5648    @section Language Choice
5649    @cindex Language
5650    
5651    Autoconf-generated @command{configure} scripts check for the C compiler and
5652    its features by default.  Packages that use other programming languages
5653    (maybe more than one, e.g., C and C++) need to test features of the
5654    compilers for the respective languages.  The following macros determine
5655    which programming language is used in the subsequent tests in
5656    @file{configure.ac}.
5657    
5658    @defmac AC_LANG (@var{language})
5659    Do compilation tests using the compiler, preprocessor, and file
5660    extensions for the specified @var{language}.
5661    
5662    Supported languages are:
5663    
5664    @table @samp
5665    @item C
5666    Do compilation tests using @code{CC} and @code{CPP} and use extension
5667    @file{.c} for test programs.
5668    
5669    @item C++
5670    Do compilation tests using @code{CXX} and @code{CXXCPP} and use
5671    extension @file{.C} for test programs.
5672    
5673    @item Fortran 77
5674    Do compilation tests using @code{F77} and use extension @file{.f} for
5675    test programs.
5676    @end table
5677    @end defmac
5678    
5679    @defmac AC_LANG_PUSH (@var{language})
5680    @acindex LANG_PUSH
5681    Remember the current language (as set by @code{AC_LANG}) on a stack, and
5682    then select the @var{language}.  Use this macro and @code{AC_LANG_POP}
5683    in macros that need to temporarily switch to a particular language.
5684    @end defmac
5685    
5686    @defmac AC_LANG_POP (@ovar{language})
5687    @acindex LANG_POP
5688    Select the language that is saved on the top of the stack, as set by
5689    @code{AC_LANG_PUSH}, and remove it from the stack.
5690    
5691    If given, @var{language} specifies the language we just @emph{quit}.  It
5692    is a good idea to specify it when it's known (which should be the
5693    case@dots{}), since Autoconf will detect inconsistencies.
5694    
5695    @example
5696    AC_LANG_PUSH(Fortran 77)
5697    # Perform some tests on Fortran 77.
5698    # @dots{}
5699    AC_LANG_POP(Fortran 77)
5700    @end example
5701    @end defmac
5702    
5703    @defmac AC_REQUIRE_CPP
5704    @acindex REQUIRE_CPP
5705    Ensure that whichever preprocessor would currently be used for tests has
5706    been found.  Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
5707    argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
5708    depending on which language is current.
5709    @end defmac
5710    
5711    
5712    @node Writing Test Programs
5713    @section Writing Test Programs
5714    
5715    Autoconf tests follow is common scheme: feeding some program with some
5716    input, and most of the time, feeding a compiler with some source file.
5717    This section is dedicated to these source samples.
5718    
5719    @menu
5720    * Guidelines::                  General rules for writing test programs
5721    * Test Functions::              Avoiding pitfalls in test programs
5722    @end menu
5723    
5724    @node Guidelines
5725    @subsection Guidelines for Test Programs
5726    
5727    Test programs should not write anything to the standard output.  They
5728    should return 0 if the test succeeds, nonzero otherwise, so that success
5729    can be distinguished easily from a core dump or other failure;
5730    segmentation violations and other failures produce a nonzero exit
5731    status.  Test programs should @code{exit}, not @code{return}, from
5732    @code{main}, because on some systems (old Suns, at least) the argument
5733    to @code{return} in @code{main} is ignored.
5734    
5735    Test programs can use @code{#if} or @code{#ifdef} to check the values of
5736    preprocessor macros defined by tests that have already run.  For
5737    example, if you call @code{AC_HEADER_STDC}, then later on in
5738    @file{configure.ac} you can have a test program that includes an
5739    @sc{ansi} C header file conditionally:
5740    
5741    @example
5742    @group
5743    #if STDC_HEADERS
5744    # include <stdlib.h>
5745    #endif
5746    @end group
5747    @end example
5748    
5749    If a test program needs to use or create a data file, give it a name
5750    that starts with @file{conftest}, such as @file{conftest.data}.  The
5751    @command{configure} script cleans up by running @samp{rm -rf conftest*}
5752    after running test programs and if the script is interrupted.
5753    
5754    @node Test Functions
5755    @subsection Test Functions
5756    
5757    Function declarations in test programs should have a prototype
5758    conditionalized for C++.  In practice, though, test programs rarely need
5759    functions that take arguments.
5760    
5761    @example
5762    #ifdef __cplusplus
5763    foo (int i)
5764    #else
5765    foo (i) int i;
5766    #endif
5767    @end example
5768    
5769    Functions that test programs declare should also be conditionalized for
5770    C++, which requires @samp{extern "C"} prototypes.  Make sure to not
5771    include any header files containing clashing prototypes.
5772    
5773    @example
5774    #ifdef __cplusplus
5775    extern "C" void *malloc (size_t);
5776    #else
5777    char *malloc ();
5778    #endif
5779    @end example
5780    
5781    If a test program calls a function with invalid parameters (just to see
5782    whether it exists), organize the program to ensure that it never invokes
5783    that function.  You can do this by calling it in another function that is
5784    never invoked.  You can't do it by putting it after a call to
5785    @code{exit}, because GCC version 2 knows that @code{exit} never returns
5786    and optimizes out any code that follows it in the same block.
5787    
5788    If you include any header files, be sure to call the functions
5789    relevant to them with the correct number of arguments, even if they are
5790    just 0, to avoid compilation errors due to prototypes.  GCC version 2
5791    has internal prototypes for several functions that it automatically
5792    inlines; for example, @code{memcpy}.  To avoid errors when checking for
5793    them, either pass them the correct number of arguments or redeclare them
5794    with a different return type (such as @code{char}).
5795    
5796    
5797    
5798    
5799  @node Examining Declarations  @node Examining Declarations
5800  @section Examining Declarations  @section Examining Declarations
5801    
# Line 5809  run it using @code{AC_TRY_RUN}.  Avoid r Line 5963  run it using @code{AC_TRY_RUN}.  Avoid r
5963  possible, because this prevents people from configuring your package for  possible, because this prevents people from configuring your package for
5964  cross-compiling.  cross-compiling.
5965    
 @menu  
 * Test Programs::               Running test programs  
 * Guidelines::                  General rules for writing test programs  
 * Test Functions::              Avoiding pitfalls in test programs  
 @end menu  
   
 @node Test Programs  
 @subsection Running Test Programs  
   
 Use the following macro if you need to test run-time behavior of the  
 system while configuring.  
   
5966  @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})  @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
5967  @acindex TRY_RUN  @acindex TRY_RUN
5968  If @var{program} compiles and links successfully and returns an exit  If @var{program} compiles and links successfully and returns an exit
# Line 5870  variable @code{cross_compiling} is set t Line 6012  variable @code{cross_compiling} is set t
6012  method to get the results instead of calling the macros.  method to get the results instead of calling the macros.
6013    
6014    
 @node Guidelines  
 @subsection 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 @code{exit}, not @code{return}, from  
 @code{main}, because on some systems (old Suns, at least) the argument  
 to @code{return} in @code{main} is ignored.  
   
 Test programs can use @code{#if} or @code{#ifdef} to check the values of  
 preprocessor macros defined by tests that have already run.  For  
 example, if you call @code{AC_HEADER_STDC}, then later on in  
 @file{configure.ac} you can have a test program that includes an  
 @sc{ansi} C header file conditionally:  
   
 @example  
 @group  
 #if STDC_HEADERS  
 # include <stdlib.h>  
 #endif  
 @end group  
 @end example  
   
 If a test program needs to use or create a data file, give it a name  
 that starts with @file{conftest}, such as @file{conftest.data}.  The  
 @command{configure} script cleans up by running @samp{rm -rf conftest*}  
 after running test programs and if the script is interrupted.  
   
 @node Test Functions  
 @subsection 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.  
   
 @example  
 #ifdef __cplusplus  
 foo (int i)  
 #else  
 foo (i) int i;  
 #endif  
 @end example  
   
 Functions that test programs declare should also be conditionalized for  
 C++, which requires @samp{extern "C"} prototypes.  Make sure to not  
 include any header files containing clashing prototypes.  
   
 @example  
 #ifdef __cplusplus  
 extern "C" void *malloc (size_t);  
 #else  
 char *malloc ();  
 #endif  
 @end example  
   
 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  
 @code{exit}, because GCC version 2 knows that @code{exit} never returns  
 and optimizes out any code that follows it in the same block.  
   
 If you include any header files, be 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, @code{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 @code{char}).  
6015    
6016  @node Systemology  @node Systemology
6017  @section Systemology  @section Systemology
# Line 6029  AC_MSG_RESULT([$fstype]) Line 6100  AC_MSG_RESULT([$fstype])
6100  @end group  @end group
6101  @end example  @end example
6102    
 @node Language Choice  
 @section Language Choice  
 @cindex Language  
   
 Autoconf-generated @command{configure} scripts check for the C compiler and  
 its features by default.  Packages that use other programming languages  
 (maybe more than one, e.g., C and C++) need to test features of the  
 compilers for the respective languages.  The following macros determine  
 which programming language is used in the subsequent tests in  
 @file{configure.ac}.  
   
 @defmac AC_LANG (@var{language})  
 Do compilation tests using the compiler, preprocessor, and file  
 extensions for the specified @var{language}.  
   
 Supported languages are:  
   
 @table @samp  
 @item C  
 Do compilation tests using @code{CC} and @code{CPP} and use extension  
 @file{.c} for test programs.  
   
 @item C++  
 Do compilation tests using @code{CXX} and @code{CXXCPP} and use  
 extension @file{.C} for test programs.  
   
 @item Fortran 77  
 Do compilation tests using @code{F77} and use extension @file{.f} for  
 test programs.  
 @end table  
 @end defmac  
   
 @defmac AC_LANG_PUSH (@var{language})  
 @acindex LANG_PUSH  
 Remember the current language (as set by @code{AC_LANG}) on a stack, and  
 then select the @var{language}.  Use this macro and @code{AC_LANG_POP}  
 in macros that need to temporarily switch to a particular language.  
 @end defmac  
   
 @defmac AC_LANG_POP (@ovar{language})  
 @acindex LANG_POP  
 Select the language that is saved on the top of the stack, as set by  
 @code{AC_LANG_PUSH}, and remove it from the stack.  
   
 If given, @var{language} specifies the language we just @emph{quit}.  It  
 is a good idea to specify it when it's known (which should be the  
 case@dots{}), since Autoconf will detect inconsistencies.  
   
 @example  
 AC_LANG_PUSH(Fortran 77)  
 # Perform some tests on Fortran 77.  
 # @dots{}  
 AC_LANG_POP(Fortran 77)  
 @end example  
 @end defmac  
   
 @defmac AC_REQUIRE_CPP  
 @acindex REQUIRE_CPP  
 Ensure that whichever preprocessor would currently be used for tests has  
 been found.  Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an  
 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},  
 depending on which language is current.  
 @end defmac  
   
   
   
6103  @c ====================================================== Results of Tests.  @c ====================================================== Results of Tests.
6104    
6105  @node Results  @node Results
# Line 7554  args: --cache='' Line 7559  args: --cache=''
7559  end-language: "Autoconf"  end-language: "Autoconf"
7560  @end verbatim  @end verbatim
7561    
 The most typical  
 use is probably to disable caches with Autoconf  
   
7562    
7563  @node Programming in M4sugar  @node Programming in M4sugar
7564  @section Programming in M4sugar  @section Programming in M4sugar

Legend:
Removed from v.1.697  
changed lines
  Added in v.1.698

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26