From: Karl Berry Date: Sun, 25 Jun 2023 01:31:29 +0000 (-0700) Subject: doc: bring a few examples up to date. X-Git-Tag: v1.16i~48 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7db4d7d1e419df773d8ad4406389d0d21ccd4be0;p=thirdparty%2Fautomake.git doc: bring a few examples up to date. * doc/automake.texi (Built Sources Example): use @kbd for typed commands; show current output. (Checking the Distribution): refer to Third-Party Makefiles for the do-nothing dvi target example. Other small wording tweaks throughout. * HACKING: consistently omit $ prompt. Say a bit more about versions of Autoconf. Describe actual current status of branches (only master in use). Give some topic examples. "rerun" not "re-run". Other small wording tweaks throughout. --- diff --git a/HACKING b/HACKING index e0ac01875..bb6b21c06 100644 --- a/HACKING +++ b/HACKING @@ -3,14 +3,14 @@ * This file attempts to describe the conventions to use when hacking automake. -* After git checkout from Savannah, can do initial build with, e.g.: - $ ./bootstrap && ./configure --prefix=/tmp/amdev && make +* After git checkout from Savannah, you can do an initial build with, e.g.: + ./bootstrap && ./configure --prefix=/tmp/amdev && make ============================================================================ = Administrivia * The correct response to most actual bugs is to write a new test case - which demonstrates the bug. Then fix the bug, re-run the test suite, + which demonstrates the bug. Then fix the bug, rerun the test suite, and check everything in. Run the test suite in parallel or it takes ages. * If you incorporate a change from somebody on the net: @@ -63,7 +63,7 @@ can be automatically fetched using the GNU Guix package manager with the following command: - $ guix environment automake --ad-hoc \ + guix environment automake --ad-hoc \ gettext help2man texinfo libtool flex bison dejagnu zip icedtea \ python gcc-toolchain gfortran pkg-config vala @@ -187,14 +187,23 @@ use the 'bootstrap' script. It uses the code from the source tree, so the resulting files (aclocal.m4 and Makefile.in) should be the same as you would get if you install this version of - automake and use it to generate those files. Be sure to have the - latest stable version of Autoconf installed and available early - in your PATH. To get a faithful and correct rebuild, run: + automake and use it to generate those files. + +* To get a faithful and correct rebuild, run: ./bootstrap && ./config.status --recheck && make clean all - (per https://bugs.gnu.org/11347) -* The Automake git tree currently carries three basic branches: 'master', - 'next' and 'maint'. +* Usually, it is best to run again latest stable versions of Autoconf, + Libtool, etc., since that is what most users will do. Sometimes it may + be necessary to use the development versions due to bugs fixed, + etc. Whatever is first in PATH wins. + (Some background: https://bugs.gnu.org/11347) + +* The Automake git tree currently carries three basic branches: + 'master', 'next' and 'maint'. In practice, for quite a few years now, + as of this writing in 2023, we have been using only the master branch, + due to lack of time and desire to deal with anything but fixing bugs. + The branch information in the items below should thus be taken with a + large dose of salt. * The 'master' branch is where the development of the next release takes place. It should be kept in a stable, almost-releasable state, @@ -284,6 +293,12 @@ +* To choose the topic label, please review the previous commits in the + git log or the ChangeLog file from a release tarball. There are no + hard-and-fast rules; the aim is a usable description. So script + names, Makefile targets, and more are all viable. Some examples: + aclocal automake build cosmetics doc maint python release tests ylwrap + * The should usually be provided (but for short or trivial changes), and should follow the GNU guidelines for ChangeLog entries (described explicitly in the GNU Coding @@ -448,7 +463,7 @@ * Fetch new versions of the files that are maintained by the FSF by running "make fetch". help2man has to be updated separately. In case any file in the automake repository has been updated, commit and - re-run the testsuite. + rerun the testsuite. * Ensure that the copyright notices of the distributed files are up to date. The maintainer-only target "update-copyright" can help with this. @@ -513,7 +528,7 @@ in by hand any "TODO" left in there. * Update version number in configure.ac to next alpha number. - Re-run ./bootstrap and commit. + Rerun ./bootstrap and commit. * Don't forget to "git push" your changes so they appear in the public git tree. diff --git a/doc/automake.texi b/doc/automake.texi index ec14c5c4c..72398adf9 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -2670,8 +2670,8 @@ installation directory. This is typically used for debugging. @vindex AUTOMAKE_LIBDIR The environment variable @env{AUTOMAKE_LIBDIR} provides another way to -set the directory containing Automake data files. However -@option{--libdir} takes precedence over it. +set the directory containing Automake data files. The +@option{--libdir} option takes precedence over it. @item --print-libdir @opindex --print-libdir @@ -7474,7 +7474,7 @@ be known only after @file{foo.o} has been compiled (@pxref{Dependencies}). The symptom is as follows. @example -% make +% @kbd{make} source='foo.c' object='foo.o' libtool=no \ depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \ depmode=gcc /bin/sh ./depcomp \ @@ -7509,7 +7509,7 @@ bindir.h: Makefile See how @file{bindir.h} gets built first: @example -% make +% @kbd{make} echo '#define bindir "/usr/local/bin"' >bindir.h make all-am make[1]: Entering directory `/home/adl/tmp' @@ -7526,12 +7526,12 @@ However, as said earlier, @code{BUILT_SOURCES} applies only to the if you try to run @samp{make foo} explicitly: @example -% make clean -rm -f bindir.h -rm -f foo +% @kbd{make clean} +test -z "bindir.h" || rm -f bindir.h +test -z "foo" || rm -f foo rm -f *.o -% : > .deps/foo.Po # Suppress previously recorded dependencies -% make foo +% @kbd{: > .deps/foo.Po} # Suppress previously recorded dependencies +% @kbd{make foo} source='foo.c' object='foo.o' libtool=no \ depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \ depmode=gcc /bin/sh ./depcomp \ @@ -8540,7 +8540,7 @@ be defined to specify additional files to clean. These variables are @trindex maintainer-clean-local When cleaning involves more than deleting some hard-coded list of files, it is also possible to supplement the cleaning rules with your -own commands: define a rule for any of the +own commands. Simply define a rule for any of the @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local}, or @code{maintainer-clean-local} targets (@pxref{Extending}). A common case is deleting a directory, for instance, a directory created by the @@ -8885,16 +8885,8 @@ example, AM_DISTCHECK_DVI_TARGET = pdf @end example -To make @code{dvi} into a do-nothing target, add it to your -@file{Makefile.am} with no commands: - -@example -dvi: -@end example - -@noindent -As usual with Automake, your user-defined target will override -Automake's target (@pxref{Extending}). +To make @code{dvi} into a do-nothing target, see the example for +@code{EMPTY_AUTOMAKE_TARGETS} in @ref{Third-Party Makefiles}. @trindex distcheck-hook @subheading distcheck-hook @@ -9894,7 +9886,7 @@ The @file{.trs} file is used to register some metadata through the use of custom reStructuredText fields. This metadata is expected to be employed in various ways by the parallel test harness; for example, to count the test results when printing the testsuite summary, or to decide -which tests to re-run upon @command{make recheck}. Unrecognized metadata +which tests to rerun upon @command{make recheck}. Unrecognized metadata in a @file{.trs} file is currently ignored by the harness, but this might change in the future. The list of currently recognized metadata follows. @@ -9972,7 +9964,7 @@ following lines: @end example @noindent -Then the corresponding test script will be re-run by @command{make check}, +Then the corresponding test script will be rerun by @command{make check}, will contribute with @emph{five} test results to the testsuite summary (three of these tests being successful, one failed, and one skipped), and the content of the corresponding @file{.log} file will @emph{not} be @@ -11324,7 +11316,7 @@ gcc -Wall -o foo main.o func.o @i{Clean up, so that we can rebuild everything from scratch.} % @kbd{make clean} -rm -f foo +test -z "foo" || rm -f foo rm -f *.o @i{Silent rules enabled: the output is minimal but informative. In @@ -11517,17 +11509,17 @@ As far as rules are concerned, a user-defined rule overrides any @cindex overriding semantics @cindex rules, overriding -These overriding semantics make it possible to fine-tune some default +These overriding semantics make it possible to fine tune some default settings of Automake, or replace some of its rules. Overriding Automake rules is often inadvisable, particularly in the topmost directory of a package with subdirectories. The @option{-Woverride} -option (@pxref{automake Invocation}) comes in handy to catch definitions -overridden by accident. +option (@pxref{automake Invocation}) comes in handy to catch overridden +definitions. -Automake does not make any distinction between rules with commands and -rules that only specify dependencies. So it is not possible to append -new dependencies to an @command{automake}-defined target without -redefining the entire rule. +Note that Automake does not make any distinction between rules with +commands and rules that only specify dependencies. So it is not +possible to append new dependencies to an @command{automake}-defined +target without redefining the entire rule. @cindex @option{-local} targets @cindex local targets @@ -11762,7 +11754,7 @@ Usually, many of these rules are irrelevant to the third-party subproject, but they are required for the whole package to work. It's OK to have a rule that does nothing, so if you are integrating a third-party project with no documentation or tag support, you could -simply augment its @file{Makefile} as follows: +augment its @file{Makefile} as follows: @vindex EMPTY_AUTOMAKE_TARGETS @cindex Automake targets, no-op @@ -11858,16 +11850,16 @@ EXTRA_DIST = subdir/Makefile subdir/program.c ... Pushing this idea to the extreme, it is also possible to ignore the subproject build system and build everything from this proxy -@file{Makefile.am}. This might sound very sensible if you need VPATH +@file{Makefile.am}. This might well be sensible if you need VPATH builds but the subproject does not support them. @node Distributing @chapter Distributing @file{Makefile.in}s Automake places no restrictions on the distribution of the resulting -@file{Makefile.in}s. We still encourage software authors to -distribute their work under terms like those of the GPL, but doing so -is not required to use Automake. +@file{Makefile.in}s. We encourage software authors to distribute +their work under terms like those of the GPL, but doing so is not +required to use Automake. Some of the files that can be automatically installed via the @option{--add-missing} switch do fall under the GPL@. However, these also