[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: sections without nodes in automake manual?
|
From: |
Ralf Wildenhues |
|
Subject: |
Re: sections without nodes in automake manual? |
|
Date: |
Fri, 27 Mar 2009 07:57:21 +0100 |
|
User-agent: |
Mutt/1.5.18 (2008-05-17) |
Hi Karl,
it took me the better part of a year to find enough energy to attack
<http://thread.gmane.org/gmane.comp.sysutils.automake.bugs/4205>.
* Karl Berry wrote on Wed, Jun 04, 2008 at 11:32:47PM CEST:
> AIUI, the subsubheadings do not cause entries in the contents of the
> PDF file. I'm not sure I think that's better, though. Are there
> other differences I overlooked?
>
> Not in terms of formatting, but in terms of theory and how Texinfo is
> typically used -- @section and the like should always be used with a
> corresponding @node; to get just a "heading" with no corresponding node,
> use the @heading series.
I understand that overly long nodes are not good, and I understand that
@sections and probably @subsections should be on separate nodes. OTOH
I'm not sure I like info files where each 5-line subsubsection is a
separate node; that really kills any reading flow, and is confusing if
they depend on each other to make sense. I've seen several such info
files before, and did not find them very useful.
OTOH, in some cases the best thing would be to just not have that many
subsubsections, and I see that using the heading commands is better.
> do you rather propose to split into several nodes, or just use less
> headings?
>
> I think it would be better to add the @node commands (and, consequently,
> @menu's also). That would make the Info version of the manual nicer to
> browse, since the nodes won't be so long.
OK. Here is a proposed patch, against the 'next' branch in Automake's
git repository. It's a compromise that splits up nodes where I think
the topics are conceptually separate enough so that a split won't hurt
the flow of reading too much. Where the nodes aren't split, I've
changed to the @..heading set of commands. I've rewritten the
Conditionals node a bit more, as it seemed to really fall out of line
with the others. Also, I went over all in-file references to the
changed nodes and adjusted them if necessary.
I'd really appreciate a look-over. Esp. the node names can probably be
improved, and we should do that before 1.11 final so that URLs don't
change afterwards.
For example, one thing I don't like much with the result yet is that the
introductory chapter has a section about two-part install, and its name
is very similar to the section about two-part install later.
FWIW, I intend to not apply this to branch-1-10, to keep the HTML
sectioning stable across stable releases.
Cheers, and thanks again,
Ralf
Reorganize nodes in the manual.
Avoid texinfo sectioning commands without nodes, by either
introducing new nodes along with menus, or using headings
commands. Adjust all references.
* doc/automake.texi: Throughout the manual, adjust references to
new or changed node names.
(Top): List new menus and nodes introduced below.
(Macro search path): Rename subsubsections to subsubheadings.
(Conditional Subdirectories): Introduce sub menu and split ...
(SUBDIRS vs DIST_SUBDIRS, Subdirectories with AM_CONDITIONAL)
(Subdirectories with AC_SUBST, Non-configured Subdirectories):
... into these new nodes.
(Conditional Sources): Rename subsubsections to subsubheadings.
(Conditional Programs): Likewise.
(Libtool Issues): Introduce sub menu and split into ...
(Required file ltmain.sh not found)
(Objects created both with libtool and without): ... these new
nodes.
(Built sources example): Rename unnumberedsubsecs to
subsubheadings.
(Install): Introduce sub menu and split into ...
(Basics of Installation, The two Parts of Install)
(Extending Installation, Staged Installs)
(Install Rules for the User): ... these new nodes.
(Dist): Introduce sub menu and split into ...
(Basics of Distribution, Fine-grained Distribution Control)
(The dist Hook, Checking the Distribution)
(The Types of Distributions): ... these new nodes.
(Tests): Introduce sub menu and split into ...
(Simple Tests, Simple Tests using parallel-tests, DejaGnu Tests)
(Install Tests): ... these new nodes.
(Conditionals): Move the portability paragraph up, introduce sub
menu and split into ...
(Usage of Conditionals, Limits of Conditionals): ... these new
nodes. Link to several sections throughout the manual that deal
with specific usage of conditionals.
(CVS): Rename subsections to subheadings.
(maintainer-mode): Likewise.
(Flag Variables Ordering): Likewise.
(Dependency Tracking Evolution): Introduce sub menu and split
into ...
(First Take on Dependencies, Dependencies As Side Effects)
(Dependencies for the User, Techniques for Dependencies)
(Recommendations for Tools, Future Directions for Dependencies):
... these new nodes.
Report by Karl Berry.
diff --git a/doc/automake.texi b/doc/automake.texi
index d3b72a5..604e86d 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -199,6 +199,13 @@ Directories
* Alternative:: Subdirectories without recursion
* Subpackages:: Nesting packages
+Conditional Subdirectories
+
+* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
+* Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
+* Subdirectories with AC_SUBST:: Another way for conditional recursion
+* Non-configured Subdirectories:: Not even creating a @samp{Makefile}
+
Building Programs and Libraries
* A Program:: Building a program
@@ -279,12 +286,40 @@ Building documentation
* Texinfo:: Texinfo
* Man pages:: Man pages
+Installation
+
+* Basics of Installation:: What gets installed where
+* The two Parts of Install:: Installing data and programs separately
+* Extending Installation:: Adding your own rules for installation
+* Staged Installs:: Installation in a temporary location
+* Install Rules for the User:: Useful additional rules
+
+Distribution
+
+* Basics of Distribution:: Files distributed by default
+* Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
+* The dist Hook:: A target for last-minute distribution changes
+* Checking the Distribution:: @samp{make distcheck} explained
+* The Types of Distributions:: A variety of formats and compression methods
+
+Support for Test Suites
+
+* Simple Tests:: Listing programs and scripts in @code{TESTS}
+* Simple Tests using parallel-tests:: More powerful test driver
+* DejaGnu Tests:: Interfacing with the external testing framework
+* Install Tests:: Running tests on installed packages
+
Miscellaneous Rules
* Tags:: Interfacing to etags and mkid
* Suffixes:: Handling new file extensions
* Multilibs:: Support for multilibs.
+Conditionals
+
+* Usage of Conditionals:: Declaring conditional content
+* Limits of Conditionals:: Enclosing complete statements
+
When Automake Isn't Enough
* Extending:: Adding new rules or overriding existing ones.
@@ -309,6 +344,15 @@ History of Automake
* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
* Releases:: Statistics about Automake Releases
+Dependency Tracking Evolution
+
+* First Take on Dependencies:: Precomputed dependency tracking
+* Dependencies As Side Effects:: Update at developer compile time
+* Dependencies for the User:: Update at user compile time
+* Techniques for Dependencies:: Alternative approaches
+* Recommendations for Tools:: What tool writers can do to help
+* Future Directions for Dependencies:: Languages Automake does not know
+
Copying This Manual
* GNU Free Documentation License:: License for copying this manual
@@ -927,8 +971,8 @@ provided earlier (@pxref{Standard Directory Variables}),
all the
variables based on @var{exec-prefix} designate architecture-dependent
directories whose files will be installed by @code{make install-exec}.
The others designate architecture-independent directories and will
-serve files installed by @code{make install-data}. @xref{Install},
-for more details.
+serve files installed by @code{make install-data}. @xref{The two Parts
+of Install}, for more details.
Here is how we could revisit our two-host installation example,
assuming that (1) we want to install the package directly in
@@ -1183,8 +1227,8 @@ being erased by @code{make clean}, or even @code{VPATH}
builds not
working).
@xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
address@hidden distcheck}. @xref{Dist}, for more information about
address@hidden
address@hidden distcheck}. @xref{Checking the Distribution}, for more
+information about @code{distcheck}.
@node Dependency Tracking
@subsection Automatic Dependency Tracking
@@ -2017,10 +2061,10 @@ data2_DATA = address@hidden @dots{} address@hidden
@noindent
and will cause Automake to treat the two lists separately during
address@hidden install}. See @ref{Install} for choosing directory names
-that will keep the ordering of the two parts of installation
-(@pxref{Two-Part Install}). Note that @code{make dist} may still
-only work on a host with a higher length limit in this example.
address@hidden install}. See @ref{The two Parts of Install} for choosing
+directory names that will keep the ordering of the two parts of
+installation Note that @code{make dist} may still only work on a host
+with a higher length limit in this example.
Automake itself employs a couple of strategies to avoid long command
lines. For example, when @address@hidden@}/} is prepended to file
@@ -2924,7 +2968,7 @@ This introduces an Automake conditional
(@pxref{Conditionals}).
This macro allows @code{automake} to detect subsequent access within
@file{configure.ac} to a conditional previously introduced with
@code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
-(@pxref{Conditionals}).
+(@pxref{Usage of Conditionals}).
@item AM_GNU_GETTEXT
This macro is required for packages that use GNU gettext
@@ -3180,7 +3224,7 @@ As an example, suppose that @command{automake-1.6.2} was
configured with
As explained in (@pxref{aclocal options}), there are several options that
can be used to change or extend this search path.
address@hidden Modifying the macro search path: @option{--acdir}
address@hidden Modifying the macro search path: @option{--acdir}
The most erroneous option to modify the search path is
@address@hidden, which changes default directory and
@@ -3194,7 +3238,7 @@ drops the @var{APIVERSION} directory. For example, if
one specifies
This option, @option{--acdir}, is intended for use by the internal
Automake test suite only; it is not ordinarily needed by end-users.
address@hidden Modifying the macro search path: @samp{-I @var{dir}}
address@hidden Modifying the macro search path: @samp{-I @var{dir}}
Any extra directories specified using @option{-I} options
(@pxref{aclocal options}) are @emph{prepended} to this search list. Thus,
@@ -3207,7 +3251,7 @@ Any extra directories specified using @option{-I} options
@item @var{acdir}
@end enumerate
address@hidden Modifying the macro search path: @file{dirlist}
address@hidden Modifying the macro search path: @file{dirlist}
@cindex @file{dirlist}
There is a third mechanism for customizing the search path. If a
@@ -4095,6 +4139,14 @@ Variables, autoconf, The Autoconf Manual}). Using
Automake
conditionals is the preferred solution. Before we illustrate these
two possibilities, let's introduce @code{DIST_SUBDIRS}.
address@hidden
+* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
+* Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
+* Subdirectories with AC_SUBST:: Another way for conditional recursion
+* Non-configured Subdirectories:: Not even creating a @samp{Makefile}
address@hidden menu
+
address@hidden SUBDIRS vs DIST_SUBDIRS
@subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
@cindex @code{DIST_SUBDIRS}, explained
@@ -4127,7 +4179,8 @@ If @code{SUBDIRS} contains @code{AC_SUBST} variables,
does not know the possible values of these variables. In this case
@code{DIST_SUBDIRS} needs to be defined manually.
address@hidden Conditional subdirectories with @code{AM_CONDITIONAL}
address@hidden Subdirectories with AM_CONDITIONAL
address@hidden Conditional Subdirectories with @code{AM_CONDITIONAL}
@cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
@cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
@@ -4168,6 +4221,7 @@ In this case Automake will define @samp{DIST_SUBDIRS =
src opt}
automatically because it knows that @code{MAYBE_OPT} can contain
@samp{opt} in some condition.
address@hidden Subdirectories with AC_SUBST
@subsection Conditional Subdirectories with @code{AC_SUBST}
@cindex @code{SUBDIRS} and @code{AC_SUBST}
@cindex @code{AC_SUBST} and @code{SUBDIRS}
@@ -4202,6 +4256,7 @@ The drawback is that since Automake cannot guess what the
possible
values of @code{MAYBE_OPT} are, it is necessary to define
@code{DIST_SUBDIRS}.
address@hidden Non-configured Subdirectories
@subsection Non-configured Subdirectories
@cindex Subdirectories, configured conditionally
@@ -4319,7 +4374,8 @@ nobase_include_HEADERS = sys/types.h
@vindex nodist_
@samp{nobase_} should be specified first when used in conjunction with
-either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
+either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
+Control}). For instance:
@example
nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
@@ -4664,7 +4720,7 @@ Fortunately there are two other ways to achieve the same
result. One is
to use configure substitutions in @code{_LDADD} variables, the other is
to use an Automake conditional.
address@hidden Conditional compilation using @code{_LDADD} substitutions
address@hidden Conditional compilation using @code{_LDADD} substitutions
@cindex @code{EXTRA_prog_SOURCES}, defined
@@ -4702,7 +4758,7 @@ either @file{hello-linux.o} or @file{hello-generic.o},
and added to
both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
built and linked in.
address@hidden Conditional compilation using Automake conditionals
address@hidden Conditional compilation using Automake conditionals
An often simpler way to compile source files conditionally is to use
Automake conditionals. For instance, you could use this
@@ -4748,7 +4804,7 @@ at configure time. For instance, GNU @code{cpio} only
builds
achieve conditional compilation of programs are the same you can use
to compile source files conditionally: substitutions or conditionals.
address@hidden Conditional programs using @command{configure} substitutions
address@hidden Conditional programs using @command{configure} substitutions
@vindex EXTRA_PROGRAMS
@cindex @code{EXTRA_PROGRAMS}, defined
@@ -4773,7 +4829,7 @@ Obviously it cannot rewrite values obtained at run-time
through
appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
['address@hidden@}'])}.
address@hidden Conditional programs using Automake conditionals
address@hidden Conditional programs using Automake conditionals
You can also use Automake conditionals (@pxref{Conditionals}) to
select programs to be built. In this case you don't have to worry
@@ -5289,6 +5345,12 @@ performed automatically by Autoconf (@pxref{AC_LIBOBJ vs
LIBOBJS, ,
@node Libtool Issues
@subsection Common Issues Related to Libtool's Use
address@hidden
+* Required file ltmain.sh not found:: The need to run libtoolize
+* Objects created both with libtool and without:: Avoid a specific build race
address@hidden menu
+
address@hidden Required file ltmain.sh not found
@subsubsection @samp{required file `./ltmain.sh' not found}
@cindex @file{ltmain.sh} not found
@cindex @command{libtoolize}, no longer run by @command{automake}
@@ -5317,6 +5379,7 @@ replacing existing @file{bootstrap.sh} or
@file{autogen.sh} scripts by
a call to @command{autoreconf} should also free you from any similar
incompatible change in the future.
address@hidden Objects created both with libtool and without
@subsubsection Objects @samp{created with both libtool and without}
Sometimes, the same source file is used both to build a libtool
@@ -6696,7 +6759,7 @@ bin_PROGRAMS = liver$(EXEEXT)
The targets Automake generates are likewise given the @samp{$(EXEEXT)}
extension.
-The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Tests}) are also
+The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests}) are
also
rewritten if they contain filenames that have been declared as programs
in the same @file{Makefile}. (This is mostly useful when some programs
from @code{check_PROGRAMS} are listed in @code{TESTS}.)
@@ -6807,7 +6870,7 @@ automake: automake.in Makefile
Such scripts for which a build rule has been supplied need to be
deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
sources have to be distributed, usually with @code{EXTRA_DIST}
-(@pxref{Dist}).
+(@pxref{Basics of Distribution}).
Another common way to build scripts is to process them from
@file{configure} with @code{AC_CONFIG_FILES}. In this situation
@@ -7010,7 +7073,7 @@ We suggest several implementations below. It's not meant
to be an
exhaustive listing of all ways to handle built sources, but it will give
you a few ideas if you encounter this issue.
address@hidden First try
address@hidden First try
This first implementation will illustrate the bootstrap issue mentioned
in the previous section (@pxref{Sources}).
@@ -7051,7 +7114,7 @@ for instance, it should be inspected while generating tags
(@pxref{Tags}). In other words, it does not help our present problem,
and the build would fail identically without it.
address@hidden Using @code{BUILT_SOURCES}
address@hidden Using @code{BUILT_SOURCES}
A solution is to require @file{bindir.h} to be built before anything
else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
@@ -7100,7 +7163,7 @@ foo.c:2: bindir.h: No such file or directory
make: *** [foo.o] Error 1
@end example
address@hidden Recording dependencies manually
address@hidden Recording dependencies manually
Usually people are happy enough with @code{BUILT_SOURCES} because they
never build targets such as @samp{make foo} before @samp{make all}, as
@@ -7136,7 +7199,7 @@ because Automake doesn't have to output any
@samp{foo.$(OBJEXT):}
target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
Always check the generated @file{Makefile.in} if you do this.
address@hidden Build @file{bindir.h} from @file{configure}
address@hidden Build @file{bindir.h} from @file{configure}
It's possible to define this preprocessor macro from @file{configure},
either in @file{config.h} (@pxref{Defining Directories, , Defining
@@ -7161,7 +7224,7 @@ However, it's not always possible to build sources from
@file{configure}, especially when these sources are generated by a tool
that needs to be built first.
address@hidden Build @file{bindir.c}, not @file{bindir.h}.
address@hidden Build @file{bindir.c}, not @file{bindir.h}.
Another attractive idea is to define @code{bindir} as a variable or
function exported from @file{bindir.o}, and build @file{bindir.c}
@@ -7181,7 +7244,7 @@ need to be built, so it won't cause any trouble.
@file{bindir.o} is
always dependent on @file{bindir.c}, so @file{bindir.c} will get built
first.
address@hidden Which is best?
address@hidden Which is best?
There is no panacea, of course. Each solution has its merits and
drawbacks.
@@ -7796,7 +7859,8 @@ notrans_man_MANS = foo.3
@cindex @code{nodist_} and @code{notrans_}
@samp{notrans_} must be specified first when used in conjunction with
-either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
+either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
+Control}). For instance:
@example
notrans_dist_man3_MANS = bar.3
@@ -7808,13 +7872,22 @@ notrans_dist_man3_MANS = bar.3
@cindex Installation support
@cindex @samp{make install} support
address@hidden Basics of installation
-
Naturally, Automake handles the details of actually installing your
program once it has been built. All files named by the various
primaries are automatically installed in the appropriate places when the
user runs @samp{make install}.
address@hidden
+* Basics of Installation:: What gets installed where
+* The two Parts of Install:: Installing data and programs separately
+* Extending Installation:: Adding your own rules for installation
+* Staged Installs:: Installation in a temporary location
+* Install Rules for the User:: Useful additional rules
address@hidden menu
+
address@hidden Basics of Installation
address@hidden Basics of Installation
+
A file named in a primary is installed by copying the built file into
the appropriate directory. The base name of the file is used when
installing.
@@ -7852,7 +7925,8 @@ rely on any particular file installation order even among
different
file types (library dependencies are an exception here).
address@hidden The two parts of install
address@hidden The two Parts of Install
address@hidden The two Parts of Install
Automake generates separate @code{install-data} and @code{install-exec}
rules, in case the installer is installing on multiple machines that
@@ -7885,7 +7959,8 @@ the name (e.g., @code{myexecbin_PROGRAMS}) is installed by
@code{install-exec}. All other user-defined prefixes are installed by
@code{install-data}.
address@hidden Extending installation
address@hidden Extending Installation
address@hidden Extending Installation
It is possible to extend this mechanism by defining an
@code{install-exec-local} or @code{install-data-local} rule. If these
@@ -7901,7 +7976,8 @@ instance, it is possible to perform post-installation
modifications
using an install hook. @xref{Extending}, for some examples.
@cindex Install hook
address@hidden Staged installs
address@hidden Staged Installs
address@hidden Staged Installs
@vindex DESTDIR
Automake generates support for the @code{DESTDIR} variable in all
@@ -7934,7 +8010,8 @@ must write that code to respect @code{DESTDIR}.
@xref{Makefile Conventions, , , standards, The GNU Coding Standards},
for another usage example.
address@hidden Rules for the user
address@hidden Install Rules for the User
address@hidden Install Rules for the User
Automake also generates rules for targets @code{uninstall},
@code{installdirs}, and @code{install-strip}.
@@ -8016,7 +8093,16 @@ We recommend that you follow this same set of heuristics
in your
@node Dist
@chapter What Goes in a Distribution
address@hidden Basics of distribution
address@hidden
+* Basics of Distribution:: Files distributed by default
+* Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
+* The dist Hook:: A target for last-minute distribution changes
+* Checking the Distribution:: @samp{make distcheck} explained
+* The Types of Distributions:: A variety of formats and compression methods
address@hidden menu
+
address@hidden Basics of Distribution
address@hidden Basics of Distribution
@cindex @samp{make dist}
@@ -8075,7 +8161,8 @@ exact list of subdirectories to include in the
distribution
(@pxref{Conditional Subdirectories}).
address@hidden Fine-grained distribution control
address@hidden Fine-grained Distribution Control
address@hidden Fine-grained Distribution Control
@vindex dist_
@vindex nodist_
@@ -8097,7 +8184,8 @@ bin_PROGRAMS = foo
nodist_foo_SOURCES = do-not-distribute.c
@end example
address@hidden The dist hook
address@hidden The dist Hook
address@hidden The dist Hook
@trindex dist-hook
@@ -8147,7 +8235,8 @@ Note that when packages are nested using
@code{AC_CONFIG_SUBDIRS}
@samp{$(top_distdir)} are relative to the package where @samp{make
dist} was run, not to any sub-packages involved.
address@hidden Checking the distribution
address@hidden Checking the Distribution
address@hidden Checking the Distribution
@cindex @samp{make distcheck}
@cindex @samp{make distcleancheck}
@@ -8242,7 +8331,8 @@ distuninstallcheck:
@@:
@end example
address@hidden The types of distributions
address@hidden The Types of Distributions
address@hidden The Types of Distributions
Automake generates rules to provide archives of the project for
distributions in various formats. Their targets are:
@@ -8297,6 +8387,14 @@ default, only the @code{dist-gzip} target is hooked to
@code{dist}.
Automake supports three forms of test suites, the first two of which
are very similar.
address@hidden
+* Simple Tests:: Listing programs and scripts in @code{TESTS}
+* Simple Tests using parallel-tests:: More powerful test driver
+* DejaGnu Tests:: Interfacing with the external testing framework
+* Install Tests:: Running tests on installed packages
address@hidden menu
+
address@hidden Simple Tests
@section Simple Tests
If the variable @code{TESTS} is defined, its value is taken to be a
@@ -8305,7 +8403,8 @@ Programs needing data files should look for them in
@code{srcdir}
(which is both an environment variable and a make variable) so they
work when building in a separate directory (@pxref{Build Directories,
, Build Directories , autoconf, The Autoconf Manual}), and in
-particular for the @code{distcheck} rule (@pxref{Dist}).
+particular for the @code{distcheck} rule (@pxref{Checking the
+Distribution}).
For each of the @code{TESTS}, the result of execution is printed along
with the test name, where @code{PASS} denotes a successful test,
@@ -8369,11 +8468,12 @@ by the tests, not the tests themselves. Of course you
can set
@code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
address@hidden Simple tests using @samp{parallel-tests}
address@hidden Simple Tests using parallel-tests
address@hidden Simple Tests using @samp{parallel-tests}
@cindex @option{parallel-tests}, Using
The option @option{parallel-tests} (@pxref{Options}) enables a test
-suite driver that is mostly compatible to the simple test driver
-described above, but provides a few more features and slightly different
+suite driver that is mostly compatible to the simple test driver described
+in the previous section, but provides a few more features and slightly
different
semantics. It features concurrent execution of tests with @code{make -j},
allows to specify inter-test dependencies, lazy reruns of tests that
have not completed in a prior run, summary and verbose output in
@@ -8505,6 +8605,7 @@ literal test names, @command{automake} can generate
per-target rules
to avoid this limitation.
address@hidden DejaGnu Tests
@section DejaGnu Tests
If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
@@ -8549,6 +8650,7 @@ dejagnu, The DejaGnu Manual}.
In either case, the testing is done via @samp{make check}.
address@hidden Install Tests
@section Install Tests
The @code{installcheck} target is available to the user as a way to
@@ -8699,13 +8801,13 @@ in the first few lines of the @file{NEWS} file.
@item @option{color-tests}
@cindex Option, @option{color-tests}
@opindex color-tests
-Cause output of the simple test suite (@pxref{Tests}) to be
+Cause output of the simple test suite (@pxref{Simple Tests}) to be
colorized on capable terminals.
@item @option{dejagnu}
@cindex Option, @option{dejagnu}
@opindex dejagnu
-Cause @command{dejagnu}-specific rules to be generated. @xref{Tests}.
+Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
@item @option{dist-bzip2}
@cindex Option, @option{dist-bzip2}
@@ -8823,7 +8925,7 @@ this directory.
@cindex Option, @option{parallel-tests}
@opindex parallel-tests
Enable test suite driver for @code{TESTS} that can run tests in parallel
-(@pxref{Tests}, for more information).
+(@pxref{Simple Tests using parallel-tests}, for more information).
@item @option{readme-alpha}
@cindex Option, @option{readme-alpha}
@@ -9140,7 +9242,24 @@ they are needed to rebuild @file{Makefile.in}.
Automake supports a simple type of conditionals.
address@hidden Usage
+These conditionals are not the same as conditionals in
+GNU Make. Automake conditionals are checked at configure time by the
address@hidden script, and affect the translation from
address@hidden to @file{Makefile}. They are based on options passed
+to @file{configure} and on results that @file{configure} has discovered
+about the host system. GNU Make conditionals are checked at @command{make}
+time, and are based on variables passed to the make program or defined
+in the @file{Makefile}.
+
+Automake conditionals will work with any make program.
+
address@hidden
+* Usage of Conditionals:: Declaring conditional content
+* Limits of Conditionals:: Enclosing complete statements
address@hidden menu
+
address@hidden Usage of Conditionals
address@hidden Usage of Conditionals
@acindex AM_CONDITIONAL
Before using a conditional, you must define it by using
@@ -9246,20 +9365,8 @@ AM_COND_IF([SHELL_WRAPPER],
[AC_CONFIG_FILES([wrapper:wrapper.in])])
@end example
address@hidden Portability
-
-Note that conditionals in Automake are not the same as conditionals in
-GNU Make. Automake conditionals are checked at configure time by the
address@hidden script, and affect the translation from
address@hidden to @file{Makefile}. They are based on options passed
-to @file{configure} and on results that @file{configure} has discovered
-about the host system. GNU Make conditionals are checked at @command{make}
-time, and are based on variables passed to the make program or defined
-in the @file{Makefile}.
-
-Automake conditionals will work with any make program.
-
address@hidden Limits
address@hidden Limits of Conditionals
address@hidden Limits of Conditionals
Conditionals should enclose complete statements like variables or
rules definitions. Automake cannot deal with conditionals used inside
@@ -9286,7 +9393,8 @@ endif
AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
@end example
address@hidden or
address@hidden
+or
@example
AM_CPPFLAGS = -DFEATURE_A
@@ -9296,6 +9404,12 @@ endif
AM_CPPFLAGS += -DFEATURE_B
@end example
+More details and examples of conditionals are described alongside
+various Automake features in this manual (@pxref{Conditional
+Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
+Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
+Libtool Sources}).
+
@node Gnits
@chapter The effect of @option{--gnu} and @option{--gnits}
@@ -9612,10 +9726,10 @@ destination directory in order to create relative links.
When writing @code{install-exec-hook} or @code{install-data-hook},
please bear in mind that the exec/data distinction is based on the
-installation directory, not on the primary used (@pxref{Install}). So
-a @code{foo_SCRIPTS} will be installed by @code{install-data}, and a
address@hidden will be installed by @code{install-exec}. You
-should define your hooks consequently.
+installation directory, not on the primary used (@pxref{The two Parts of
+Install}). So a @code{foo_SCRIPTS} will be installed by
address@hidden, and a @code{barexec_SCRIPTS} will be installed by
address@hidden You should define your hooks consequently.
@c FIXME should include discussion of variables you can use in these
@c rules
@@ -9655,7 +9769,7 @@ constructed. Of course this target is not required if the
@option{no-dist} option (@pxref{Options}) is used.
The variables @samp{$(top_distdir)} and @samp{$(distdir)}
-(@pxref{Dist}) will be passed from the outer package to the subpackage
+(@pxref{The dist Hook}) will be passed from the outer package to the subpackage
when the @code{distdir} target is invoked. These two variables have
been adjusted for the directory that is being recursed into, so they
are ready to use.
@@ -9961,7 +10075,7 @@ lists.
@node CVS
@section CVS and generated files
address@hidden Background: distributed generated files
address@hidden Background: distributed generated files
@cindex generated files, distributed
@cindex rebuild rules
@@ -9982,7 +10096,7 @@ As generated files shipped in packages are up-to-date,
and because
@command{tar} preserves times-tamps, these rebuild rules are not
triggered when a user unpacks and builds a package.
address@hidden Background: CVS and timestamps
address@hidden Background: CVS and timestamps
@cindex timestamps and CVS
@cindex CVS and timestamps
@@ -10005,7 +10119,7 @@ after a @command{cvs update} that updates both files,
even if
checked in. Calling @command{make} will then trigger a spurious rebuild
of @file{configure}.
address@hidden Living with CVS in Autoconfiscated projects
address@hidden Living with CVS in Autoconfiscated projects
@cindex CVS and generated files
@cindex generated files and CVS
@@ -10105,7 +10219,7 @@ produces bogus output (for instance a non-portable C
file), something
other developers could have noticed if they weren't using their own
versions of this tool.
address@hidden Third-party files
address@hidden Third-party files
@cindex CVS and third-party files
@cindex third-party files and CVS
@@ -10123,7 +10237,7 @@ Issues, Integrating with CVS, gettext, GNU gettext
tools}.
@node maintainer-mode
@section @command{missing} and @code{AM_MAINTAINER_MODE}
address@hidden @command{missing}
address@hidden @command{missing}
@cindex @command{missing}, purpose
The @command{missing} script is a wrapper around several maintainer
@@ -10152,7 +10266,7 @@ rule is spuriously triggered, halting the build. This
failure to let
the build continue is one of the arguments of the
@code{AM_MAINTAINER_MODE} advocates.
address@hidden @code{AM_MAINTAINER_MODE}
address@hidden @code{AM_MAINTAINER_MODE}
@cindex @code{AM_MAINTAINER_MODE}, purpose
@acindex AM_MAINTAINER_MODE
@@ -10348,8 +10462,8 @@ Nowadays it is no longer worth worrying about the 8.3
limits of
This is a diagnostic you might encounter while running @samp{make
distcheck}.
-As explained in @ref{Dist}, @samp{make distcheck} attempts to build
-and check your package for errors like this one.
+As explained in @ref{Checking the Distribution}, @samp{make distcheck}
+attempts to build and check your package for errors like this one.
@samp{make distcheck} will perform a @code{VPATH} build of your
package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
@@ -10481,7 +10595,8 @@ in distributing it.
@vrindex distcleancheck_listfiles
For desperate cases, it's always possible to disable this check by
-setting @code{distcleancheck_listfiles} as documented in @ref{Dist}.
+setting @code{distcleancheck_listfiles} as documented in @ref{Checking
+the Distribution}.
Make sure you do understand the reason why @samp{make distcheck}
complains before you do this. @code{distcleancheck_listfiles} is a
way to @emph{hide} errors, not to fix them. You can always do better.
@@ -10508,7 +10623,7 @@ put the flag into @code{AM_CXXFLAGS} it is prepended to
the other
flags, not appended.
@end display
address@hidden Compile Flag Variables
address@hidden Compile Flag Variables
@cindex Flag Variables, Ordering
@cindex Compile Flag Variables
@cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
@@ -10686,12 +10801,12 @@ Finally, we have avoided naming the variable of the
example
Automake to think that this is actually a per-target variable (like
@code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
address@hidden Other Variables
address@hidden Other Variables
There are other variables in Automake that follow similar principles
to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
-DejaGnu tests (@pxref{Tests}) use @code{RUNTESTDEFAULTFLAGS} and
+DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
@code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
(@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
@code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
@@ -10705,7 +10820,7 @@ obeys this naming scheme. The slight difference is that
However you should not think that all variables ending with
@code{FLAGS} follow this convention. For instance,
address@hidden (@pxref{Dist}) and
address@hidden (@pxref{Checking the Distribution}) and
@code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
are two variables that are only useful to the maintainer and have no
user counterpart.
@@ -12010,7 +12125,17 @@ tracking methods, their flaws, and their fixes. We
conclude with
recommendations for tool writers, and by indicating future directions
for dependency tracking work in Automake.
address@hidden First Take
address@hidden
+* First Take on Dependencies:: Precomputed dependency tracking
+* Dependencies As Side Effects:: Update at developer compile time
+* Dependencies for the User:: Update at user compile time
+* Techniques for Dependencies:: Alternative approaches
+* Recommendations for Tools:: What tool writers can do to help
+* Future Directions for Dependencies:: Languages Automake does not know
address@hidden menu
+
address@hidden First Take on Dependencies
address@hidden First Take on Dependency Tracking
@unnumberedsubsubsec Description
Our first attempt at automatic dependency tracking was based on the
@@ -12069,6 +12194,7 @@ implementation of dependency tracking, I believe the
impetus and
inspiration was Jim Meyering. (I could be mistaken. If you know
otherwise feel free to correct me.)
address@hidden Dependencies As Side Effects
@subsection Dependencies As Side Effects
@unnumberedsubsubsec Description
@@ -12118,6 +12244,7 @@ output of @command{gcc} to include a dummy dependency
for each header
file.
@end itemize
address@hidden Dependencies for the User
@subsection Dependencies for the User
@unnumberedsubsubsec Description
@@ -12218,6 +12345,7 @@ because we have to encode two compilation rules in
@file{Makefile}
(with or without @command{depcomp}), the produced @file{Makefile}s are
larger.
address@hidden Techniques for Dependencies
@subsection Techniques for Computing Dependencies
There are actually several ways for a build tool like Automake to
@@ -12250,6 +12378,7 @@ powerful, but unfortunately it is not portable enough
for use in
@command{automake}.
@end table
address@hidden Recommendations for Tools
@subsection Recommendations for Tool Writers
We think that every compilation tool ought to be able to generate
@@ -12261,6 +12390,7 @@ bug. Finally, the tool should generate a dependency
for each probe,
instead of each successful file open, in order to avoid the duplicated
new header bug.
address@hidden Future Directions for Dependencies
@subsection Future Directions for Automake's Dependency Tracking
Currently, only languages and compilers understood by Automake can
@@ -12440,7 +12570,7 @@ parentheses is the number of generated test cases.
@c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
@c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
@c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
address@hidden LocalWords: unnumberedsubsec depfile tmpdepfile depmode const
interoperate
address@hidden LocalWords: depfile tmpdepfile depmode const interoperate
@c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
@c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
@c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
- Re: sections without nodes in automake manual?,
Ralf Wildenhues <=