02-move-sections.patch

[Akim Demaille]

Index: ChangeLog
from  Akim Demaille  <address@hidden>
        Move sections around.
        
        * doc/autoconf.texi (Customizing autom4te): Remove a lost
        sentence.
        Reported by Burno Haible.
        (Language Choice): Now the first section of...
        (Writing Tests): this section.
        Make the introduction less C-centric.
        (Guidelines, Test Functions): Move to...
        (Writing Test Programs): this new section.
        (Test Programs): Merge into...
        (Run Time): this.
        
        
Index: doc/autoconf.texi
--- doc/autoconf.texi Sun, 27 Oct 2002 13:35:48 +0100 akim
+++ doc/autoconf.texi Sun, 27 Oct 2002 14:06:20 +0100 akim
@@ -281,17 +281,17 @@ @node Top
 
 Writing Tests
 
+* Language Choice::             Selecting which language to use for testing
+* Writing Test Programs::       Forging source files for compilers
 * Examining Declarations::      Detecting header files and declarations
 * Examining Syntax::            Detecting language syntax features
 * Examining Libraries::         Detecting functions and global variables
 * Run Time::                    Testing for run-time features
 * Systemology::                 A zoology of operating systems
 * Multiple Cases::              Tests for several possible values
-* Language Choice::             Selecting which language to use for testing
 
-Checking Run Time Behavior
+Writing Test Programs
 
-* Test Programs::               Running test programs
 * Guidelines::                  General rules for writing test programs
 * Test Functions::              Avoiding pitfalls in test programs
 
@@ -5620,28 +5620,182 @@ @node Writing Tests
 information can help you understand the assumptions behind them, which
 might help you figure out how to best solve the problem.
 
-These macros check the output of the C compiler system.  They do
-not cache the results of their tests for future use (@pxref{Caching
-Results}), because they don't know enough about the information they are
-checking for to generate a cache variable name.  They also do not print
-any messages, for the same reason.  The checks for particular kinds of C
-features call these macros and do cache their results and print messages
-about what they're checking for.
+These macros check the output of the compiler system of the current
+language (@pxref{Language Choice}).  They do not cache the results of
+their tests for future use (@pxref{Caching Results}), because they don't
+know enough about the information they are checking for to generate a
+cache variable name.  They also do not print any messages, for the same
+reason.  The checks for particular kinds of features call these macros
+and do cache their results and print messages about what they're
+checking for.
 
 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.
 @xref{Writing Autoconf Macros}, for how to do that.
 
 @menu
+* Language Choice::             Selecting which language to use for testing
+* Writing Test Programs::       Forging source files for compilers
 * Examining Declarations::      Detecting header files and declarations
 * Examining Syntax::            Detecting language syntax features
 * Examining Libraries::         Detecting functions and global variables
 * Run Time::                    Testing for run-time features
 * Systemology::                 A zoology of operating systems
 * Multiple Cases::              Tests for several possible values
-* Language Choice::             Selecting which language to use for testing
 @end menu
 
address@hidden Language Choice
address@hidden Language Choice
address@hidden 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
address@hidden
+
address@hidden AC_LANG (@var{language})
+Do compilation tests using the compiler, preprocessor, and file
+extensions for the specified @var{language}.
+
+Supported languages are:
+
address@hidden @samp
address@hidden C
+Do compilation tests using @code{CC} and @code{CPP} and use extension
address@hidden for test programs.
+
address@hidden C++
+Do compilation tests using @code{CXX} and @code{CXXCPP} and use
+extension @file{.C} for test programs.
+
address@hidden Fortran 77
+Do compilation tests using @code{F77} and use extension @file{.f} for
+test programs.
address@hidden table
address@hidden defmac
+
address@hidden AC_LANG_PUSH (@var{language})
address@hidden 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.
address@hidden defmac
+
address@hidden AC_LANG_POP (@ovar{language})
address@hidden LANG_POP
+Select the language that is saved on the top of the stack, as set by
address@hidden, 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
address@hidden), since Autoconf will detect inconsistencies.
+
address@hidden
+AC_LANG_PUSH(Fortran 77)
+# Perform some tests on Fortran 77.
+# @dots{}
+AC_LANG_POP(Fortran 77)
address@hidden example
address@hidden defmac
+
address@hidden AC_REQUIRE_CPP
address@hidden 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.
address@hidden defmac
+
+
address@hidden Writing Test Programs
address@hidden Writing Test Programs
+
+Autoconf tests follow is common scheme: feeding some program with some
+input, and most of the time, feeding a compiler with some source file.
+This section is dedicated to these source samples.
+
address@hidden
+* Guidelines::                  General rules for writing test programs
+* Test Functions::              Avoiding pitfalls in test programs
address@hidden menu
+
address@hidden Guidelines
address@hidden 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
address@hidden, 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
address@hidden you can have a test program that includes an
address@hidden C header file conditionally:
+
address@hidden
address@hidden
+#if STDC_HEADERS
+# include <stdlib.h>
+#endif
address@hidden group
address@hidden 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
address@hidden script cleans up by running @samp{rm -rf conftest*}
+after running test programs and if the script is interrupted.
+
address@hidden Test Functions
address@hidden 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.
+
address@hidden
+#ifdef __cplusplus
+foo (int i)
+#else
+foo (i) int i;
+#endif
address@hidden 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.
+
address@hidden
+#ifdef __cplusplus
+extern "C" void *malloc (size_t);
+#else
+char *malloc ();
+#endif
address@hidden 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
address@hidden, 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}).
+
+
+
+
 @node Examining Declarations
 @section Examining Declarations
 
