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 |
|
|
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 |
|
|
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 |
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 |
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 |
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 |