X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fautomake.texi;h=cd33ad7c305122e6728cd4566a021ac31cebed02;hb=e5eb95ce956adc428b65414ebf28bb5b96d74b9f;hp=c0b1abf7950a99a085cc9bdd22665689f4a34279;hpb=18143e7cfe66eaddffa481211ad4e340a11a22f4;p=platform%2Fupstream%2Fautomake.git diff --git a/doc/automake.texi b/doc/automake.texi index c0b1abf..cd33ad7 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -23,7 +23,7 @@ This manual is for GNU Automake (version @value{VERSION}, @value{UPDATED}), a program that creates GNU standards-compliant Makefiles from template files. -Copyright @copyright{} 1995-2012 Free Software Foundation, Inc. +Copyright @copyright{} 1995-2013 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -53,6 +53,8 @@ section entitled ``GNU Free Documentation License.'' @author David MacKenzie @author Tom Tromey @author Alexandre Duret-Lutz +@author Ralf Wildenhues +@author Stefano Lattarini @page @vskip 0pt plus 1filll @insertcopying @@ -319,7 +321,7 @@ Support for test suites Simple Tests * Scripts-based Testsuites:: Automake-specific concepts and terminology -* Serial Test Harness:: Older (and obsolescent) serial test harness +* Serial Test Harness:: Older (and discouraged) serial test harness * Parallel Test Harness:: Generic concurrent test harness Using the TAP test protocol @@ -1496,6 +1498,7 @@ command as follows: ~/amhello % @kbd{autoreconf --install} configure.ac: installing './install-sh' configure.ac: installing './missing' +configure.ac: installing './compile' src/Makefile.am: installing './depcomp' @end example @@ -3896,19 +3899,25 @@ Automake ships with several Autoconf macros that you can use from your Runs many macros required for proper operation of the generated Makefiles. @vindex AUTOMAKE_OPTIONS -@code{AM_INIT_AUTOMAKE} is called with a single argument: a space-separated -list of Automake options that 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}). - -@c FIXME: Remove this "modernization advice" in Automake 1.14 (and adjust -@c FIXME: the error message in m4/init.m4:AM_INIT_AUTOMAKE accordingly). +Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a +space-separated list of Automake options that 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 -This macro could once (before Automake 1.13) also be called in the -@emph{now obsolete and completely unsupported} form +This macro can also be called in another, @emph{deprecated} form: @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form, -there were two required arguments: the package and the version number. +there are two required arguments: the package and the version number. +This usage is mostly obsolete because the @var{package} and @var{version} +can be obtained from Autoconf's @code{AC_INIT} macro. However, +differently from what happens for @code{AC_INIT} invocations, this +@code{AM_INIT_AUTOMAKE} invocation supports shell variables' expansions +in the @code{PACKAGE} and @code{VERSION} arguments, and this can be +still be useful in some selected situations. Our hope is that future +Autoconf versions will improve their support for package versions +defined dynamically at configure runtime; when (and if) this happens, +support for the two-args @code{AM_INIT_AUTOMAKE} invocation will likely +be removed from Automake. @anchor{Modernize AM_INIT_AUTOMAKE invocation} If your @file{configure.ac} has: @@ -3919,8 +3928,7 @@ AM_INIT_AUTOMAKE([mumble], [1.5]) @end example @noindent -you must modernize it as follows in order to make it work with Automake -1.13 or later: +you should modernize it as follows: @example AC_INIT([mumble], [1.5]) @@ -3945,9 +3953,9 @@ explicitly). @opindex no-define By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and @code{VERSION}. This can be avoided by passing the @option{no-define} -option: +option (@pxref{List of Automake options}): @example -AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2]) +AM_INIT_AUTOMAKE([no-define ...]) @end example @item AM_PATH_LISPDIR @@ -3988,11 +3996,11 @@ choose the assembler for you (by default the C compiler) and set @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. +This is an obsolescent macro that checks that the C compiler supports +the @option{-c} and @option{-o} options together. Note that, since +Automake 1.14, the @code{AC_PROG_CC} is rewritten to implement such +checks itself, and thus the explicit use of @code{AM_PROG_CC_C_O} +should no longer be required. @item AM_PROG_LEX @acindex AM_PROG_LEX @@ -4080,8 +4088,8 @@ the output variable @code{MKDIR_P} instead. In case you are still using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac}, or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am}, you are advised to switch ASAP to the more modern Autoconf-provided -interface instead; both the macro and the variable @emph{will be -removed} in the next major Automake release. +interface instead; both the macro and the variable might be removed +in a future major Automake release. @end table @@ -5805,9 +5813,7 @@ different name for the intermediate object files. Ordinarily a file like @file{sample.c} will be compiled to produce @file{sample.o}. However, if the program's @code{_CFLAGS} variable is set, then the object file will be named, for instance, @file{maude-sample.o}. (See -also @ref{Renamed Objects}.) The use of per-target compilation flags -with C sources requires that the macro @code{AM_PROG_CC_C_O} be called -from @file{configure.ac}. +also @ref{Renamed Objects}). In compilations with per-target flags, the ordinary @samp{AM_} form of the flags variable is @emph{not} automatically included in the @@ -6128,9 +6134,9 @@ same functionality. This variable is deprecated; we suggest using @item AM_CFLAGS This is the variable the @file{Makefile.am} author can use to pass -in additional C compiler flags. It is more fully documented elsewhere. -In some situations, this is not used, in preference to the -per-executable (or per-library) @code{_CFLAGS}. +in additional C compiler flags. In some situations, this is +not used, in preference to the per-executable (or per-library) +@code{_CFLAGS}. @item COMPILE This is the command used to actually compile a C source file. The @@ -6238,10 +6244,10 @@ 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 --i} 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 +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 @@ -7591,11 +7597,11 @@ libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary. Automake provides some minimal support for Java bytecode compilation with the @code{JAVA} primary (in addition to the support for compiling Java to native machine code; @pxref{Java Support with gcj}). Note however that -@emph{the interface and most features described here are deprecated}; the -next automake release will strive to provide a better and cleaner +@emph{the interface and most features described here are deprecated}. +Future Automake releases will strive to provide a better and cleaner interface, which however @emph{won't be backward-compatible}; the present -interface will probably be removed altogether in future automake releases -(1.13 or later), so don't use it in new code. +interface will probably be removed altogether some time after the +introduction of the new interface (if that ever materializes). Any @file{.java} files listed in a @code{_JAVA} variable will be compiled with @code{JAVAC} at build time. By default, @file{.java} @@ -7818,9 +7824,9 @@ Currently Automake provides support for Texinfo and man pages. If the current directory contains Texinfo source, you must declare it with the @code{TEXINFOS} primary. Generally Texinfo files are converted into info, and thus the @code{info_TEXINFOS} variable is most commonly used -here. Any Texinfo source file must end in the @file{.texi}, -@file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi} -for new manuals. +here. Any Texinfo source file should have the @file{.texi} extension. +Automake also accepts @file{.txi} or @file{.texinfo} extensions, but their +use is discouraged now, and will elicit runtime warnings. Automake generates rules to build @file{.info}, @file{.dvi}, @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo @@ -7830,6 +7836,11 @@ install} (unless you use @option{no-installinfo}, see below). Furthermore, @file{.info} files are automatically distributed so that Texinfo is not a prerequisite for installing your package. +It is worth noting that, contrary to what happens with the other formats, +the generated @file{.info} files are by default placed in @code{srcdir} +rather than in the @code{builddir}. This can be changed with the +@option{info-in-builddir} option. + @trindex dvi @trindex html @trindex pdf @@ -7972,7 +7983,7 @@ passed to @code{makeinfo} when building @file{.info} files; and @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html} files. -@c Keep in sync with txinfo21.sh +@c Keep in sync with txinfo-many-output-formats.sh For instance, the following setting can be used to obtain one single @file{.html} file per manual, without node separators. @example @@ -8408,7 +8419,9 @@ You can also mention a directory in @code{EXTRA_DIST}; in this case the entire directory will be recursively copied into the distribution. Please note that this will also copy @emph{everything} in the directory, including, e.g., Subversion's @file{.svn} private directories or CVS/RCS -version control files. We recommend against using this feature. +version control files; thus we recommend against using this feature +as-is. However, you can use the @code{dist-hook} feature to +ameliorate the problem; @pxref{The dist Hook}. @vindex SUBDIRS @vindex DIST_SUBDIRS @@ -8543,11 +8556,18 @@ to supply additional flags to @command{configure}, define them in the @file{Makefile.am}. The user can still extend or override the flags provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable, on the command line when invoking @command{make}. - -Still, developers are encouraged to strive to make their code buildable -without requiring any special configure option; thus, in general, you -shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there -might be few scenarios in which the use of this variable is justified. +@c See automake bug#14991 for more details about how the following holds. +It's worth nothing that @command{make distcheck} needs complete control +over the @command{configure} options @option{--srcdir} and +@option{--prefix}, so those options cannot be overridden by +@code{AM_DISTCHECK_CONFIGURE_FLAGS} nor by +@code{DISTCHECK_CONFIGURE_FLAGS}. + +Also note that developers are encouraged to strive to make their code +buildable without requiring any special configure option; thus, in +general, you shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. +However, there might be few scenarios in which the use of this variable +is justified. GNU @command{m4} offers an example. GNU @command{m4} configures by default with its experimental and seldom used "changeword" feature disabled; so in its case it is useful to have @command{make distcheck} @@ -8651,28 +8671,25 @@ Automake generates rules to provide archives of the project for distributions in various formats. Their targets are: @table @asis +@item @code{dist-gzip} +Generate a @samp{gzip} tar archive of the distribution. This is the +only format enabled by default. +@trindex dist-gzip + @vindex BZIP2 @item @code{dist-bzip2} -Generate a bzip2 tar archive of the distribution. bzip2 archives are -frequently smaller than gzipped archives. +Generate a @samp{bzip2} tar archive of the distribution. bzip2 archives +are frequently smaller than gzipped archives. By default, this rule makes @samp{bzip2} use a compression option of @option{-9}. To make it use a different one, set the @env{BZIP2} environment variable. For example, @samp{make dist-bzip2 BZIP2=-7}. @trindex dist-bzip2 -@item @code{dist-gzip} -Generate a gzip tar archive of the distribution. -@trindex dist-gzip - @item @code{dist-lzip} Generate an @samp{lzip} tar archive of the distribution. @command{lzip} archives are frequently smaller than @command{bzip2}-compressed archives. @trindex dist-lzip -@item @code{dist-shar} -Generate a shar archive of the distribution. -@trindex dist-shar - @vindex XZ_OPT @item @code{dist-xz} Generate an @samp{xz} tar archive of the distribution. @command{xz} @@ -8681,22 +8698,33 @@ By default, this rule makes @samp{xz} use a compression option of @option{-e}. To make it use a different one, set the @env{XZ_OPT} environment variable. For example, run this command to use the default compression ratio, but with a progress indicator: -@samp{make dist-xz XZ_OPT=-7e}. +@samp{make dist-xz XZ_OPT=-ve}. @trindex dist-xz @item @code{dist-zip} -Generate a zip archive of the distribution. +Generate a @samp{zip} archive of the distribution. @trindex dist-zip @item @code{dist-tarZ} -Generate a compressed tar archive of -the distribution. +Generate a tar archive of the distribution, compressed with the +historical (and obsolescent) program @command{compress}. This +option is deprecated, and it and the corresponding functionality +will be removed altogether in Automake 2.0. @trindex dist-tarZ + +@item @code{dist-shar} +Generate a @samp{shar} archive of the distribution. This format +archive is obsolescent, and use of this option is deprecated. +It and the corresponding functionality will be removed altogether +in Automake 2.0. +@trindex dist-shar + @end table -The rule @code{dist} (and its historical synonym @code{dist-all}) will -create archives in all the enabled formats, @ref{Options}. By -default, only the @code{dist-gzip} target is hooked to @code{dist}. +The rule @code{dist} (and its historical synonym @code{dist-all}) +will create archives in all the enabled formats (@pxref{List of +Automake options} for how to change this list). By default, only +the @code{dist-gzip} target is hooked to @code{dist}. @node Tests @@ -8801,7 +8829,7 @@ terminology)? @menu * Scripts-based Testsuites:: Automake-specific concepts and terminology -* Serial Test Harness:: Older (and obsolescent) serial test harness +* Serial Test Harness:: Older (and discouraged) serial test harness * Parallel Test Harness:: Generic concurrent test harness @end menu @@ -8891,7 +8919,7 @@ If the standard output is connected to a capable terminal, then the test results and the summary are colored appropriately. The developer and the user can disable colored output by setting the @command{make} variable @samp{AM_COLOR_TESTS=no}; the user can in addition force colored output -even without a connecting terminal with @samp{AM_COLOR_TESTS=always}. +even without a connecting terminal with @samp{AM_COLOR_TESTS=always}. It's also worth noting that some @command{make} implementations, when used in parallel mode, have slightly different semantics (@pxref{Parallel make,,, autoconf, The Autoconf Manual}), which can @@ -8974,12 +9002,16 @@ by the tests, not the tests themselves. Of course you can set @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases. @node Serial Test Harness -@subsection Older (and obsolescent) serial test harness +@subsection Older (and discouraged) serial test harness @cindex @option{serial-tests}, Using -@emph{This harness is obsolescent}, and kept for backward-compatibility -reasons only. The user is strongly advised to just use the parallel test -harness instead (@pxref{Parallel Test Harness}). +First, note that today the use of this harness is strongly discouraged in +favour of the parallel test harness (@pxref{Parallel Test Harness}). +Still, there are @emph{few} situations when the advantages offered by +the parallel harness are irrelevant, and when test concurrency can +even cause tricky problems. In those cases, it might make sense to +still use the serial harness, for simplicity and reliability (we still +suggest trying to give the parallel harness a shot though). The serial test harness is enabled by the Automake option @option{serial-tests}. It operates by simply running the tests serially, @@ -9021,9 +9053,6 @@ files, concurrent execution of tests with @code{make -j}, specification of inter-test dependencies, lazy reruns of tests that have not completed in a prior run, and hard errors for exceptional failures. -This harness is still somewhat experimental and may undergo changes in -order to satisfy additional portability requirements. - @anchor{Basics of test metadata} @vindex TEST_SUITE_LOG @vindex TESTS @@ -9076,6 +9105,12 @@ followed by any number of alphabetic characters. For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions, while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not. +@cindex Configure substitutions in @code{TESTS} +It is important to note that, due to current limitations (unlikely to be +lifted), configure substitutions in the definition of @code{TESTS} can +only work if they will expand to a list of tests that have a suffix listed +in @code{TEST_EXTENSIONS}. + @vindex _LOG_COMPILE @vindex _LOG_COMPILER @vindex _LOG_FLAGS @@ -9892,6 +9927,7 @@ from @file{configure.ac}. For instance, the following statement will cause @file{configure} to be rerun each time @file{version.sh} is changed. +@c Keep in sync with remake-config-status-dependencies.sh @example AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh']) @end example @@ -9904,12 +9940,17 @@ any level in the build hierarchy. Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for @code{CONFIG_STATUS_DEPENDENCIES}. +@c Keep in sync with remake-configure-dependencies.sh @code{CONFIGURE_DEPENDENCIES} adds dependencies to the @file{configure} rule, whose effect is to run @command{autoconf}. This variable should be seldom used, because @command{automake} already tracks @code{m4_include}d files. However it can be useful when playing tricky games with @code{m4_esyscmd} or similar non-recommendable -macros with side effects. +macros with side effects. Be also aware that interactions of this +variable with the @ref{Autom4te Cache, , autom4te cache, autoconf, +The Autoconf Manual} are quite problematic and can cause subtle +breakage, so you might want to disable the cache if you want to use +@code{CONFIGURE_DEPENDENCIES}. @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the @file{config.status} rule, whose effect is to run @file{configure}. @@ -9918,8 +9959,27 @@ be read as a side effect of running @command{configure}, like @file{version.sh} in the example above. Speaking of @file{version.sh} scripts, we recommend against them -today. We recommend that @file{version.sh} be replaced by an M4 file -that is included by @file{configure.ac}: +today. They are mainly used when the version of a package is updated +automatically by a script (e.g., in daily builds). Here is what some +old-style @file{configure.ac}s may look like: + +@example +AC_INIT +. $srcdir/version.sh +AM_INIT_AUTOMAKE([name], $VERSION_NUMBER) +@dots{} +@end example + +@noindent +Here, @file{version.sh} is a shell fragment that sets +@code{VERSION_NUMBER}. The problem with this example is that +@command{automake} cannot track dependencies (listing @file{version.sh} +in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up +to the user), and that it uses the obsolete form of @code{AC_INIT} and +@code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not +straightforward, because shell variables are not allowed in +@code{AC_INIT}'s arguments. We recommend that @file{version.sh} be +replaced by an M4 file that is included by @file{configure.ac}: @example m4_include([version.m4]) @@ -9933,7 +9993,9 @@ Here @file{version.m4} could contain something like @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this second form is that @command{automake} will take care of the dependencies when defining the rebuild rule, and will also distribute -the file automatically. +the file automatically. An inconvenience is that @command{autoconf} +will now be rerun each time the version number is bumped, when only +@file{configure} had to be rerun in the previous setup. @node Options @@ -10034,11 +10096,11 @@ Hook @code{dist-bzip2} to @code{dist}. Hook @code{dist-lzip} to @code{dist}. @trindex dist-lzip -@item @option{dist-shar} -@cindex Option, @option{dist-shar} -@opindex dist-shar -Hook @code{dist-shar} to @code{dist}. -@trindex dist-shar +@item @option{dist-xz} +@cindex Option, @option{dist-xz} +@opindex dist-xz +Hook @code{dist-xz} to @code{dist}. +@trindex dist-xz @item @option{dist-zip} @cindex Option, @option{dist-zip} @@ -10046,10 +10108,21 @@ Hook @code{dist-shar} to @code{dist}. Hook @code{dist-zip} to @code{dist}. @trindex dist-zip +@item @option{dist-shar} +@cindex Option, @option{dist-shar} +@opindex dist-shar +Hook @code{dist-shar} to @code{dist}. Use of this option +is deprecated, as the @samp{shar} format is obsolescent and +problematic. Support for it will be removed altogether in +Automake 2.0. +@trindex dist-shar + @item @option{dist-tarZ} @cindex Option, @option{dist-tarZ} @opindex dist-tarZ -Hook @code{dist-tarZ} to @code{dist}. +Hook @code{dist-tarZ} to @code{dist}. Use of this option +is deprecated, as the @samp{compress} program is obsolete. +Support for it will be removed altogether in Automake 2.0. @trindex dist-tarZ @item @option{filename-length-max=99} @@ -10063,6 +10136,14 @@ options below. This option should be used in the top-level @file{configure.ac}, it will be ignored otherwise. It will also be ignored in sub-packages of nested packages (@pxref{Subpackages}). +@item @option{info-in-builddir} +@cindex Option, @option{info-in-builddir} +@opindex info-in-builddir +Instruct Automake to place the generated @file{.info} files in the +@code{builddir} rather than in the @code{srcdir}. Note that this +might make VPATH builds with some non-GNU make implementations more +brittle. + @item @option{no-define} @cindex Option, @option{no-define} @opindex no-define @@ -10198,9 +10279,6 @@ the source file. For instance, if the source file is @file{subdir/file.cxx}, then the output file would be @file{subdir/file.o}. -In order to use this option with C sources, you should add -@code{AM_PROG_CC_C_O} to @file{configure.ac}. - @anchor{tar-formats} @item @option{tar-v7} @itemx @option{tar-ustar} @@ -10455,6 +10533,26 @@ condition applies to the entire contents of that fragment. Makefile fragments included this way are always distributed because they are needed to rebuild @file{Makefile.in}. +Inside a fragment, the construct @code{%reldir%} is replaced with the +directory of the fragment relative to the base @file{Makefile.am}. +Similarly, @code{%canon_reldir%} is replaced with the canonicalized +(@pxref{Canonicalization}) form of @code{%reldir%}. As a convenience, +@code{%D%} is a synonym for @code{%reldir%}, and @code{%C%} +is a synonym for @code{%canon_reldir%}. + +A special feature is that if the fragment is in the same directory as +the base @file{Makefile.am} (i.e., @code{%reldir%} is @code{.}), then +@code{%reldir%} and @code{%canon_reldir%} will expand to the empty +string as well as eat, if present, a following slash or underscore +respectively. + +Thus, a makefile fragment might look like this: + +@example +bin_PROGRAMS += %reldir%/mumble +%canon_reldir%_mumble_SOURCES = %reldir%/one.c +@end example + @node Conditionals @chapter Conditionals @@ -11637,9 +11735,9 @@ touch aclocal.m4 sleep 1 # autoconf-generated configure depends on aclocal.m4 and on # configure.ac -configure config.h.in +touch configure # so does autoheader-generated config.h.in -configure config.h.in +touch config.h.in # and all the automake-generated Makefile.in files touch `find . -name Makefile.in -print` # finally, the makeinfo-generated '.info' files depend on the