[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: |
Sat, 4 Apr 2009 11:14:07 +0200 |
|
User-agent: |
Mutt/1.5.18 (2008-05-17) |
Hello Karl,
below are two patches. The second one is very large, and is the one
that I pushed to the next branch on Sunday right before creating the
1.10b test release. The first one is new, I have just pushed it now,
to fix some names that I forgot in the large patch.
I consider this issue fixed now, I can't find any more nodes missing
capitalization.
Cheers, and thanks again,
Ralf
More node renaming in the manual.
* doc/automake.texi (Top): Adjust menu to ...
(API Versioning): ... this node being renamed from ...
(API versioning): ... this, and ...
(Wildcards): ... this being renamed from ...
(wildcards): ... this.
Report by Karl Berry.
diff --git a/doc/automake.texi b/doc/automake.texi
index 95ea5f2..cdc445a 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -117,7 +117,7 @@ section entitled address@hidden Free Documentation
License.''
* Cygnus:: The effect of @option{--cygnus}
* Not Enough:: When Automake is not Enough
* Distributing:: Distributing the Makefile.in
-* API versioning:: About compatibility between Automake versions
+* API Versioning:: About compatibility between Automake versions
* Upgrading:: Upgrading to a Newer Automake Version
* FAQ:: Frequently Asked Questions
* History:: Notes about the history of Automake
@@ -329,7 +329,7 @@ Frequently Asked Questions about Automake
* CVS:: CVS and generated files
* maintainer-mode:: missing and AM_MAINTAINER_MODE
-* wildcards:: Why doesn't Automake support wildcards?
+* Wildcards:: Why doesn't Automake support wildcards?
* Limitations on File Names:: Limitations on source and installed file names
* distcleancheck:: Files left in build directory after distclean
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
@@ -10040,8 +10040,8 @@ have a special exception allowing you to distribute
them with your
package, regardless of the licensing you choose.
address@hidden API versioning
address@hidden Automake API versioning
address@hidden API Versioning
address@hidden Automake API Versioning
New Automake releases usually include bug fixes and new features.
Unfortunately they may also introduce new bugs and incompatibilities.
@@ -10170,7 +10170,7 @@ lists.
@menu
* CVS:: CVS and generated files
* maintainer-mode:: missing and AM_MAINTAINER_MODE
-* wildcards:: Why doesn't Automake support wildcards?
+* Wildcards:: Why doesn't Automake support wildcards?
* Limitations on File Names:: Limitations on source and installed file names
* distcleancheck:: Files left in build directory after distclean
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
@@ -10424,7 +10424,7 @@ and because @command{missing} isn't enough if you have
the wrong
version of the tools.
address@hidden wildcards
address@hidden Wildcards
@section Why doesn't Automake support wildcards?
@cindex wildcards
@@ -12084,7 +12084,7 @@ facing similar troubles, for similar reasons.
@item 2002-03-05 Automake 1.6
This release introduced versioned installation (@pxref{API
-versioning}). This was mainly pushed by Havoc Pennington, taking the
+Versioning}). This was mainly pushed by Havoc Pennington, taking the
GNOME source tree as motive: due to incompatibilities between the
autotools it's impossible for the GNOME packages to switch to Autoconf
2.53 and Automake 1.5 all at once, so they are currently stuck with
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. Rename `non-configured' to
`unconfigured', capitalize headings and section names better.
(Top): List new menus and nodes introduced below.
(Length Limitations): Renamed from ...
(Length limitations): ... this.
(aclocal Options): Renamed from ...
(aclocal options): ... this.
(Macro Search Path): Renamed from ...
(Macro search path): ... this. Rename subsubsections to
subsubheadings.
(Public Macros, Obsolete Macros, Private Macros): Renamed from
(Public macros, Obsolete macros, Private macros): ... these.
(Conditional Subdirectories): Introduce sub menu and split ...
(SUBDIRS vs DIST_SUBDIRS, Subdirectories with AM_CONDITIONAL)
(Subdirectories with AC_SUBST, Unconfigured Subdirectories):
... into these new nodes. Adjust subsection names to node
names.
(Conditional Sources): Rename subsubsections to subsubheadings.
(Conditional Programs): Likewise.
(Program Variables): Renamed from ...
(Program variables): ... this.
(Libtool Issues): Introduce sub menu and split into ...
(Required file ltmain.sh not found)
(Objects created both with libtool and without): ... these new
nodes.
(Other Objects, Built Sources): Renamed from ...
(Other objects, Built sources): ... these.
(Built Sources Example): Renamed from ...
(Built sources example): this. Rename unnumberedsubsecs to
subsubheadings.
(Man Pages): Renamed from ...
(Man pages): ... this.
(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.
(Limitations on File Names): Renamed from ...
(limitations on file names): ... this.
(Flag Variables Ordering): Rename subsections to subheadings.
(Renamed Objects): Renamed from ...
(Renamed objects): ... this.
(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 Tool Writers)
(Future Directions for Dependencies): ... these new nodes.
Report by Karl Berry.
diff --git a/doc/automake.texi b/doc/automake.texi
index 4c751c7..764dad6 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -101,7 +101,7 @@ section entitled address@hidden Free Documentation
License.''
* configure:: Scanning configure.ac or configure.in
* Directories:: Declaring subdirectories
* Programs:: Building programs and libraries
-* Other objects:: Other derived objects
+* Other Objects:: Other derived objects
* Other GNU Tools:: Other GNU Tools
* Documentation:: Building documentation
* Install:: What gets installed
@@ -161,7 +161,7 @@ General ideas
* Strictness:: Standards conformance checking
* Uniform:: The Uniform Naming Scheme
* Canonicalization:: How derived variables are named
-* Length limitations:: Staying below the command line length limit
+* Length Limitations:: Staying below the command line length limit
* User Variables:: Variables reserved for the user
* Auxiliary Programs:: Programs automake might require
@@ -179,8 +179,8 @@ Scanning @file{configure.ac}
Auto-generating aclocal.m4
-* aclocal options:: Options supported by aclocal
-* Macro search path:: How aclocal finds .m4 files
+* aclocal Options:: Options supported by aclocal
+* Macro Search Path:: How aclocal finds .m4 files
* Extending aclocal:: Writing your own aclocal macros
* Local Macros:: Organizing local macros
* Serials:: Serial lines in Autoconf macros
@@ -188,9 +188,9 @@ Auto-generating aclocal.m4
Autoconf macros supplied with Automake
-* Public macros:: Macros that you can use.
-* Obsolete macros:: Macros that you should stop using.
-* Private macros:: Macros that you should not use.
+* Public Macros:: Macros that you can use.
+* Obsolete Macros:: Macros that you should stop using.
+* Private Macros:: Macros that you should not use.
Directories
@@ -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
+* Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
+
Building Programs and Libraries
* A Program:: Building a program
@@ -208,7 +215,7 @@ Building Programs and Libraries
library builds
* Default _SOURCES:: Default source files
* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
-* Program variables:: Variables used when building a program
+* Program Variables:: Variables used when building a program
* Yacc and Lex:: Yacc and Lex support
* C++ Support:: Compiling C++ sources
* Objective C Support:: Compiling Objective C sources
@@ -262,9 +269,9 @@ Other Derived Objects
* Data:: Architecture-independent data files
* Sources:: Derived sources
-Built sources
+Built Sources
-* Built sources example:: Several ways to handle built sources.
+* Built Sources Example:: Several ways to handle built sources.
Other GNU Tools
@@ -277,7 +284,30 @@ Other GNU Tools
Building documentation
* Texinfo:: Texinfo
-* Man pages:: Man pages
+* 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
@@ -285,6 +315,11 @@ Miscellaneous Rules
* 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.
@@ -295,10 +330,10 @@ Frequently Asked Questions about Automake
* CVS:: CVS and generated files
* maintainer-mode:: missing and AM_MAINTAINER_MODE
* wildcards:: Why doesn't Automake support wildcards?
-* limitations on file names:: Limitations on source and installed file names
+* Limitations on File Names:: Limitations on source and installed file names
* distcleancheck:: Files left in build directory after distclean
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
-* renamed objects:: Why are object files sometimes renamed?
+* Renamed Objects:: Why are object files sometimes renamed?
* Per-Object Flags:: How to simulate per-object flags?
* Multiple Outputs:: Writing rules for tools with many output files
* Hard-Coded Install Paths:: Installing to Hard-Coded Locations
@@ -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 Tool Writers:: 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
@@ -1043,7 +1087,7 @@ options.
@cindex Programs, renaming during installation
The GNU Build System provides means to automatically rename
-executables and manpages before they are installed (@pxref{Man pages}).
+executables and manpages before they are installed (@pxref{Man Pages}).
This is especially convenient
when installing a GNU package on a system that already has a
proprietary implementation you do not want to overwrite. For instance,
@@ -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
@@ -1689,7 +1733,7 @@ understand how Automake works.
* Strictness:: Standards conformance checking
* Uniform:: The Uniform Naming Scheme
* Canonicalization:: How derived variables are named
-* Length limitations:: Staying below the command line length limit
+* Length Limitations:: Staying below the command line length limit
* User Variables:: Variables reserved for the user
* Auxiliary Programs:: Programs automake might require
@end menu
@@ -1977,10 +2021,10 @@ Some primaries also allow additional prefixes that
control other
aspects of @command{automake}'s behavior. The currently defined prefixes
are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
These prefixes are explained later (@pxref{Program and Library Variables})
-(@pxref{Man pages}).
+(@pxref{Man Pages}).
address@hidden Length limitations
address@hidden Length Limitations
@section Staying below the command line length limit
@cindex command line length limit
@@ -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
@@ -2930,7 +2974,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
@@ -3000,7 +3044,7 @@ aclocal}). You can also use it to maintain your own set
of custom
macros (@pxref{Local Macros}).
At startup, @command{aclocal} scans all the @file{.m4} files it can
-find, looking for macro definitions (@pxref{Macro search path}). Then
+find, looking for macro definitions (@pxref{Macro Search Path}). Then
it scans @file{configure.ac}. Any mention of one of the macros found
in the first step causes that macro, and any macros it in turn
requires, to be put into @file{aclocal.m4}.
@@ -3039,16 +3083,16 @@ called conditionally). @command{autom4te} is expected
to be in the
overridden using the @env{AUTOM4TE} environment variable.
@menu
-* aclocal options:: Options supported by aclocal
-* Macro search path:: How aclocal finds .m4 files
+* aclocal Options:: Options supported by aclocal
+* Macro Search Path:: How aclocal finds .m4 files
* Extending aclocal:: Writing your own aclocal macros
* Local Macros:: Organizing local macros
* Serials:: Serial lines in Autoconf macros
* Future of aclocal:: aclocal's scheduled death
@end menu
address@hidden aclocal options
address@hidden aclocal options
address@hidden aclocal Options
address@hidden aclocal Options
@cindex @command{aclocal}, Options
@cindex Options, @command{aclocal}
@@ -3151,8 +3195,8 @@ way as it is for @command{automake} (@pxref{Invoking
Automake}).
@end table
address@hidden Macro search path
address@hidden Macro search path
address@hidden Macro Search Path
address@hidden Macro Search Path
@cindex Macro search path
@cindex @command{aclocal} search path
@@ -3172,7 +3216,7 @@ configured when @command{automake} itself is built. This
is
@file{@@datadir@@/aclocal/}, which typically
expands to @address@hidden@}/share/aclocal/}. To find the compiled-in
value of @var{acdir}, use the @option{--print-ac-dir} option
-(@pxref{aclocal options}).
+(@pxref{aclocal Options}).
@end table
As an example, suppose that @command{automake-1.6.2} was configured with
@@ -3183,10 +3227,10 @@ As an example, suppose that @command{automake-1.6.2}
was configured with
@item @file{/usr/local/share/aclocal/}
@end enumerate
-As explained in (@pxref{aclocal options}), there are several options that
+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
@@ -3200,10 +3244,10 @@ 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,
+(@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
@samp{aclocal -I /foo -I /bar} results in the following search path:
@enumerate
@@ -3213,7 +3257,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
@@ -3435,7 +3479,7 @@ do not really care about the rebuild rules, you should
define
When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
that @code{m4_include}s any file from @file{m4/} that defines a
required macro. Macros not found locally will still be searched in
-system-wide directories, as explained in @ref{Macro search path}.
+system-wide directories, as explained in @ref{Macro Search Path}.
Custom macros should be distributed for the same reason that
@file{configure.ac} is: so that other people have all the sources of
@@ -3598,8 +3642,8 @@ with serial 1.
@noindent
Because both files have the same serial number, @command{aclocal} uses
-the first it found in its search path order (@pxref{Macro search
-path}). @command{aclocal} therefore ignores
+the first it found in its search path order (@pxref{Macro Search
+Path}). @command{aclocal} therefore ignores
@file{/usr/share/aclocal/thirdparty.m4} and outputs an
@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
@@ -3705,15 +3749,15 @@ Automake ships with several Autoconf macros that you
can use from your
@command{aclocal} in @file{aclocal.m4}.
@menu
-* Public macros:: Macros that you can use.
-* Obsolete macros:: Macros that you should stop using.
-* Private macros:: Macros that you should not use.
+* Public Macros:: Macros that you can use.
+* Obsolete Macros:: Macros that you should stop using.
+* Private Macros:: Macros that you should not use.
@end menu
@c consider generating the following subsections automatically from m4 files.
address@hidden Public macros
address@hidden Public macros
address@hidden Public Macros
address@hidden Public Macros
@table @code
@@ -3870,8 +3914,8 @@ into @code{LIBOBJS}.
@end table
address@hidden Obsolete macros
address@hidden Obsolete macros
address@hidden Obsolete Macros
address@hidden Obsolete Macros
@cindex obsolete macros
@cindex autoupdate
@@ -3945,8 +3989,8 @@ you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS}
instead.
@end table
address@hidden Private macros
address@hidden Private macros
address@hidden Private Macros
address@hidden Private Macros
The following macros are private macros you should not call directly.
They are called by the other public macros when appropriate. Do not
@@ -4101,6 +4145,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
+* Unconfigured 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
@@ -4133,7 +4185,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 Subdirectories with @code{AM_CONDITIONAL}
@cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
@cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
@@ -4174,7 +4227,8 @@ 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 Conditional Subdirectories with @code{AC_SUBST}
address@hidden Subdirectories with AC_SUBST
address@hidden Subdirectories with @code{AC_SUBST}
@cindex @code{SUBDIRS} and @code{AC_SUBST}
@cindex @code{AC_SUBST} and @code{SUBDIRS}
@@ -4208,7 +4262,8 @@ 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
address@hidden Unconfigured Subdirectories
address@hidden Unconfigured Subdirectories
@cindex Subdirectories, configured conditionally
The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
@@ -4252,7 +4307,7 @@ lists all the directories that have been configured.
@end itemize
@end cartouche
-In order to prevent recursion in some non-configured directory you
+In order to prevent recursion in some unconfigured directory you
must therefore ensure that this directory does not appear in
@code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
@code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
@@ -4268,7 +4323,7 @@ configuration where all directories are known to appear in
distribute these directories).
@cindex Subdirectories, not distributed
-In few packages, non-configured directories are not even expected to
+In few packages, unconfigured directories are not even expected to
be distributed. Although these packages do not require the
aforementioned extra arrangements, there is another pitfall. If the
name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
@@ -4325,7 +4380,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
@@ -4468,7 +4524,7 @@ to build programs and libraries.
library builds
* Default _SOURCES:: Default source files
* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
-* Program variables:: Variables used when building a program
+* Program Variables:: Variables used when building a program
* Yacc and Lex:: Yacc and Lex support
* C++ Support:: Compiling C++ sources
* Objective C Support:: Compiling Objective C sources
@@ -4670,7 +4726,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
@@ -4708,7 +4764,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
@@ -4754,7 +4810,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
@@ -4779,7 +4835,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
@@ -5297,7 +5353,13 @@ performed automatically by Autoconf (@pxref{AC_LIBOBJ vs
LIBOBJS, ,
@node Libtool Issues
@subsection Common Issues Related to Libtool's Use
address@hidden @samp{required file `./ltmain.sh' not found}
address@hidden
+* Error 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 Error required file ltmain.sh not found
address@hidden Error: @samp{required file `./ltmain.sh' not found}
@cindex @file{ltmain.sh} not found
@cindex @command{libtoolize}, no longer run by @command{automake}
@cindex @command{libtoolize} and @command{autoreconf}
@@ -5325,6 +5387,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
@@ -5359,7 +5422,7 @@ object `foo.$(OBJEXT)' created both with libtool and
without
@end example
A workaround for this issue is to ensure that these two objects get
-different basenames. As explained in @ref{renamed objects}, this
+different basenames. As explained in @ref{Renamed Objects}, this
happens automatically when per-targets flags are used.
@example
@@ -5583,7 +5646,7 @@ different name for the intermediate object files.
Ordinarily a file
like @file{sample.c} will be compiled to produce @file{sample.o}.
However, if the program's @code{_CFLAGS} variable is set, then the
object file will be named, for instance, @file{maude-sample.o}. (See
-also @ref{renamed objects}.) The use of per-target compilation flags
+also @ref{Renamed Objects}.) The use of per-target compilation flags
with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
from @file{configure.ac}.
@@ -5848,7 +5911,7 @@ be defined by hand (as in the past), however at the time
of writing
autoconf, The Autoconf Manual}.
address@hidden Program variables
address@hidden Program Variables
@section Variables used when building a program
Occasionally it is useful to know which @file{Makefile} variables
@@ -6136,7 +6199,7 @@ Automake includes some support for Unified Parallel C.
Any package including Unified Parallel C code must define the output
variable @code{UPC} in @file{configure.ac}; the simplest way to do
-this is to use the @code{AM_PROG_UPC} macro (@pxref{Public macros}).
+this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
A few additional variables are defined when a Unified Parallel C
source file is seen:
@@ -6701,7 +6764,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}.)
@@ -6733,7 +6796,7 @@ an @command{automake}-generated rule for
@samp{foo$(EXEEXT)}. Without
the @option{no-exeext} option, this use will give a diagnostic.
address@hidden Other objects
address@hidden Other Objects
@chapter Other Derived Objects
Automake can handle derived objects that are not C programs. Sometimes
@@ -6812,7 +6875,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
@@ -6941,7 +7004,7 @@ dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
@node Sources
address@hidden Built sources
address@hidden Built Sources
Because Automake's automatic dependency tracking works as a side-effect
of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
@@ -6999,11 +7062,11 @@ The next section illustrates and discusses the handling
of built sources
on a toy example.
@menu
-* Built sources example:: Several ways to handle built sources.
+* Built Sources Example:: Several ways to handle built sources.
@end menu
address@hidden Built sources example
address@hidden Built sources example
address@hidden Built Sources Example
address@hidden Built Sources Example
Suppose that @file{foo.c} includes @file{bindir.h}, which is
installation-dependent and not distributed: it needs to be built. Here
@@ -7015,7 +7078,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}).
@@ -7056,7 +7119,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}).
@@ -7105,7 +7168,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
@@ -7141,7 +7204,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
@@ -7166,7 +7229,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}
@@ -7186,7 +7249,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.
@@ -7504,7 +7567,7 @@ Currently Automake provides support for Texinfo and man
pages.
@menu
* Texinfo:: Texinfo
-* Man pages:: Man pages
+* Man Pages:: Man pages
@end menu
@@ -7709,8 +7772,8 @@ TEXINFO_TEX = ../doc/texinfo.tex
@end vtable
address@hidden Man pages
address@hidden Man pages
address@hidden Man Pages
address@hidden Man Pages
@cindex @code{_MANS} primary, defined
@cindex @code{MANS} primary, defined
@@ -7801,7 +7864,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
@@ -7813,13 +7877,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.
@@ -7846,7 +7919,7 @@ will install @file{stdio.h} in @samp{$(includedir)} and
@file{types.h}
in @samp{$(includedir)/sys}.
For most file types, Automake will install multiple files at once, while
-avoiding command line length issues (@pxref{Length limitations}). Since
+avoiding command line length issues (@pxref{Length Limitations}). Since
some @command{install} programs will not install the same file twice in
one invocation, you may need to ensure that file lists are unique within
one variable such as @samp{nobase_include_HEADERS} above.
@@ -7857,7 +7930,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
@@ -7890,7 +7964,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
@@ -7906,7 +7981,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
@@ -7939,7 +8015,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}.
@@ -8021,7 +8098,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}
@@ -8080,7 +8166,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_
@@ -8102,7 +8189,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
@@ -8152,7 +8240,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}
@@ -8247,7 +8336,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:
@@ -8302,6 +8392,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
@@ -8310,7 +8408,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,
@@ -8374,12 +8473,13 @@ 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
@@ -8569,6 +8669,7 @@ In case of doubt you may want to require to use GNU
@command{make},
or work around the issue with inference rules to generate the tests.
address@hidden DejaGnu Tests
@section DejaGnu Tests
If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
@@ -8613,6 +8714,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
@@ -8763,13 +8865,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}
@@ -8887,7 +8989,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}
@@ -9244,7 +9346,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
@@ -9350,20 +9469,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
@@ -9390,7 +9497,8 @@ endif
AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
@end example
address@hidden or
address@hidden
+or
@example
AM_CPPFLAGS = -DFEATURE_A
@@ -9400,6 +9508,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}
@@ -9716,10 +9830,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
@@ -9759,7 +9873,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.
@@ -10053,10 +10167,10 @@ lists.
* CVS:: CVS and generated files
* maintainer-mode:: missing and AM_MAINTAINER_MODE
* wildcards:: Why doesn't Automake support wildcards?
-* limitations on file names:: Limitations on source and installed file names
+* Limitations on File Names:: Limitations on source and installed file names
* distcleancheck:: Files left in build directory after distclean
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
-* renamed objects:: Why are object files sometimes renamed?
+* Renamed Objects:: Why are object files sometimes renamed?
* Per-Object Flags:: How to simulate per-object flags?
* Multiple Outputs:: Writing rules for tools with many output files
* Hard-Coded Install Paths:: Installing to Hard-Coded Locations
@@ -10065,7 +10179,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
@@ -10086,7 +10200,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
@@ -10109,7 +10223,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
@@ -10117,7 +10231,7 @@ There are basically two clans amongst maintainers:
those who keep all
distributed files under CVS, including generated files, and those who
keep generated files @emph{out} of CVS.
address@hidden All files in CVS
address@hidden All Files in CVS
@itemize @bullet
@item
@@ -10183,7 +10297,7 @@ tree, @file{Makefile.in} will happen to be newer than
@end itemize
address@hidden Generated files out of CVS
address@hidden Generated Files out of CVS
One way to get CVS and @command{make} working peacefully is to never
store generated files in CVS, i.e., do not CVS-control files that
@@ -10209,7 +10323,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
@@ -10227,7 +10341,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
@@ -10256,7 +10370,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
@@ -10378,8 +10492,8 @@ variables as far Automake is concerned.
You can get warnings about @samp{$(wildcard ...}) constructs using the
@option{-Wportability} flag.
address@hidden limitations on file names
address@hidden Limitations on file names
address@hidden Limitations on File Names
address@hidden Limitations on File Names
@cindex file names, limitations on
Automake attempts to support all kinds of file names, even those that
@@ -10452,8 +10566,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}.
@@ -10585,7 +10699,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.
@@ -10612,7 +10727,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}
@@ -10790,12 +10905,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
@@ -10809,7 +10924,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.
@@ -10825,7 +10940,7 @@ variable), and @code{mumble_LIBADD} exists only as a
per-target
variable. @xref{Program and Library Variables}.
address@hidden renamed objects
address@hidden Renamed Objects
@section Why are object files sometimes renamed?
This happens when per-target compilation flags are used. Object
@@ -10891,7 +11006,7 @@ foo_CFLAGS = -some -flags
@noindent
@file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
compiled with @samp{-some -flags}. (If you wonder about the names of
-these object files, see @ref{renamed objects}.) Note that
+these object files, see @ref{Renamed Objects}.) Note that
@code{foo_CFLAGS} gives the flags to use when compiling all the C
sources of the @emph{program} @code{foo}, it has nothing to do with
@file{foo.c} or @file{foo-foo.o} specifically.
@@ -10930,8 +11045,8 @@ could think about defining the @samp{foo-foo.o: foo.c}
rule yourself.
We recommend against this, because this is error prone. For instance,
if you add such a rule to the first example, it will break the day you
decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
-compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{renamed
-objects}). Also in order to support dependency tracking, the two
+compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
+Objects}). Also in order to support dependency tracking, the two
@file{.o}/@file{.obj} extensions, and all the other flags variables
involved in a compilation, you will end up modifying a copy of the
rule previously output by @command{automake} for this file. If a new
@@ -12114,7 +12229,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 Tool Writers:: 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
@@ -12173,6 +12298,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
@@ -12222,6 +12348,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
@@ -12322,6 +12449,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
@@ -12354,6 +12482,7 @@ powerful, but unfortunately it is not portable enough
for use in
@command{automake}.
@end table
address@hidden Recommendations for Tool Writers
@subsection Recommendations for Tool Writers
We think that every compilation tool ought to be able to generate
@@ -12365,7 +12494,8 @@ 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 Automake's Dependency Tracking
address@hidden Future Directions for Dependencies
address@hidden Future Directions for Dependencies
Currently, only languages and compilers understood by Automake can
have dependency tracking enabled. We would like to see if it is
@@ -12544,7 +12674,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
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- Re: sections without nodes in automake manual?,
Ralf Wildenhues <=