X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fautomake.texi;h=b7ae709695968cf846a3b67c090498b1e1ed85e4;hb=780299d96327ac43de44e38173c0162ed2c10474;hp=76761a7d8b755a6caf464e897b0dea91d0efdd92;hpb=6b8f20088def2f54c8d62e8a0baaa249511ed0f2;p=platform%2Fupstream%2Fautomake.git diff --git a/doc/automake.texi b/doc/automake.texi index 76761a7..b7ae709 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -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 @@ -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 @@ -3994,10 +3997,9 @@ 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 @emph{obsolete wrapper} around @code{AC_PROG_CC_C_O}. +New code needs not use this macro. It might be deprecated and +@emph{retired in future Automake versions}. @item AM_PROG_LEX @acindex AM_PROG_LEX @@ -4068,6 +4070,13 @@ Invocation, , Using @command{autoupdate} to Modernize @table @code +@item AM_PROG_CC_C_O +@acindex AM_PROG_CC_C_O +@acindex AC_PROG_CC_C_O +This is an @emph{obsolete wrapper} around @code{AC_PROG_CC_C_O}. New +code needs not to use this macro. It will be deprecated, and then +removed, in future Automake versions. + @item AM_PROG_MKDIR_P @acindex AM_PROG_MKDIR_P @cindex @code{mkdir -p}, macro check @@ -5810,9 +5819,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 @@ -6243,10 +6250,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 @@ -7596,11 +7603,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} @@ -7823,9 +7830,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 @@ -7835,6 +7842,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 @@ -8413,7 +8425,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 @@ -8663,8 +8677,8 @@ only format enabled by default. @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}. @@ -8675,10 +8689,6 @@ 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} @@ -8691,18 +8701,29 @@ default compression ratio, but with a progress indicator: @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 @@ -9083,6 +9104,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 @@ -10074,22 +10101,27 @@ Hook @code{dist-lzip} to @code{dist}. Hook @code{dist-xz} to @code{dist}. @trindex dist-xz -@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-zip} @cindex Option, @option{dist-zip} @opindex dist-zip 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} @@ -10103,6 +10135,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 @@ -10238,9 +10278,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} @@ -10495,6 +10532,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