@@ -5809,18 +5963,6 @@ @node Run Time
 possible, because this prevents people from configuring your package for
 cross-compiling.
 
address@hidden
-* Test Programs::               Running test programs
-* Guidelines::                  General rules for writing test programs
-* Test Functions::              Avoiding pitfalls in test programs
address@hidden menu
-
address@hidden Test Programs
address@hidden Running Test Programs
-
-Use the following macro if you need to test run-time behavior of the
-system while configuring.
-
 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, 
@ovar{action-if-false}, @ovar{action-if-cross-compiling})
 @acindex TRY_RUN
 If @var{program} compiles and links successfully and returns an exit
@@ -5870,77 +6012,6 @@ @node Test Programs
 method to get the results instead of calling the macros.
 
 
address@hidden Guidelines
address@hidden 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
address@hidden, 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
address@hidden you can have a test program that includes an
address@hidden C header file conditionally:
-
address@hidden
address@hidden
-#if STDC_HEADERS
-# include <stdlib.h>
-#endif
address@hidden group
address@hidden 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
address@hidden script cleans up by running @samp{rm -rf conftest*}
-after running test programs and if the script is interrupted.
-
address@hidden Test Functions
address@hidden 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.
-
address@hidden
-#ifdef __cplusplus
-foo (int i)
-#else
-foo (i) int i;
-#endif
address@hidden 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.
-
address@hidden
-#ifdef __cplusplus
-extern "C" void *malloc (size_t);
-#else
-char *malloc ();
-#endif
address@hidden 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
address@hidden, 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}).
 
 @node Systemology
 @section Systemology
@@ -6029,72 +6100,6 @@ @node Multiple Cases
 @end group
 @end example
 
address@hidden Language Choice
address@hidden Language Choice
address@hidden 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
address@hidden
-
address@hidden AC_LANG (@var{language})
-Do compilation tests using the compiler, preprocessor, and file
-extensions for the specified @var{language}.
-
-Supported languages are:
-
address@hidden @samp
address@hidden C
-Do compilation tests using @code{CC} and @code{CPP} and use extension
address@hidden for test programs.
-
address@hidden C++
-Do compilation tests using @code{CXX} and @code{CXXCPP} and use
-extension @file{.C} for test programs.
-
address@hidden Fortran 77
-Do compilation tests using @code{F77} and use extension @file{.f} for
-test programs.
address@hidden table
address@hidden defmac
-
address@hidden AC_LANG_PUSH (@var{language})
address@hidden 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.
address@hidden defmac
-
address@hidden AC_LANG_POP (@ovar{language})
address@hidden LANG_POP
-Select the language that is saved on the top of the stack, as set by
address@hidden, 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
address@hidden), since Autoconf will detect inconsistencies.
-
address@hidden
-AC_LANG_PUSH(Fortran 77)
-# Perform some tests on Fortran 77.
-# @dots{}
-AC_LANG_POP(Fortran 77)
address@hidden example
address@hidden defmac
-
address@hidden AC_REQUIRE_CPP
address@hidden 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.
address@hidden defmac
-
-
-
 @c ====================================================== Results of Tests.
 
 @node Results
@@ -7553,9 +7558,6 @@ begin-language: "Autoconf"
 args: --cache=''
 end-language: "Autoconf"
 @end verbatim
-
-The most typical
-use is probably to disable caches with Autoconf
 
 
 @node Programming in M4sugar