diff options
Diffstat (limited to 'doc/automake.texi')
-rw-r--r-- | doc/automake.texi | 126 |
1 files changed, 71 insertions, 55 deletions
diff --git a/doc/automake.texi b/doc/automake.texi index 59bc2f8c7..37c858087 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -62,6 +62,7 @@ section entitled ``GNU Free Documentation License.'' @insertcopying @end titlepage +@shortcontents @contents @c We use the following macros to define indices: @@ -192,6 +193,7 @@ Auto-generating aclocal.m4 Autoconf macros supplied with Automake * Public Macros:: Macros that you can use. +* Obsolete Macros:: Macros that will soon be removed. * Private Macros:: Macros that you should not use. Directories @@ -256,6 +258,10 @@ Common Issues Related to Libtool's Use * Error required file ltmain.sh not found:: The need to run libtoolize * Objects created both with libtool and without:: Avoid a specific build race +Yacc and Lex support + +* Linking Multiple Yacc Parsers:: + Fortran 77 Support * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources @@ -312,7 +318,7 @@ What Goes in a Distribution Support for test suites -* Generalities about Testing:: Generic concepts and terminology about testing +* Generalities about Testing:: Concepts and terminology about testing * Simple Tests:: Listing test scripts in @code{TESTS} * Custom Test Drivers:: Writing and using custom test drivers * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol @@ -325,13 +331,6 @@ Simple Tests * Serial Test Harness:: Older (and discouraged) serial test harness * Parallel Test Harness:: Generic concurrent test harness -Using the TAP test protocol - -* Introduction to TAP:: -* Use TAP with the Automake test harness:: -* Incompatibilities with other TAP parsers and drivers:: -* Links and external resources on TAP:: - Custom Test Drivers * Overview of Custom Test Drivers Support:: @@ -344,6 +343,13 @@ API for Custom Test Drivers * Log files generation and test results recording:: * Testsuite progress output:: +Using the TAP test protocol + +* Introduction to TAP:: +* Use TAP with the Automake test harness:: +* Incompatibilities with other TAP parsers and drivers:: +* Links and external resources on TAP:: + Changing Automake's Behavior * Options generalities:: Semantics of Automake option @@ -359,7 +365,7 @@ Conditionals * Usage of Conditionals:: Declaring conditional content * Limits of Conditionals:: Enclosing complete statements -Silencing Make +Silencing @command{make} * Make verbosity:: Make is verbose by default * Tricks For Silencing Make:: Standard and generic ways to silence make @@ -4599,11 +4605,10 @@ recursion will probably come as unwelcome advice. For those who haven't read the paper, Miller's main thesis is that recursive @command{make} invocations are both slow and error-prone. -Automake provides sufficient cross-directory support @footnote{We -believe. This work is new and there are probably warts. -@xref{Introduction}, for information on reporting bugs.} to enable you -to write a single @file{Makefile.am} for a complex multi-directory -package. +Automake is intended to have sufficient cross-directory support to +enable you to write a single @file{Makefile.am} for a complex +multi-directory package. (If it seems to be lacking, please report +the issue as usual.) By default an installable file specified in a subdirectory will have its directory name stripped before installation. For instance, in this @@ -6293,14 +6298,14 @@ variable. Automake has somewhat idiosyncratic support for Yacc and Lex. Automake assumes that the @file{.c} file generated by @command{yacc} -(or @command{lex}) should be named using the basename of the input -file. That is, for a yacc source file @file{foo.y}, Automake will +or @command{lex} should be named using the basename of the input +file. That is, for a Yacc source file @file{foo.y}, Automake will cause the intermediate file to be named @file{foo.c} (as opposed to @file{y.tab.c}, which is more traditional). -The extension of a yacc source file is used to determine the extension -of the resulting C or C++ source and header files. Note that header -files are generated only when the @option{-d} Yacc option is used; see +The extension of a Yacc source file is used to determine the extension +of the resulting C or C++ source and header files. Be aware that header +files are generated only when the option @option{-d} is given to Yacc; see below for more information about this flag, and how to specify it. Files with the extension @file{.y} will thus be turned into @file{.c} sources and @file{.h} headers; likewise, @file{.yy} will become @@ -6308,7 +6313,7 @@ sources and @file{.h} headers; likewise, @file{.yy} will become @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx}, and @file{.ypp} will become @file{.cpp} and @file{.hpp}. -Similarly, lex source files can be used to generate C or C++; the +Similarly, Lex source files can be used to generate C or C++; the extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and @file{.lpp} are recognized. @@ -6319,10 +6324,10 @@ The intermediate files generated by @command{yacc} (or @command{lex}) will be included in any distribution that is made. That way the user doesn't need to have @command{yacc} or @command{lex}. -If a @command{yacc} source file is seen, then your @file{configure.ac} must +If a Yacc source file is seen, then your @file{configure.ac} must define the variable @code{YACC}. This is most easily done by invoking -the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular -Program Checks, autoconf, The Autoconf Manual}). +the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , +Particular Program Checks, autoconf, The Autoconf Manual}). @vindex YFLAGS @vindex AM_YFLAGS @@ -6333,17 +6338,18 @@ intended for the @file{Makefile.am} author. @code{AM_YFLAGS} is usually used to pass the @option{-d} option to @command{yacc}. Automake knows what this means and will automatically adjust its rules to update and distribute the header file built by -@samp{yacc -d}@footnote{Please note that @command{automake} recognizes -@option{-d} in @code{AM_YFLAGS} only if it is not clustered with other -options; for example, it won't be recognized if @code{AM_YFLAGS} is -@option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or -@option{-t -d}.}. -What Automake cannot guess, though, is where this -header will be used: it is up to you to ensure the header gets built -before it is first used. Typically this is necessary in order for -dependency tracking to work when the header is included by another -file. The common solution is listing the header file in -@code{BUILT_SOURCES} (@pxref{Sources}) as follows. +@samp{yacc -d}. Caveat: @command{automake} recognizes @option{-d} in +@code{AM_YFLAGS} only if it is not clustered with other options; for +example, it won't be recognized if @code{AM_YFLAGS} is @option{-dt}, +but it will be if @code{AM_YFLAGS} is @option{-d -t} or @option{-t +-d}. + +What Automake cannot guess, though, is where this header will be used: +it is up to you to ensure the header gets built before it is first +used. Typically this is necessary in order for dependency tracking to +work when the header is included by another file. The common solution +is listing the header file in @code{BUILT_SOURCES} (@pxref{Sources}) +as follows. @example BUILT_SOURCES = parser.h @@ -6352,11 +6358,11 @@ bin_PROGRAMS = foo foo_SOURCES = @dots{} parser.y @dots{} @end example -If a @command{lex} source file is seen, then your @file{configure.ac} -must define the variable @code{LEX}. You can use @code{AC_PROG_LEX} -to do this (@pxref{Particular Programs, , Particular Program Checks, -autoconf, The Autoconf Manual}), but using the @code{AM_PROG_LEX} macro -(@pxref{Macros}) is recommended. +If a Lex source file is seen, then your @file{configure.ac} must +define the variable @code{LEX}. You can use @code{AC_PROG_LEX} to do +this (@pxref{Particular Programs, , Particular Program Checks, +autoconf, The Autoconf Manual}), but using the @code{AM_PROG_LEX} +macro (@pxref{Macros}) is recommended. @vindex LFLAGS @vindex AM_LFLAGS @@ -6364,9 +6370,10 @@ When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and @code{LFLAGS}. The latter is a user variable and the former is intended for the @file{Makefile.am} author. -When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the -rebuild rule for distributed Yacc and Lex sources are only used when -@code{maintainer-mode} is enabled, or when the files have been erased. +When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is in effect, +the rebuild rules for distributed Yacc and Lex sources are only used +when @code{maintainer-mode} is enabled, or when the files have been +erased. @cindex @command{ylwrap} @cindex @command{yacc}, multiple parsers @@ -6374,19 +6381,28 @@ rebuild rule for distributed Yacc and Lex sources are only used when @cindex Multiple @command{lex} lexers @cindex @command{lex}, multiple lexers -When @command{lex} or @command{yacc} sources are used, @code{automake -a} -automatically installs an auxiliary program called @command{ylwrap} in -your package (@pxref{Auxiliary Programs}). -This program is used by the build rules to rename the output of these -tools, and makes it possible to include multiple @command{yacc} (or -@command{lex}) source files in a single directory. (This is necessary -because yacc's output file name is fixed, and a parallel make could -conceivably invoke more than one instance of @command{yacc} -simultaneously.) - -For @command{yacc}, simply managing locking is insufficient. The output of -@command{yacc} always uses the same symbol names internally, so it isn't -possible to link two @command{yacc} parsers into the same executable. +When Yacc or Lex sources are used, @code{automake -a} automatically +installs an auxiliary program called @command{ylwrap} in your package +(@pxref{Auxiliary Programs}). This program is used by the build rules +to rename the output of these tools, and makes it possible to include +multiple @command{yacc} (or @command{lex}) source files in a single +directory. This is necessary because Yacc's output file name is +fixed, and a parallel make could invoke more than one instance of +@command{yacc} simultaneously. + +@menu +* Linking Multiple Yacc Parsers:: +@end menu + +@subsection Linking Multiple Yacc Parsers +@node Linking Multiple Yacc Parsers + +@cindex Linking multiple @command{yacc} parsers + +For @command{yacc}, simply managing locking as with @code{ylwrap} is +insufficient. The output of @command{yacc} always uses the same +symbol names internally, so it isn't possible to link two +@command{yacc} parsers into the same executable. We recommend using the following renaming hack used in @command{gdb}: @example |