diff options
Diffstat (limited to 'doc/automake.texi')
| -rw-r--r-- | doc/automake.texi | 167 |
1 files changed, 134 insertions, 33 deletions
diff --git a/doc/automake.texi b/doc/automake.texi index 73c0e51b5..9f66a9d79 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -320,9 +320,14 @@ Support for test suites * DejaGnu Tests:: Interfacing with the external testing framework * Install Tests:: Running tests on installed packages +Changing Automake's Behavior + +* Options generalities:: Semantics of Automake option +* List of Automake options:: A comprehensive list of Automake options + Miscellaneous Rules -* Tags:: Interfacing to etags and mkid +* Tags:: Interfacing to cscope, etags and mkid * Suffixes:: Handling new file extensions * Multilibs:: Support for multilibs. @@ -1899,7 +1904,9 @@ The valid strictness levels are: Automake will check for only those things that are absolutely required for proper operations. For instance, whereas GNU standards dictate the existence of a @file{NEWS} file, it will not be required in -this mode. The name comes from the fact that Automake is intended to be +this mode. This strictness will also turn off some warnings by default +(among them, portability warnings). +The name comes from the fact that Automake is intended to be used for GNU programs; these relaxed rules are not the standard mode of operation. @@ -2217,6 +2224,10 @@ copies are updated before each release, but we mention the original source in case you need more recent versions. @table @code +@item ar-lib +This is a wrapper primarily for the Microsoft lib archiver, to make +it more POSIX-like. + @item ansi2knr.c @itemx ansi2knr.1 These two files are used for de-ANSI-fication support (obsolete @@ -2225,7 +2236,11 @@ These two files are used for de-ANSI-fication support (obsolete @item compile This is a wrapper for compilers that do not accept options @option{-c} and @option{-o} at the same time. It is only used when absolutely -required. Such compilers are rare. +required. Such compilers are rare, with the Microsoft C/C++ Compiler +as the most notable exception. This wrapper also makes the following +common options available for that compiler, while performing file name +translation where needed: @option{-I}, @option{-L}, @option{-l}, +@option{-Wl,} and @option{-Xlinker}. @item config.guess @itemx config.sub @@ -2890,12 +2905,12 @@ The Autoconf Manual}. Automake will look for various helper scripts, such as @file{install-sh}, in the directory named in this macro invocation. @c This list is accurate relative to version 1.8 -(The full list of scripts is: @file{config.guess}, @file{config.sub}, -@file{depcomp}, @file{elisp-comp}, @file{compile}, @file{install-sh}, -@file{ltmain.sh}, @file{mdate-sh}, @file{missing}, @file{mkinstalldirs}, -@file{py-compile}, @file{texinfo.tex}, and @file{ylwrap}.) Not all -scripts are always searched for; some scripts will only be sought if the -generated @file{Makefile.in} requires them. +(The full list of scripts is: @file{ar-lib}, @file{config.guess}, +@file{config.sub}, @file{depcomp}, @file{elisp-comp}, @file{compile}, +@file{install-sh}, @file{ltmain.sh}, @file{mdate-sh}, @file{missing}, +@file{mkinstalldirs}, @file{py-compile}, @file{texinfo.tex}, and +@file{ylwrap}.) Not all scripts are always searched for; some scripts +will only be sought if the generated @file{Makefile.in} requires them. If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in their standard locations. For @file{mdate-sh}, @@ -3965,19 +3980,6 @@ Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If the user runs @command{configure} with @option{--with-dmalloc}, then define @code{WITH_DMALLOC} and add @option{-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 @option{--with-regex} to the @command{configure} command line. If -specified (the default), then the @samp{regex} regular expression -library is used, @file{regex.o} is put into @code{LIBOBJS}, and -@code{WITH_REGEX} is defined. If @option{--without-regex} is given, then -the @code{rx} regular expression library is used, and @file{rx.o} is put -into @code{LIBOBJS}. - @end table @@ -4053,6 +4055,21 @@ 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_REGEX +@acindex AM_WITH_REGEX +@vindex WITH_REGEX +@opindex --with-regex +@cindex regex package +@cindex rx package +Adds @option{--with-regex} to the @command{configure} command line. If +specified (the default), then the @samp{regex} regular expression +library is used, @file{regex.o} is put into @code{LIBOBJS}, and +@code{WITH_REGEX} is defined. If @option{--without-regex} is given, then +the @samp{rx} regular expression library is used, and @file{rx.o} is put +into @code{LIBOBJS}. This macro is obsolete now (since @samp{rx} doesn't +seem to be maintained), and will be removed in a future version of +Automake. Consider using gnulib if you need regex functionality. + @end table @@ -4743,11 +4760,12 @@ this purpose. @cindex @code{_DEPENDENCIES}, defined @vindex maude_DEPENDENCIES +@vindex EXTRA_maude_DEPENDENCIES It is also occasionally useful to have a program depend on some other target that is not actually part of that program. This can be done -using the @code{@var{prog}_DEPENDENCIES} variable. Each program -depends on the contents of such a variable, but no further -interpretation is done. +using either the @code{@var{prog}_DEPENDENCIES} or the +@code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on +the contents both variables, but no further interpretation is done. Since these dependencies are associated to the link rule used to create the programs they should normally list files used by the link @@ -4770,6 +4788,10 @@ generated. @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES} may be used. +The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where +you merely want to augment the @command{automake}-generated +@code{@var{prog}_DEPENDENCIES} rather than replacing it. + @cindex @code{LDADD} and @option{-l} @cindex @option{-l} and @code{LDADD} We recommend that you avoid using @option{-l} options in @code{LDADD} @@ -5637,6 +5659,7 @@ option, so they should not be mode-specific options (those belong to the compiler or linker flags). @xref{Libtool Flags}. @item maude_DEPENDENCIES +@itemx EXTRA_maude_DEPENDENCIES It is also occasionally useful to have a target (program or library) depend on some other file that is not actually part of that target. This can be done using the @code{_DEPENDENCIES} variable. Each @@ -5667,6 +5690,10 @@ compilation using an @code{AC_SUBST} variable that contains a list of objects. @xref{Conditional Sources}, and @ref{Conditional Libtool Sources}. +The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where +you merely want to augment the @command{automake}-generated +@code{_DEPENDENCIES} variable rather than replacing it. + @item maude_LINK You can override the linker on a per-program basis. By default the linker is chosen according to the languages used by the program. For @@ -5877,9 +5904,10 @@ However there is no need to list the corresponding sources in automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the dependencies, and it will discover the list of corresponding source files automatically (by tracing the invocations of the -@code{AC_LIBSOURCE} Autoconf macros). However, if you have already -defined @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then -you have to add these variables manually. +@code{AC_LIBSOURCE} Autoconf macros). If you have already defined +@samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you +either need to add these variables manually, or use +@samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}. These variables are usually used to build a portability library that is linked with all the programs of the project. We now review a @@ -8498,15 +8526,24 @@ Automake generates rules to provide archives of the project for distributions in various formats. Their targets are: @table @asis +@vindex BZIP2 @item @code{dist-bzip2} Generate a 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-lzma} Generate an @samp{lzma} tar archive of the distribution. @command{lzma} archives are frequently smaller than @command{bzip2}-compressed archives. @@ -8518,10 +8555,15 @@ instead. 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} archives are frequently smaller than @command{bzip2}-compressed archives. The @samp{xz} format displaces the obsolete @samp{lzma} format. +By default, this rule makes @samp{xz} use a compression option of @option{-9}. +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}. @trindex dist-xz @item @code{dist-zip} @@ -8999,8 +9041,16 @@ will now be rerun each time the version number is bumped, when only @node Options @chapter Changing Automake's Behavior +@menu +* Options generalities:: Semantics of Automake option +* List of Automake options:: A comprehensive list of Automake options +@end menu + +@node Options generalities +@section Options generalities + Various features of Automake can be controlled by options. Except where -noted otherwise, options can be specified in one of several ways: Most +noted otherwise, options can be specified in one of several ways. Most options can be applied on a per-@file{Makefile} basis when listed in a special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some of these options only make sense when specified in the toplevel @@ -9010,7 +9060,43 @@ of these options only make sense when specified in the toplevel require changes to the @command{configure} script can only be specified there. These are annotated below. -Currently understood options are: +As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take +precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in +turn take precedence over those specified on the command line. + +Also, some care must be taken about the interactions among strictness +level and warning categories. As a general rule, strictness-implied +warnings are overridden by those specified by explicit options. For +example, even if @samp{portability} warnings are disabled by default +in @option{foreign} strictness, an usage like this will end up enabling +them: + +@example +AUTOMAKE_OPTIONS = -Wportability foreign +@end example + +However, a strictness level specified in a higher-priority context +will override all the explicit warnings specified in a lower-priority +context. For example, if @file{configure.ac} contains: + +@example +AM_INIT_AUTOMAKE([-Wportability]) +@end example + +@noindent +and @file{Makefile.am} contains: + +@example +AUTOMAKE_OPTIONS = foreign +@end example + +@noindent +then @samp{portability} warnings will be @emph{disabled} in +@file{Makefile.am}. + +@node List of Automake options +@section List of Automake options + @vindex AUTOMAKE_OPTIONS @table @asis @@ -9063,6 +9149,12 @@ Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}. Hook @code{dist-bzip2} to @code{dist}. @trindex dist-bzip2 +@item @option{dist-lzip} +@cindex Option, @option{dist-lzip} +@opindex dist-lzip +Hook @code{dist-lzip} to @code{dist}. +@trindex dist-lzip + @item @option{dist-lzma} @cindex Option, @option{dist-lzma} @opindex dist-lzma @@ -9335,7 +9427,8 @@ In order to use this option with C sources, you should add These three mutually exclusive options select the tar format to use when generating tarballs with @samp{make dist}. (The tar file created is then compressed according to the set of @option{no-dist-gzip}, -@option{dist-bzip2}, @option{dist-xz} and @option{dist-tarZ} options in use.) +@option{dist-bzip2}, @option{dist-lzip}, @option{dist-tarZ} and +@option{dist-xz} options in use.) These options must be passed as arguments to @code{AM_INIT_AUTOMAKE} (@pxref{Macros}) because they can require additional configure checks. @@ -9407,7 +9500,7 @@ the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}. There are a few rules and variables that didn't fit anywhere else. @menu -* Tags:: Interfacing to etags and mkid +* Tags:: Interfacing to cscope, etags and mkid * Suffixes:: Handling new file extensions * Multilibs:: Support for multilibs. @end menu @@ -9469,6 +9562,14 @@ Automake will also generate an @code{ID} rule that will run directory-by-directory basis. @trindex id +Similarly, the @code{cscope} rule will create a list of all the source +files in the tree and run @command{cscope} to build an inverted index +database. The variable @code{CSCOPE} is the name of the program to invoke +(by default @command{cscope}); @code{CSCOPEFLAGS} and +@code{CSCOPE_ARGS} can be used by the user to pass additional flags and +file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the +@file{Makefile.am}. + Finally, Automake also emits rules to support the @uref{http://www.gnu.org/software/global/, GNU Global Tags program}. The @code{GTAGS} rule runs Global Tags and puts the @@ -13103,4 +13204,4 @@ parentheses is the number of generated test cases. @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS -@c LocalWords: barexec Pinard's automatize initialize lzma xz +@c LocalWords: barexec Pinard's automatize initialize lzip lzma xz cscope |