From fdfebffaf7814f4b7db38d0740c057daa67e150f Mon Sep 17 00:00:00 2001 From: Alexandre Duret-Lutz Date: Sun, 6 Feb 2005 10:32:59 +0000 Subject: [PATCH] * doc/automake.texi (aclocal options, Macro search path, Extending aclocal, Local Macros, Serials, Future of aclocal): Make these subsection of ... (Invoking aclocal): ... this. --- ChangeLog | 5 + doc/automake.texi | 500 +++++++++++++++++++++++----------------------- 2 files changed, 253 insertions(+), 252 deletions(-) diff --git a/ChangeLog b/ChangeLog index b277c528a..c9cfae58f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,10 @@ 2005-02-06 Alexandre Duret-Lutz + * doc/automake.texi (aclocal options, Macro search path, + Extending aclocal, Local Macros, Serials, Future of aclocal): Make + these subsection of ... + (Invoking aclocal): ... this. + * aclocal.in ($serial_line_rx): Allow trailing garbage after the serial number. (scan_file): Explicitly mark the "ill-formed serial" message diff --git a/doc/automake.texi b/doc/automake.texi index 1b9518dff..f2951d6fc 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -135,18 +135,16 @@ Scanning @file{configure.ac} * Requirements:: Configuration requirements * Optional:: Other things Automake recognizes * Invoking aclocal:: Auto-generating aclocal.m4 -* aclocal options:: aclocal command line arguments -* Macro search path:: Modifying aclocal's search path * Macros:: Autoconf macros supplied with Automake -* Extending aclocal:: Writing your own aclocal macros -* Local Macros:: Organizing local macros -* Serials:: #serial lines in Autoconf macros -* Future of aclocal:: aclocal's scheduled death Auto-generating aclocal.m4 * aclocal options:: Options supported by aclocal * Macro search path:: How aclocal finds .m4 files +* Extending aclocal:: Writing your own aclocal macros +* Local Macros:: Organizing local macros +* Serials:: Serial lines in Autoconf macros +* Future of aclocal:: aclocal's scheduled death Autoconf macros supplied with Automake @@ -1265,13 +1263,7 @@ easier. These macros can automatically be put into your * Requirements:: Configuration requirements * Optional:: Other things Automake recognizes * Invoking aclocal:: Auto-generating aclocal.m4 -* aclocal options:: aclocal command line arguments -* Macro search path:: Modifying aclocal's search path * Macros:: Autoconf macros supplied with Automake -* Extending aclocal:: Writing your own aclocal macros -* Local Macros:: Organizing local macros -* Serials:: #serial lines in Autoconf macros -* Future of aclocal:: aclocal's scheduled death @end menu @@ -1634,10 +1626,14 @@ just as @code{autoconf}. Its location can be overridden using the @menu * aclocal options:: Options supported by aclocal * Macro search path:: How aclocal finds .m4 files +* Extending aclocal:: Writing your own aclocal macros +* Local Macros:: Organizing local macros +* Serials:: Serial lines in Autoconf macros +* Future of aclocal:: aclocal's scheduled death @end menu @node aclocal options -@section aclocal options +@subsection aclocal options @cindex @command{aclocal}, Options @cindex Options, @command{aclocal} @@ -1730,7 +1726,7 @@ way as it is for @command{automake} (@pxref{Invoking Automake}). @end table @node Macro search path -@section Macro search path +@subsection Macro search path @cindex Macro search path @cindex @command{aclocal} search path @@ -1764,7 +1760,7 @@ As an example, suppose that automake-1.6.2 was configured with As explained in (@pxref{aclocal options}), there are several options that can be used to change or extend this search path. -@subsection Modifying the macro search path: @code{--acdir} +@subsubsection Modifying the macro search path: @code{--acdir} The most erroneous option to modify the search path is @code{--acdir=@var{dir}}, which changes default directory and @@ -1778,7 +1774,7 @@ drops the @var{APIVERSION} directory. For example, if one specifies This option, @code{--acdir}, is intended for use by the internal automake test suite only; it is not ordinarily needed by end-users. -@subsection Modifying the macro search path: @code{-I @var{dir}} +@subsubsection Modifying the macro search path: @code{-I @var{dir}} Any extra directories specified using @code{-I} options (@pxref{aclocal options}) are @emph{prepended} to this search list. Thus, @@ -1791,7 +1787,7 @@ Any extra directories specified using @code{-I} options @item @var{acdir} @end enumerate -@subsection Modifying the macro search path: @file{dirlist} +@subsubsection Modifying the macro search path: @file{dirlist} @cindex @file{dirlist} There is a third mechanism for customizing the search path. If a @@ -1871,239 +1867,8 @@ copy Automake on your account and want @command{aclocal} to look for macros installed at other places on the system. -@node Macros -@section Autoconf macros supplied with Automake - -Automake ships with several Autoconf macros that you can use from your -@file{configure.ac}. When you use one of them it will be included by -@code{aclocal} in @file{aclocal.m4}. - -@menu -* Public macros:: Macros that you can use. -* Private macros:: Macros that you should not use. -@end menu - -@c consider generating the following subsections automatically from m4 files. - -@node Public macros -@subsection Public macros - -@table @code -@item AM_CONFIG_HEADER -@acindex AM_CONFIG_HEADER -Automake will generate rules to automatically regenerate the config -header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS} -today (@pxref{Optional}). - -@item AM_ENABLE_MULTILIB -@acindex AM_ENABLE_MULTILIB -This is used when a ``multilib'' library is being built. The first -optional argument is the name of the @file{Makefile} being generated; it -defaults to @samp{Makefile}. The second option argument is used to find -the top source directory; it defaults to the empty string (generally -this should not be used unless you are familiar with the internals). -@xref{Multilibs}. - -@item AM_C_PROTOTYPES -@acindex AM_C_PROTOTYPES -@vindex ANSI2KNR -@vindex U -Check to see if function prototypes are understood by the compiler. If -so, define @samp{PROTOTYPES} and set the output variables @samp{U} and -@samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to -@samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these -values to implement automatic de-ANSI-fication. - -@item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL -@acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL -If the use of @code{TIOCGWINSZ} requires @file{}, then -define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be -found in @file{}. This macro is obsolete, you should -use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead. - -@item AM_INIT_AUTOMAKE([OPTIONS]) -@itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE]) -@acindex AM_INIT_AUTOMAKE -Runs many macros required for proper operation of the generated Makefiles. - -@vindex AUTOMAKE_OPTIONS -This macro has two forms, the first of which is preferred. -In this form, @code{AM_INIT_AUTOMAKE} is called with a -single argument --- a space-separated list of Automake options which should -be applied to every @file{Makefile.am} in the tree. The effect is as if -each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}). - -@acindex AC_INIT -The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required -arguments: the package and the version number. This form is -obsolete because the @var{package} and @var{version} can be obtained -from Autoconf's @code{AC_INIT} macro (which itself has an old and a new -form). - -If your @file{configure.ac} has: - -@example -AC_INIT(src/foo.c) -AM_INIT_AUTOMAKE(mumble, 1.5) -@end example - -@noindent -you can modernize it as follows: - -@example -AC_INIT(mumble, 1.5) -AC_CONFIG_SRCDIR(src/foo.c) -AM_INIT_AUTOMAKE -@end example - -Note that if you're upgrading your @file{configure.ac} from an earlier -version of Automake, it is not always correct to simply move the package -and version arguments from @code{AM_INIT_AUTOMAKE} directly to -@code{AC_INIT}, as in the example above. The first argument to -@code{AC_INIT} should be the name of your package (e.g. @samp{GNU Automake}), -not the tarball name (e.g. @samp{automake}) that you used to pass to -@code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a tarball name from -the package name, which should work for most but not all package names. -(If it doesn't work for yours, you can use the -four-argument form of @code{AC_INIT} --- supported in Autoconf versions -greater than 2.52g --- to provide the tarball name explicitly). - -@cindex @code{PACKAGE}, prevent definition -@cindex @code{VERSION}, prevent definition -@opindex no-define -By default this macro @code{AC_DEFINE}'s @samp{PACKAGE} and -@samp{VERSION}. This can be avoided by passing the @samp{no-define} -option, as in: -@example -AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2]) -@end example -or by passing a third non-empty argument to the obsolete form. - -@item AM_PATH_LISPDIR -@acindex AM_PATH_LISPDIR -@vindex EMACS -@vindex lispdir -Searches for the program @code{emacs}, and, if found, sets the output -variable @code{lispdir} to the full path to Emacs' site-lisp directory. - -Note that this test assumes the @code{emacs} found to be a version that -supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other emacsen -can cause this test to hang (some, like old versions of MicroEmacs, -start up in interactive mode, requiring @samp{C-x C-c} to exit, which -is hardly obvious for a non-emacs user). In most cases, however, you -should be able to use @samp{C-c} to kill the test. In order to avoid -problems, you can set @code{EMACS} to ``no'' in the environment, or -use the @samp{--with-lispdir} option to @command{configure} to -explicitly set the correct path (if you're sure you have an @code{emacs} -that supports Emacs Lisp. - -@item AM_PROG_AS -@acindex AM_PROG_AS -@vindex CCAS -@vindex CCASFLAGS -Use this macro when you have assembly code in your project. This will -choose the assembler for you (by default the C compiler) and set -@code{CCAS}, and will also set @code{CCASFLAGS} if required. - -@item AM_PROG_CC_C_O -@acindex AM_PROG_CC_C_O -@acindex AC_PROG_CC_C_O -This is like @code{AC_PROG_CC_C_O}, but it generates its results in -the manner required by automake. You must use this instead of -@code{AC_PROG_CC_C_O} when you need this functionality, that is, when -using per-target flags or subdir-objects with C sources. - -@item AM_PROG_LEX -@acindex AM_PROG_LEX -@acindex AC_PROG_LEX -@cindex HP-UX 10, @command{lex} problems -@cindex @command{lex} problems with HP-UX 10 -Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular -Program Checks, autoconf, The Autoconf Manual}), but uses the -@code{missing} script on systems that do not have @code{lex}. -@samp{HP-UX 10} is one such system. - -@item AM_PROG_GCJ -@acindex AM_PROG_GCJ -@vindex GCJ -@vindex GCJFLAGS -This macro finds the @code{gcj} program or causes an error. It sets -@samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the -GNU Compiler Collection. - -@item AM_SYS_POSIX_TERMIOS -@acindex AM_SYS_POSIX_TERMIOS -@cindex POSIX termios headers -@cindex termios POSIX headers -Check to see if POSIX termios headers and functions are available on the -system. If so, set the shell variable @code{am_cv_sys_posix_termios} to -@samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete, -you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead. - -@item AM_WITH_DMALLOC -@acindex AM_WITH_DMALLOC -@cindex @command{dmalloc}, support for -@vindex WITH_DMALLOC -@opindex --with-dmalloc -Add support for the -@uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc} -package. If the user configures with @samp{--with-dmalloc}, then define -@code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}. - -@item AM_WITH_REGEX -@acindex AM_WITH_REGEX -@vindex WITH_REGEX -@opindex --with-regex -@cindex regex package -@cindex rx package -Adds @samp{--with-regex} to the @code{configure} command line. If -specified (the default), then the @samp{regex} regular expression -library is used, @file{regex.o} is put into @samp{LIBOBJS}, and -@samp{WITH_REGEX} is defined. If @samp{--without-regex} is given, then -the @samp{rx} regular expression library is used, and @file{rx.o} is put -into @samp{LIBOBJS}. - -@end table - -@node Private macros -@subsection Private macros - -The following macros are private macros you should not call directly. -They are called by the other public macros when appropriate. Do not -rely on them, as they might be changed in a future version. Consider -them as implementation details; or better, do not consider them at all: -skip this section! - -@ftable @code -@item _AM_DEPENDENCIES -@itemx AM_SET_DEPDIR -@itemx AM_DEP_TRACK -@itemx AM_OUTPUT_DEPENDENCY_COMMANDS -These macros are used to implement Automake's automatic dependency -tracking scheme. They are called automatically by automake when -required, and there should be no need to invoke them manually. - -@item AM_MAKE_INCLUDE -This macro is used to discover how the user's @code{make} handles -@code{include} statements. This macro is automatically invoked when -needed; there should be no need to invoke it manually. - -@item AM_PROG_INSTALL_STRIP -This is used to find a version of @code{install} which can be used to -@code{strip} a program at installation time. This macro is -automatically included when required. - -@item AM_SANITY_CHECK -This checks to make sure that a file created in the build directory is -newer than a file in the source directory. This can fail on systems -where the clock is set incorrectly. This macro is automatically run -from @code{AM_INIT_AUTOMAKE}. - -@end ftable - - @node Extending aclocal -@section Writing your own aclocal macros +@subsection Writing your own aclocal macros @cindex @command{aclocal}, extending @cindex Extending @command{aclocal} @@ -2188,7 +1953,7 @@ manage macros which are used locally by the package, @ref{Local Macros}. @node Local Macros -@section Handling Local Macros +@subsection Handling Local Macros Feature tests offered by Autoconf do not cover all needs. People often have to supplement existing tests with their own macros, or @@ -2292,7 +2057,7 @@ other people to use it. @node Serials -@section Serial Numbers +@subsection Serial Numbers @cindex serial numbers in macros @cindex macro serial numbers @cindex @code{#serial} syntax @@ -2441,7 +2206,7 @@ revert, and run @code{aclocal -I m4 --install}. @node Future of aclocal -@section The Future of @command{aclocal} +@subsection The Future of @command{aclocal} @cindex @command{aclocal}'s scheduled death @command{aclocal} is expected to disappear. This feature really @@ -2489,6 +2254,237 @@ written (@pxref{Extending aclocal}). +@node Macros +@section Autoconf macros supplied with Automake + +Automake ships with several Autoconf macros that you can use from your +@file{configure.ac}. When you use one of them it will be included by +@code{aclocal} in @file{aclocal.m4}. + +@menu +* Public macros:: Macros that you can use. +* Private macros:: Macros that you should not use. +@end menu + +@c consider generating the following subsections automatically from m4 files. + +@node Public macros +@subsection Public macros + +@table @code +@item AM_CONFIG_HEADER +@acindex AM_CONFIG_HEADER +Automake will generate rules to automatically regenerate the config +header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS} +today (@pxref{Optional}). + +@item AM_ENABLE_MULTILIB +@acindex AM_ENABLE_MULTILIB +This is used when a ``multilib'' library is being built. The first +optional argument is the name of the @file{Makefile} being generated; it +defaults to @samp{Makefile}. The second option argument is used to find +the top source directory; it defaults to the empty string (generally +this should not be used unless you are familiar with the internals). +@xref{Multilibs}. + +@item AM_C_PROTOTYPES +@acindex AM_C_PROTOTYPES +@vindex ANSI2KNR +@vindex U +Check to see if function prototypes are understood by the compiler. If +so, define @samp{PROTOTYPES} and set the output variables @samp{U} and +@samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to +@samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these +values to implement automatic de-ANSI-fication. + +@item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL +@acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL +If the use of @code{TIOCGWINSZ} requires @file{}, then +define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be +found in @file{}. This macro is obsolete, you should +use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead. + +@item AM_INIT_AUTOMAKE([OPTIONS]) +@itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE]) +@acindex AM_INIT_AUTOMAKE +Runs many macros required for proper operation of the generated Makefiles. + +@vindex AUTOMAKE_OPTIONS +This macro has two forms, the first of which is preferred. +In this form, @code{AM_INIT_AUTOMAKE} is called with a +single argument --- a space-separated list of Automake options which should +be applied to every @file{Makefile.am} in the tree. The effect is as if +each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}). + +@acindex AC_INIT +The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required +arguments: the package and the version number. This form is +obsolete because the @var{package} and @var{version} can be obtained +from Autoconf's @code{AC_INIT} macro (which itself has an old and a new +form). + +If your @file{configure.ac} has: + +@example +AC_INIT(src/foo.c) +AM_INIT_AUTOMAKE(mumble, 1.5) +@end example + +@noindent +you can modernize it as follows: + +@example +AC_INIT(mumble, 1.5) +AC_CONFIG_SRCDIR(src/foo.c) +AM_INIT_AUTOMAKE +@end example + +Note that if you're upgrading your @file{configure.ac} from an earlier +version of Automake, it is not always correct to simply move the package +and version arguments from @code{AM_INIT_AUTOMAKE} directly to +@code{AC_INIT}, as in the example above. The first argument to +@code{AC_INIT} should be the name of your package (e.g. @samp{GNU Automake}), +not the tarball name (e.g. @samp{automake}) that you used to pass to +@code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a tarball name from +the package name, which should work for most but not all package names. +(If it doesn't work for yours, you can use the +four-argument form of @code{AC_INIT} --- supported in Autoconf versions +greater than 2.52g --- to provide the tarball name explicitly). + +@cindex @code{PACKAGE}, prevent definition +@cindex @code{VERSION}, prevent definition +@opindex no-define +By default this macro @code{AC_DEFINE}'s @samp{PACKAGE} and +@samp{VERSION}. This can be avoided by passing the @samp{no-define} +option, as in: +@example +AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2]) +@end example +or by passing a third non-empty argument to the obsolete form. + +@item AM_PATH_LISPDIR +@acindex AM_PATH_LISPDIR +@vindex EMACS +@vindex lispdir +Searches for the program @code{emacs}, and, if found, sets the output +variable @code{lispdir} to the full path to Emacs' site-lisp directory. + +Note that this test assumes the @code{emacs} found to be a version that +supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other emacsen +can cause this test to hang (some, like old versions of MicroEmacs, +start up in interactive mode, requiring @samp{C-x C-c} to exit, which +is hardly obvious for a non-emacs user). In most cases, however, you +should be able to use @samp{C-c} to kill the test. In order to avoid +problems, you can set @code{EMACS} to ``no'' in the environment, or +use the @samp{--with-lispdir} option to @command{configure} to +explicitly set the correct path (if you're sure you have an @code{emacs} +that supports Emacs Lisp. + +@item AM_PROG_AS +@acindex AM_PROG_AS +@vindex CCAS +@vindex CCASFLAGS +Use this macro when you have assembly code in your project. This will +choose the assembler for you (by default the C compiler) and set +@code{CCAS}, and will also set @code{CCASFLAGS} if required. + +@item AM_PROG_CC_C_O +@acindex AM_PROG_CC_C_O +@acindex AC_PROG_CC_C_O +This is like @code{AC_PROG_CC_C_O}, but it generates its results in +the manner required by automake. You must use this instead of +@code{AC_PROG_CC_C_O} when you need this functionality, that is, when +using per-target flags or subdir-objects with C sources. + +@item AM_PROG_LEX +@acindex AM_PROG_LEX +@acindex AC_PROG_LEX +@cindex HP-UX 10, @command{lex} problems +@cindex @command{lex} problems with HP-UX 10 +Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular +Program Checks, autoconf, The Autoconf Manual}), but uses the +@code{missing} script on systems that do not have @code{lex}. +@samp{HP-UX 10} is one such system. + +@item AM_PROG_GCJ +@acindex AM_PROG_GCJ +@vindex GCJ +@vindex GCJFLAGS +This macro finds the @code{gcj} program or causes an error. It sets +@samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the +GNU Compiler Collection. + +@item AM_SYS_POSIX_TERMIOS +@acindex AM_SYS_POSIX_TERMIOS +@cindex POSIX termios headers +@cindex termios POSIX headers +Check to see if POSIX termios headers and functions are available on the +system. If so, set the shell variable @code{am_cv_sys_posix_termios} to +@samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete, +you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead. + +@item AM_WITH_DMALLOC +@acindex AM_WITH_DMALLOC +@cindex @command{dmalloc}, support for +@vindex WITH_DMALLOC +@opindex --with-dmalloc +Add support for the +@uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc} +package. If the user configures with @samp{--with-dmalloc}, then define +@code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}. + +@item AM_WITH_REGEX +@acindex AM_WITH_REGEX +@vindex WITH_REGEX +@opindex --with-regex +@cindex regex package +@cindex rx package +Adds @samp{--with-regex} to the @code{configure} command line. If +specified (the default), then the @samp{regex} regular expression +library is used, @file{regex.o} is put into @samp{LIBOBJS}, and +@samp{WITH_REGEX} is defined. If @samp{--without-regex} is given, then +the @samp{rx} regular expression library is used, and @file{rx.o} is put +into @samp{LIBOBJS}. + +@end table + +@node Private macros +@subsection Private macros + +The following macros are private macros you should not call directly. +They are called by the other public macros when appropriate. Do not +rely on them, as they might be changed in a future version. Consider +them as implementation details; or better, do not consider them at all: +skip this section! + +@ftable @code +@item _AM_DEPENDENCIES +@itemx AM_SET_DEPDIR +@itemx AM_DEP_TRACK +@itemx AM_OUTPUT_DEPENDENCY_COMMANDS +These macros are used to implement Automake's automatic dependency +tracking scheme. They are called automatically by automake when +required, and there should be no need to invoke them manually. + +@item AM_MAKE_INCLUDE +This macro is used to discover how the user's @code{make} handles +@code{include} statements. This macro is automatically invoked when +needed; there should be no need to invoke it manually. + +@item AM_PROG_INSTALL_STRIP +This is used to find a version of @code{install} which can be used to +@code{strip} a program at installation time. This macro is +automatically included when required. + +@item AM_SANITY_CHECK +This checks to make sure that a file created in the build directory is +newer than a file in the source directory. This can fail on systems +where the clock is set incorrectly. This macro is automatically run +from @code{AM_INIT_AUTOMAKE}. + +@end ftable + + @node Directories @chapter Directories -- 2.47.2