From f88c295196984ff049090b3953516ef6bf1296fd Mon Sep 17 00:00:00 2001 From: Alexandre Duret-Lutz Date: Sun, 17 Feb 2002 22:12:37 +0000 Subject: [PATCH] * automake.in (handle_lib_objects_cond): Tell the user to put global linker flags in AM_LDFLAGS, not LDFLAGS. * automake.texi (General Operation): AC_SUBST'ed variables override Automake's variables. (Uniform): More words and @refs. (Auxiliary Programs) : Add URL. (etags): More explanations about the first example. (Invoking Automake): Mention autoreconf. More @refs. (Requirements): Mention AC_CONFIG_FILES. (Optional): AC_CHECK_TOOL will no longer install config.sub and config.guess. Mention AC_LIBOBJ, AC_LIBSOURCE, and AC_LIBSOURCES. (Invoking aclocal): aclocal no longer warn about duplicates. (Macros) : More explanations. (Extending aclocal): Suggest using the output of `aclocal --print-ac-dir` to install third-party macros. (Alternative): Specify ordering of dist_, nodist_, and nobase_ prefixes. (A Program): Mention scripts. The global LDADD variable is not meant to hold link flags, suggest using AM_LDFLAGS instead. (Program and Library Variables) : _LIBADD and _LDADD are subject to the same restriction wrt to link flags. (Program and Library Variables) : Is also derived from maude_LIBADD. (Program variables): Define AM_LDFLAGS. (Dependencies): Passing the no-dependencies option to AM_INIT_AUTOMAKE is prefered. (Scripts): Explain why automake is magically cleaned. Mention noinst_SCRIPTS and check_SCRIPTS. (Data): Use dist_ in Automake's example. (Dist): Reference AM_INIT_AUTOMAKE for PACKAGE and VERSION. Mention AC_CONFIG_FILES instead of AC_OUTPUT. --- ChangeLog | 36 ++++++ NEWS | 5 +- automake.in | 4 +- automake.texi | 305 ++++++++++++++++++++++++++++++++------------------ stamp-vti | 4 +- version.texi | 4 +- 6 files changed, 244 insertions(+), 114 deletions(-) diff --git a/ChangeLog b/ChangeLog index 866aa638..e9cc696d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,39 @@ +2002-02-17 Alexandre Duret-Lutz + + * automake.in (handle_lib_objects_cond): Tell the user to put + global linker flags in AM_LDFLAGS, not LDFLAGS. + + * automake.texi (General Operation): AC_SUBST'ed variables + override Automake's variables. + (Uniform): More words and @refs. + (Auxiliary Programs) : Add URL. + (etags): More explanations about the first example. + (Invoking Automake): Mention autoreconf. More @refs. + (Requirements): Mention AC_CONFIG_FILES. + (Optional): AC_CHECK_TOOL will no longer install config.sub and + config.guess. Mention AC_LIBOBJ, AC_LIBSOURCE, and AC_LIBSOURCES. + (Invoking aclocal): aclocal no longer warn about duplicates. + (Macros) : More explanations. + (Extending aclocal): Suggest using the output of + `aclocal --print-ac-dir` to install third-party macros. + (Alternative): Specify ordering of dist_, nodist_, and nobase_ + prefixes. + (A Program): Mention scripts. The global LDADD variable is not + meant to hold link flags, suggest using AM_LDFLAGS instead. + (Program and Library Variables) : + _LIBADD and _LDADD are subject to the same restriction wrt to + link flags. + (Program and Library Variables) : Is also + derived from maude_LIBADD. + (Program variables): Define AM_LDFLAGS. + (Dependencies): Passing the no-dependencies option to + AM_INIT_AUTOMAKE is prefered. + (Scripts): Explain why automake is magically cleaned. + Mention noinst_SCRIPTS and check_SCRIPTS. + (Data): Use dist_ in Automake's example. + (Dist): Reference AM_INIT_AUTOMAKE for PACKAGE and VERSION. + Mention AC_CONFIG_FILES instead of AC_OUTPUT. + 2002-02-14 Alexandre Duret-Lutz * Makefile.am (FETCHFILES): Add Automake/XFile.pm. diff --git a/NEWS b/NEWS index 33d052c3..bb29e0c2 100644 --- a/NEWS +++ b/NEWS @@ -20,8 +20,9 @@ New in 1.5d: * Fixed support of implicit rules leading to .lo objects. * Fixed late inclusion of --add-missing files (e.g. depcomp) in DIST_COMMON * Added uninstall-hook target -* `AC_INIT AM_INIT_AUTOMAKE(package,version)' is an obsolete construct. - You can now use `AC_INIT(package,version) AM_INIT_AUTOMAKE' instead. +* `AC_INIT AM_INIT_AUTOMAKE(tarname,version)' is an obsolete construct. + You can now use `AC_INIT(pkgname,version) AM_INIT_AUTOMAKE' instead. + (Note that "pkgname" is not "tarname", see the manual for details.) It is also possible to pass a list of global Automake options as first argument to this new form of AM_INIT_AUTOMAKE. * Compiler-based assembler is now called `CCAS'; people expected `AS' diff --git a/automake.in b/automake.in index 4cfc1f8b..5bb3d929 100755 --- a/automake.in +++ b/automake.in @@ -2394,11 +2394,13 @@ sub handle_lib_objects_cond { # Skip -dlopen and -dlpreopen; these are explicitly allowed. next if $lsearch =~ /^-dl(pre)?open$/; + my $prefix = $1 || 'AM_'; macro_error ($var, - "linker flags such as `$lsearch' belong in `${1}LDFLAGS"); + "linker flags such as `$lsearch' belong in `${prefix}LDFLAGS"); } else { + $var =~ /^(.*)LIBADD$/; # Only get this error once. $flagvar = 1; macro_error ($var, diff --git a/automake.texi b/automake.texi index f082333b..1bcb825e 100644 --- a/automake.texi +++ b/automake.texi @@ -234,6 +234,7 @@ behavior. Automake tries to group comments with adjoining targets and macro definitions in an intelligent way. +@c FIXME: What does this imply practically? @cindex Make targets, overriding @cindex Overriding make targets @@ -247,12 +248,12 @@ very particular. @cindex Macros, overriding @cindex Overriding make macros -Similarly, a macro defined in @file{Makefile.am} will override any -definition of the macro that @code{automake} would ordinarily create. -This feature is more often useful than the ability to override a target -definition. Be warned that many of the macros generated by -@code{automake} are considered to be for internal use only, and their -names might change in future releases. +Similarly, a macro defined in @file{Makefile.am} or @code{AC_SUBST}'ed +from @file{configure.in} will override any definition of the macro that +@code{automake} would ordinarily create. This feature is more often +useful than the ability to override a target definition. Be warned that +many of the macros generated by @code{automake} are considered to be for +internal use only, and their names might change in future releases. @cindex Recursive operation of Automake @cindex Automake, recursive operation @@ -306,7 +307,7 @@ not want to use all the GNU conventions. @cindex Strictness, foreign @cindex foreign strictness @cindex Strictness, gnu -@cindex gnits strictness +@cindex gnu strictness @cindex Strictness, gnits @cindex gnits strictness @@ -360,7 +361,6 @@ determination of what should be built. @cindex _PROGRAMS primary variable @cindex PROGRAMS primary variable @cindex Primary variable, PROGRAMS - @cindex Primary variable, defined At @code{make} time, certain variables are used to determine which @@ -389,7 +389,7 @@ Automake extends this list with @code{pkglibdir}, @code{pkgincludedir}, and @code{pkgdatadir}; these are the same as the non-@samp{pkg} versions, but with @samp{@@PACKAGE@@} appended. For instance, @code{pkglibdir} is defined as @code{$(libdir)/@@PACKAGE@@}. -@cvindex PACKAGE +@cvindex PACKAGE, directory @cindex EXTRA_, prepending @@ -422,8 +422,13 @@ variable names; thus one writes @samp{bin_PROGRAMS} and not @samp{bindir_PROGRAMS}. Not every sort of object can be installed in every directory. Automake -will flag those attempts it finds in error. Automake will also diagnose -obvious misspellings in directory names. +will flag those attempts it finds in error. +@c FIXME: This is broken today: &am_primary_prefix will allow data_PROGRAMS +@c because $datadir is defined before Makefile.am is parsed. This +@c means that passing the list of allowed directory suffix to +@c &am_install_var or &am_primary_prefix is absolutely useless (except +@c for 'noinst', 'check' and friends). +Automake will also diagnose obvious misspellings in directory names. @cindex Extending list of installation directories @cindex Installation directories, extending list @@ -448,12 +453,15 @@ html_DATA = automake.html @cindex noinst primary prefix, definition The special prefix @samp{noinst} indicates that the objects in question -should not be installed at all. +should be built but not installed at all. This is usually used for +objects required to build the rest of your package, for instance static +libraries (@pxref{A Library}), or helper scripts. @cindex check primary prefix, definition The special prefix @samp{check} indicates that the objects in question -should not be built until the @code{make check} command is run. +should not be built until the @code{make check} command is run. Those +objects are not installed either. The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA}, @@ -472,7 +480,7 @@ The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES}, Some primaries also allow additional prefixes which control other aspects of @code{automake}'s behavior. The currently defined prefixes are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes -are explained later. +are explained later (@pxref{Program and Library Variables}). @node Canonicalization, User Variables, Uniform, Generalities @@ -516,6 +524,8 @@ particularly not to include switches which are required for proper compilation of the package. Since these variables are documented as being for the package builder, that person rightfully expects to be able to override any of these variables at build time. +@c FIXME: maybe Automake could bark if a developer forces a user variable +@c from Makefile.am. To get around this problem, automake introduces an automake-specific shadow variable for each user flag variable. (Shadow variables are not @@ -549,7 +559,10 @@ Such compilers are rare. @item config.guess @itemx config.sub These programs compute the canonical triplets for the given build, host, -or target architecture. +or target architecture. These programs are updated regulary to support +new architectures and fix probes broken by changes in new kernel +versions. You are encouraged to fetch the latest versions of these +files from @url{ftp://ftp.gnu.org/gnu/config/} before making a release. @item depcomp This program understands how to run a compiler so that it will generate @@ -634,7 +647,7 @@ you're done with this part. That was easy! Now you must regenerate @file{configure}. But to do that, you'll need to tell @code{autoconf} how to find the new macro you've used. The easiest way to do this is to use the @code{aclocal} program to generate -your @file{aclocal.m4} for you. But wait... you already have an +your @file{aclocal.m4} for you. But wait... maybe you already have an @file{aclocal.m4}, because you had to write some hairy macros for your program. The @code{aclocal} program lets you put your own macros into @file{acinclude.m4}, so simply rename and then run: @@ -649,10 +662,10 @@ autoconf Now it is time to write your @file{Makefile.am} for @code{zardoz}. Since @code{zardoz} is a user program, you want to install it where the -rest of the user programs go. Additionally, @code{zardoz} has some -Texinfo documentation. Your @file{configure.in} script uses -@code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}. -So here's what you'd write: +rest of the user programs go: @code{bindir}. Additionally, +@code{zardoz} has some Texinfo documentation. Your @file{configure.in} +script uses @code{AC_REPLACE_FUNCS}, so you need to link against +@samp{@@LIBOBJS@@}. So here's what you'd write: @example bin_PROGRAMS = zardoz @@ -768,6 +781,8 @@ only test case. @code{make check} will run this test. @cindex INCLUDES, example usage Last we have @file{src/Makefile.am}, where all the real work is done: +@c FIXME: As all the Hello World excerpts in this manual, this +@c shows deprecated features (here: $(INCLUDES)). @example bin_PROGRAMS = hello @@ -802,12 +817,19 @@ ctags.o: etags.c $(COMPILE) -DCTAGS -o ctags.o -c etags.c @end example -Note that @code{ctags_SOURCES} is defined to be empty---that way no -implicit value is substituted. The implicit value, however, is used to -generate @code{etags} from @file{etags.o}. +Note that there is no @code{etags_SOURCES} definition. Automake will +implicitly assume that there is a source file named @file{etags.c}, and +define rules to compile @file{etags.o} and link @file{etags}. The +@code{etags.o: etags.c} rule supplied by the above @file{Makefile.am}, +will override the Automake generated rule to build @file{etags.o}. -@code{ctags_LDADD} is used to get @file{ctags.o} into the link line. -@code{ctags_DEPENDENCIES} is generated by Automake. +@code{ctags_SOURCES} is defined to be empty---that way no implicit value +is substituted. Because we have not listed the source of +@file{ctags}, we have to tell Automake how to link the program. This is +the purpose of the @code{ctags_LDADD} line. A @code{ctags_DEPENDENCIES} +variable, holding the dependencies of the @file{ctags} target will be +automatically generated by Automake from the contant of +@code{ctags_LDADD}. The above rules won't work if your compiler doesn't accept both @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a @@ -872,7 +894,9 @@ and generate the corresponding @file{Makefile.in}. Note that package; it assumes that a package has only one @file{configure.in}, at the top. If your package has multiple @file{configure.in}s, then you must run @code{automake} in each directory holding a -@file{configure.in}. +@file{configure.in}. (Alteratively, you may rely on Autoconf's +@code{autoreconf}, which is able to recurse your package tree and run +@code{automake} where appropriate.) You can optionally give @code{automake} an argument; @file{.am} is appended to the argument and the result is used as the name of the input @@ -886,6 +910,7 @@ in a subdirectory to change its behavior in some cases. @cindex Automake options @cindex Options, Automake +@cindex Strictness, command line @code{automake} accepts the following options: @@ -901,11 +926,11 @@ in a subdirectory to change its behavior in some cases. Automake requires certain common files to exist in certain situations; for instance @file{config.guess} is required if @file{configure.in} runs @code{AC_CANONICAL_HOST}. Automake is distributed with several of these -files; this option will cause the missing ones to be automatically added -to the package, whenever possible. In general if Automake tells you a -file is missing, try using this option. By default Automake tries to -make a symbolic link pointing to its own copy of the missing file; this -can be changed with @code{--copy}. +files (@pxref{Auxiliary Programs}); this option will cause the missing +ones to be automatically added to the package, whenever possible. In +general if Automake tells you a file is missing, try using this option. +By default Automake tries to make a symbolic link pointing to its own +copy of the missing file; this can be changed with @code{--copy}. @item --libdir=@var{dir} @opindex --libdir @@ -928,7 +953,7 @@ of GNU or Gnits rules. For more information, see @ref{Cygnus}. @opindex -f @itemx --force-missing @opindex --force-missing -When used with @code{--add-missing}, causes standard files to be rebuilt +When used with @code{--add-missing}, causes standard files to be reinstalled even if they already exist in the source tree. This involves removing the file from the source tree before creating the new symlink (or, with @code{--copy}, copying the new file). @@ -955,7 +980,8 @@ Print a summary of the command line options and exit. @item -i @itemx --ignore-deps @opindex -i -This disables the dependency tracking feature; see @ref{Dependencies}. +This disables the dependency tracking feature in generated +@file{Makefile}s; see @ref{Dependencies}. @item --include-deps @opindex --include-deps @@ -974,6 +1000,7 @@ dependents. @itemx --output-dir=@var{dir} @opindex -o @opindex --output-dir +@c FIXME: This seems to be a left-over from Automake 1.4, unused today. Put the generated @file{Makefile.in} in the directory @var{dir}. Ordinarily each @file{Makefile.in} is created in the directory of the corresponding @file{Makefile.am}. This option is used when making @@ -1034,7 +1061,7 @@ easier. These macros can automatically be put into your The one real requirement of Automake is that your @file{configure.in} call @code{AM_INIT_AUTOMAKE}. This macro does several things which are -required for proper Automake operation. +required for proper Automake operation (@pxref{Macros}). @cvindex AM_INIT_AUTOMAKE Here are the other macros which Automake requires but which are not run @@ -1043,13 +1070,18 @@ by @code{AM_INIT_AUTOMAKE}: @cindex AC_OUTPUT, scanning @table @code -@item AC_OUTPUT -Automake uses this to determine which files to create (@pxref{Output, , -Creating Output Files, autoconf, The Autoconf Manual}). Listed files -named @code{Makefile} are treated as @file{Makefile}s. Other listed -files are treated differently. Currently the only difference is that a -@file{Makefile} is removed by @code{make distclean}, while other files -are removed by @code{make clean}. +@item AC_CONFIG_FILES +@itemx AC_OUTPUT +Automake uses these to determine which files to create (@pxref{Output, , +Creating Output Files, autoconf, The Autoconf Manual}). A listed file +is considered to be an Automake generated @file{Makefile} if there +exists a file with the same name and the @file{.am} extension appended. +Typically, @code{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to +generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists. + +Other listed files are treated differently. Currently the only +difference is that an Automake @file{Makefile} is removed by @code{make +distclean}, while other files are removed by @code{make clean}. @c FIXME: this is in violation of standards! @cvindex AC_OUTPUT @end table @@ -1067,10 +1099,10 @@ and their effects are: @table @code @item AC_CONFIG_HEADER -Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar -to @code{AC_CONFIG_HEADER} (@pxref{Configuration Headers, , -Configuration Header Files, autoconf, The Autoconf Manual}), but does -some useful Automake-specific work. +Automake requires the use of @code{AM_CONFIG_HEADER} (@pxref{Macros}), +which is similar to @code{AC_CONFIG_HEADER} (@pxref{Configuration +Headers, , Configuration Header Files, autoconf, The Autoconf Manual}), +but does some useful Automake-specific work. @cvindex AC_CONFIG_HEADER @item AC_CONFIG_AUX_DIR @@ -1092,16 +1124,11 @@ Autoconf Manual}. @cvindex AC_PATH_XTRA @item AC_CANONICAL_HOST -@itemx AC_CHECK_TOOL Automake will ensure that @file{config.guess} and @file{config.sub} exist. Also, the @file{Makefile} variables @samp{host_alias} and -@samp{host_triplet} are introduced. See both @ref{Canonicalizing, , -Getting the Canonical System Type, autoconf, The Autoconf Manual}, and -@ref{Generic Programs, , Generic Program Checks, autoconf, The Autoconf -Manual}. -@c fixme xref autoconf docs. +@samp{host_triplet} are introduced. See @ref{Canonicalizing, , +Getting the Canonical System Type, autoconf, The Autoconf Manual}. @cvindex AC_CANONICAL_HOST -@cvindex AC_CHECK_TOOL @vindex host_alias @vindex host_triplet @@ -1146,11 +1173,24 @@ Functions, , Particular Function Checks, autoconf, The Autoconf Manual}. @cvindex AC_STRUCT_ST_BLOCKS @cvindex AM_WITH_REGEX -@item LIBOBJS +@item AC_LIBOBJ +@itemx LIBOBJS +@itemx AC_LIBSOURCE +@itemx AC_LIBSOURCES Automake will detect statements which put @file{.o} files into -@code{LIBOBJS}, and will treat these additional files as if they were -discovered via @code{AC_REPLACE_FUNCS}. @xref{Generic Functions, , -Generic Function Checks, autoconf, The Autoconf Manual}. +@code{LIBOBJS}, or pass @file{.o} files to @code{AC_LIBOBJ}, and will +treat these additional files as if they were discovered via +@code{AC_REPLACE_FUNCS}. Similarly, Automake will also distribute file +listed in @code{AC_LIBSOURCE} and @code{AC_LIBSOURCES}. + +Note that assignments to @code{LIBOBJS} is a construct which is being +phased out; they will be ignored in a future release of Automake. You +should call the @code{AC_LIBOBJ} macro instead. @xref{Generic +Functions, , Generic Function Checks, autoconf, The Autoconf Manual}. + +@cvindex AC_LIBOBJ +@cvindex AC_LIBSOURCE +@cvindex AC_LIBSOURCES @cvindex LIBOBJS @item AC_PROG_RANLIB @@ -1251,8 +1291,8 @@ otherwise they will not be seen by @code{autoconf}. The @code{aclocal} program will automatically generate @file{aclocal.m4} files based on the contents of @file{configure.in}. This provides a convenient way to get Automake-provided macros, without having to -search around. Also, the @code{aclocal} mechanism is extensible for use -by other packages. +search around. Also, the @code{aclocal} mechanism allows other packages +to supply their own macros. At startup, @code{aclocal} scans all the @file{.m4} files it can find, looking for macro definitions. Then it scans @file{configure.in}. Any @@ -1264,7 +1304,7 @@ automatically included in @file{aclocal.m4}. This is useful for incorporating local macros into @file{configure}. @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s -in the files it scans. It will warn if it finds duplicates. It also +in the files it scans. It also tries to copy the full text of the scanned file into @file{aclocal.m4}, including both @samp{#} and @samp{dnl} comments. If you want to make a comment which will be completely ignored by @code{aclocal}, use @@ -1294,9 +1334,9 @@ Cause the output to be put into @var{file} instead of @file{aclocal.m4}. @item --print-ac-dir @opindex --print-ac-dir Prints the name of the directory which @code{aclocal} will search to -find the @file{.m4} files. When this option is given, normal processing -is suppressed. This option can be used by a package to determine where -to install a macro file. +find third-party @file{.m4} files. When this option is given, normal +processing is suppressed. This option can be used by a package to +determine where to install a macro file. @item --verbose @opindex --verbose @@ -1331,6 +1371,7 @@ this should not be used unless you are familiar with the internals). @itemx AM_SET_DEPDIR @itemx AM_DEP_TRACK @itemx AM_OUTPUT_DEPENDENCY_COMMANDS +@c FIXME: Consider not documenting these internal macros. 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. @@ -1351,11 +1392,13 @@ found in @file{}. @item AM_INIT_AUTOMAKE([OPTIONS]) @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE]) -Runs many macros that most @file{configure.in}'s need. This macro has -two forms, the second of which has two required arguments: the package -and the version number. This latter form is obsolete because the -@var{package} and @var{version} are now arguments of the @samp{AC_INIT} -Autoconf macro, and Automake can get this information from there. +Runs many macros required for proper operation of the generated Makefiles. + +This macro has two forms, the second of which has two required +arguments: the package and the version number. This latter 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.in} has: @example @@ -1369,10 +1412,22 @@ AC_CONFIG_SRCDIR(src/foo.c) AM_INIT_AUTOMAKE @end example -If this macro is called with a single argument, it is interpreted as 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}. +Note that if you're upgrading your @file{configure.in} 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 of +@code{AC_INIT} is the name of your package (e.g. @samp{GNU Automake}), +not the tarball name (e.g. @samp{automake}) you used to pass to +@code{AM_INIT_AUTOMAKE}. Autoconf's rule to derive a tarball name from +the package name should work for most but not all packages. Especially, +if your tarball name is not all lower case, you will have to use the +four-argument form of @code{AC_INIT} (supported in Autoconf versions +greater than 2.52g). + +When @code{AM_INIT_AUTOMAKE} is called with a single argument, it is +interpreted as 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}. By default this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This can be avoided by passing the @samp{no-define} @@ -1385,14 +1440,9 @@ or by passing a third non-empty argument to the obsolete form. @cvindex PACKAGE, prevent definition @cvindex VERSION, prevent definition -Note that if you're upgrading your @file{configure.in} 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}. If your package name is not all lower case, you will -have to use the four-argument form of @code{AC_INIT}. - @item AM_MAKE_INCLUDE +@c FIXME: Consider not documenting this internal macro. 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. @@ -1444,6 +1494,7 @@ This is used to find a version of @code{install} which can be used to automatically included when required. @item AM_SANITY_CHECK +@c FIXME: Consider not documenting this internal macro. 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 @@ -1503,7 +1554,8 @@ safe to put each macro in a separate file. @xref{Prerequisite Macros, , autoconf, The Autoconf Manual}. A macro file's name should end in @file{.m4}. Such files should be -installed in @file{$(datadir)/aclocal}. +installed in @code{`aclocal --print-ac-dir`} (which usually happens to +be @file{$(datadir)/aclocal}). @node Top level, Alternative, configure, Top @@ -1633,6 +1685,16 @@ stripping. In this example, the header file will be installed as nobase_include_HEADERS = sys/types.h @end example +@cindex nobase_ and dist_ or nodist_ +@cindex dist_ and nobase_ +@cindex nodist_ and nobase_ + +@samp{nobase_} should be specified first when used in conjonction with +either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance: + +@example +nobase_dist_pkgdata_DATA = images/vortex.pgm +@end example @node Rebuilding, Programs, Alternative, Top @chapter Rebuilding Makefiles @@ -1689,12 +1751,14 @@ to build programs and libraries. @vindex libexec_PROGRAMS @vindex pkglib_PROGRAMS @vindex noinst_PROGRAMS +@vindex check_PROGRAMS In a directory containing source that gets built into a program (as -opposed to a library), the @samp{PROGRAMS} primary is used. Programs -can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir}, -@code{pkglibdir}, or not at all (@samp{noinst}). They can also be built -only for @code{make check}, in which case the prefix is @samp{check}. +opposed to a library or a script), the @samp{PROGRAMS} primary is used. +Programs can be installed in @code{bindir}, @code{sbindir}, +@code{libexecdir}, @code{pkglibdir}, or not at all (@samp{noinst}). +They can also be built only for @code{make check}, in which case the +prefix is @samp{check}. For instance: @@ -1806,9 +1870,12 @@ be built. @subsection Linking the program If you need to link against libraries that are not found by -@code{configure}, you can use @code{LDADD} to do so. This variable -actually can be used to add any options to the linker command line. +@code{configure}, you can use @code{LDADD} to do so. This variable is +used to specify additional objects or libraries to link with; it is +inappropriate for specifying specific linker flags, you should use +@code{AM_LDFLAGS} for this purpose. @vindex LDADD +@vindex AM_LDFLAGS @cindex prog_LDADD, defined @@ -2083,9 +2150,10 @@ Extra objects can be added to a shared library or a program by listing them in the @samp{_LDADD} variable. This should be used for objects determined by @code{configure}. -@samp{_LDADD} is inappropriate for passing program-specific linker flags -(except for @samp{-l}, @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen}). -Use the @samp{_LDFLAGS} variable for this purpose. +@samp{_LDADD} and @samp{_LIBADD} are inappropriate for passing +program-specific linker flags (except for @samp{-l}, @samp{-L}, +@samp{-dlopen} and @samp{-dlpreopen}). Use the @samp{_LDFLAGS} variable +for this purpose. For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you could link your program against the X libraries like so: @@ -2143,12 +2211,12 @@ using the @samp{_DEPENDENCIES} variable. Each program depends on the contents of such a variable, but no further interpretation is done. If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake. -The automatically-assigned value is the contents of @samp{_LDADD}, with -most configure substitutions, @samp{-l}, @samp{-L}, @samp{-dlopen} and -@samp{-dlpreopen} options removed. The configure substitutions that are -left in are only @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are -left because it is known that they will not cause an invalid value for -@samp{_DEPENDENCIES} to be generated. +The automatically-assigned value is the contents of @samp{_LDADD} or +@samp{_LIBADD}, with most configure substitutions, @samp{-l}, @samp{-L}, +@samp{-dlopen} and @samp{-dlpreopen} options removed. The configure +substitutions that are left in are only @samp{@@LIBOBJS@@} and +@samp{@@ALLOCA@@}; these are left because it is known that they will not +cause an invalid value for @samp{_DEPENDENCIES} to be generated. @item maude_SHORTNAME On some platforms the allowable file names are very short. In order to @@ -2190,7 +2258,12 @@ own compilation in some special cases. Some variables are inherited from Autoconf; these are @code{CC}, @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and @code{LIBS}. +@vindex CC +@vindex CFLAGS +@vindex CPPFLAGS +@vindex DEFS @vindex LDFLAGS +@vindex LIBS There are some additional variables which Automake itself defines: @@ -2215,12 +2288,17 @@ the same functionality. This macro is deprecated; we suggest using This is the variable which 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}. +per-executable (or per-library) @code{_CFLAGS}. @item COMPILE This is the command used to actually compile a C source file. The filename is appended to form the complete command line. +@item AM_LDFLAGS +This is the variable which the @file{Makefile.am} author can use to pass +in additional linker flags. In some situations, this is not used, in +preference to the per-executable (or per-library) @code{_LDFLAGS}. + @item LINK This is the command used to actually link a C program. It already includes @samp{-o $@@} and the usual variable references (for instance, @@ -2769,6 +2847,7 @@ into your @file{configure.in}, just before the @code{AC_OUTPUT} call: # the ANSI2KNR-filtering rules. LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'` @end example +@c FIXME: Ask Akim how this should be handled in the upcoming Autoconf. Note that automatic de-ANSI-fication will not work when the package is being built for a different host architecture. That is because automake @@ -2807,9 +2886,10 @@ dependencies only on the maintainer's system, as configurations vary too much. So instead Automake implements dependency tracking at build time. Automatic dependency tracking can be suppressed by putting -@code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}. Or, you -can invoke @code{automake} with the @code{-i} option. Dependency -tracking is enabled by default. +@code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or +passing @code{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE} +(this should be the prefered way). Or, you can invoke @code{automake} +with the @code{-i} option. Dependency tracking is enabled by default. @vindex AUTOMAKE_OPTIONS @opindex no-dependencies @@ -2834,8 +2914,9 @@ among them) will automatically generate @file{foo.exe} when asked to generate @file{foo}. Automake provides mostly-transparent support for this. Unfortunately -the support isn't completely transparent; if you want your package to -support these platforms then you must assist. +@emph{mostly} doesn't yet mean @emph{fully}. Until the English +dictionary is revised, you will have to assist Automake if your package +must support those platforms. One thing you must be aware of is that, internally, Automake rewrites something like this: @@ -2920,7 +3001,8 @@ bin_SCRIPTS = automake @end example Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target -for it is automatically generated. +for it is automatically generated, and it is also automatically cleaned +(despite the fact it's a script). @cindex SCRIPTS, installation directories @cindex Installing scripts @@ -2930,10 +3012,15 @@ for it is automatically generated. @vindex libexec_SCRIPTS @vindex pkgdata_SCRIPTS @vindex noinst_SCRIPTS +@vindex check_SCRIPTS Script objects can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir}, or @code{pkgdatadir}. +Scripts that need not being installed can be listed in +@code{noinst_SCRIPTS}, and among them, those which are needed only by +@code{make check} should go in @code{check_SCRIPTS}. + @node Headers, Data, Scripts, Other objects @section Header files @@ -2994,10 +3081,10 @@ By default, data files are @emph{not} included in a distribution. Of course, you can use the @samp{dist_} prefix to change this on a per-variable basis. -Here is how Automake installs its auxiliary data files: +Here is how Automake declares its auxiliary data files: @example -pkgdata_DATA = clean-kr.am clean.am @dots{} +dist_pkgdata_DATA = clean-kr.am clean.am @dots{} @end example @@ -3564,7 +3651,9 @@ packaging tool. @cindex make clean support The GNU Makefile Standards specify a number of different clean rules. -@c FIXME xref +See @xref{Standard Targets, , Standard Targets for Users, standards, +The GNU Coding Standards}. + Generally the files that can be cleaned are determined automatically by Automake. Of course, Automake also recognizes some variables that can be defined to specify additional files to clean. These variables are @@ -3610,8 +3699,9 @@ We recommend that you follow this same set of heuristics in your The @code{dist} target in the generated @file{Makefile.in} can be used to generate a gzip'd @code{tar} file and other flavors of archive for distribution. The files is named based on the @samp{PACKAGE} and -@samp{VERSION} variables; more precisely the gzip'd @code{tar} file is -named @samp{@var{package}-@var{version}.tar.gz}. +@samp{VERSION} variables defined by @code{AM_INIT_AUTOMAKE} +(@pxref{Macros}); more precisely the gzip'd @code{tar} file is named +@samp{@var{package}-@var{version}.tar.gz}. @cvindex PACKAGE @cvindex VERSION @trindex dist @@ -3625,8 +3715,9 @@ has a built-in list of commonly used files which are automatically included if they are found in the current directory (either physically, or as the target of a @file{Makefile.am} rule). This list is printed by @samp{automake --help}. Also, files which are read by @code{configure} -(i.e. the source files corresponding to the files specified in the -@code{AC_OUTPUT} invocation) are automatically distributed. +(i.e. the source files corresponding to the files specified in various +Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are +automatically distributed. Still, sometimes there are files which must be distributed, but which are not covered in the automatic rules. These files should be listed in diff --git a/stamp-vti b/stamp-vti index 78b25572..419d7c89 100644 --- a/stamp-vti +++ b/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 30 January 2002 -@set UPDATED-MONTH January 2002 +@set UPDATED 17 February 2002 +@set UPDATED-MONTH February 2002 @set EDITION 1.5e @set VERSION 1.5e diff --git a/version.texi b/version.texi index 78b25572..419d7c89 100644 --- a/version.texi +++ b/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 30 January 2002 -@set UPDATED-MONTH January 2002 +@set UPDATED 17 February 2002 +@set UPDATED-MONTH February 2002 @set EDITION 1.5e @set VERSION 1.5e -- 2.43.5