@copying
This manual is for @acronym{GNU} Automake (version @value{VERSION},
-@value{UPDATED}), a program which creates GNU standards-compliant
+@value{UPDATED}), a program that creates GNU standards-compliant
Makefiles from template files.
Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
@cindex Special Automake comment
@cindex Comment, special to Automake
-Automake also allows a form of comment which is @emph{not} copied into
+Automake also allows a form of comment that is @emph{not} copied into
the output; all lines beginning with @samp{##} (leading spaces allowed)
are completely ignored by Automake.
@table @option
@item foreign
-Automake will check for only those things which are absolutely
+Automake will check for only those things that are absolutely
required for proper operations. For instance, whereas GNU standards
dictate the existence of a @file{NEWS} file, it will not be required in
this mode. The name comes from the fact that Automake is intended to be
standard is actually published (which may never happen).
@end table
-For more information on the precise implications of the strictness
-level, see @ref{Gnits}.
+@xref{Gnits}, for more information on the precise implications of the
+strictness level.
-Automake also has a special ``cygnus'' mode which is similar to
+Automake also has a special ``cygnus'' mode that is similar to
strictness but handled differently. This mode is useful for packages
-which are put into a ``Cygnus'' style tree (e.g., the GCC tree). For
-more information on this mode, see @ref{Cygnus}.
+that are put into a ``Cygnus'' style tree (e.g., the GCC tree).
+@xref{Cygnus}, for more information on this mode.
@node Uniform
At @command{make} time, certain variables are used to determine which
objects are to be built. The variable names are made of several pieces
-which are concatenated together.
+that are concatenated together.
-The piece which tells automake what is being built is commonly called
+The piece that tells automake what is being built is commonly called
the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
-list of programs which are to be compiled and linked.
+list of programs that are to be compiled and linked.
@vindex PROGRAMS
@cindex @code{pkglibdir}, defined
@cindex @code{PACKAGE}, directory
A different set of names is used to decide where the built objects
-should be installed. These names are prefixes to the primary which
+should be installed. These names are prefixes to the primary, and they
indicate which standard directory should be used as the installation
directory. The standard directory names are given in the GNU standards
(@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
@cindex @code{EXTRA_}, prepending
For each primary, there is one additional variable named by prepending
@samp{EXTRA_} to the primary name. This variable is used to list
-objects which may or may not be built, depending on what
+objects that may or may not be built, depending on what
@command{configure} decides. This variable is required because Automake
must statically know the entire list of objects that may be built in
order to generate a @file{Makefile.in} that will work in all cases.
@cindex Example, @code{EXTRA_PROGRAMS}
@cindex @command{cpio} example
-For instance, @command{cpio} decides at configure time which programs are
-built. Some of the programs are installed in @code{bindir}, and some
-are installed in @code{sbindir}:
+For instance, @command{cpio} decides at configure time which programs
+should be built. Some of the programs are installed in @code{bindir},
+and some are installed in @code{sbindir}:
@example
EXTRA_PROGRAMS = mt rmt
@vindex MANS
@vindex TEXINFOS
-Some primaries also allow additional prefixes which control other
+Some primaries also allow additional prefixes that control other
aspects of @command{automake}'s behavior. The currently defined prefixes
are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
are explained later (@pxref{Program and Library Variables}).
Sometimes package developers are tempted to set user variables such as
@code{CFLAGS} because it appears to make their job easier. However,
the package itself should never set a user variable, particularly not
-to include switches which are required for proper compilation of the
+to include switches that are required for proper compilation of the
package. Since these variables are documented as being for the
package builder, that person rightfully expects to be able to override
any of these variables at build time.
(@pxref{ANSI}).
@item compile
-This is a wrapper for compilers which don't accept both @option{-c} and
-@option{-o} at the same time. It is only used when absolutely required.
-Such compilers are rare.
+This is a wrapper for compilers that do not accept options @option{-c}
+and @option{-o} at the same time. It is only used when absolutely
+required. Such compilers are rare.
@item config.guess
@itemx config.sub
release.
@item depcomp
-This program understands how to run a compiler so that it will generate
-not only the desired output but also dependency information which is
-then used by the automatic dependency tracking feature.
+This program understands how to run a compiler so that it will
+generate not only the desired output but also dependency information
+that is then used by the automatic dependency tracking feature.
@item elisp-comp
This program is used to byte-compile Emacs Lisp code.
@item install-sh
-This is a replacement for the @command{install} program which works on
+This is a replacement for the @command{install} program that works on
platforms where @command{install} is unavailable or unusable.
@item mdate-sh
a file and prints some date information about it.
@item missing
-This wraps a number of programs which are typically only required by
+This wraps a number of programs that are typically only required by
maintainers. If the program in question doesn't exist,
@command{missing} prints an informative warning and attempts to fix
things so that the build can continue.
@opindex --no-force
Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
@file{configure.ac}. This option causes it to only update those
-@file{Makefile.in}s which are out of date with respect to one of their
+@file{Makefile.in}s that are out of date with respect to one of their
dependents.
@item -o @var{dir}
@item override
user redefinitions of Automake rules or variables
@item portability
-portability issues (e.g., use of Make features which are known not portable)
+portability issues (e.g., use of @command{make} features that are
+known to be not portable)
@item syntax
weird syntax, unused variables, typos
@item unsupported
@acindex AM_INIT_AUTOMAKE
The one real requirement of Automake is that your @file{configure.ac}
-call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
+call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
required for proper Automake operation (@pxref{Macros}).
-Here are the other macros which Automake requires but which are not run
+Here are the other macros that Automake requires but which are not run
by @code{AM_INIT_AUTOMAKE}:
@table @code
This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
@item AM_GNU_GETTEXT
-This macro is required for packages which use GNU gettext
+This macro is required for packages that use GNU gettext
(@pxref{gettext}). It is distributed with gettext. If Automake sees
this macro it ensures that the package meets some of gettext's
requirements.
@cindex Invoking @command{aclocal}
@cindex @command{aclocal}, Invoking
-Automake includes a number of Autoconf macros which can be used in
+Automake includes a number of Autoconf macros that can be used in
your package (@pxref{Macros}); some of them are actually required by
Automake in certain situations. These macros must be defined in your
@file{aclocal.m4}; otherwise they will not be seen by
@emph{Putting} the file that contains the macro definition into
@file{aclocal.m4} is usually done by copying the entire text of this
file, including unused macro definitions as well as both @samp{#} and
-@samp{dnl} comments. If you want to make a comment which will be
+@samp{dnl} comments. If you want to make a comment that will be
completely ignored by @command{aclocal}, use @samp{##} as the comment
leader.
and uses @code{m4_include} instead of copying it into
@file{aclocal.m4}. This makes the package smaller, eases dependency
tracking, and cause the file to be distributed automatically.
-(@xref{Local Macros}, for an example.) Any macro which is found in a
+(@xref{Local Macros}, for an example.) Any macro that is found in a
system-wide directory, or via an absolute search path will be copied.
So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
some relative directory need to be considered outside the package.
@cindex autom4te
While computing @file{aclocal.m4}, @command{aclocal} runs
@command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
-autoconf, The Autoconf Manual}) in order to trace the macros which are
-really used, and omit from @file{aclocal.m4} all macros which are
+autoconf, The Autoconf Manual}) in order to trace the macros that are
+really used, and omit from @file{aclocal.m4} all macros that are
mentioned but otherwise unexpanded (this can happen when a macro is
called conditionally). @command{autom4te} is expected to be in the
@env{PATH}, just as @command{autoconf}. Its location can be
@item --print-ac-dir
@opindex --print-ac-dir
-Prints the name of the directory which @command{aclocal} will search to
+Prints the name of the directory that @command{aclocal} will search to
find third-party @file{.m4} files. When this option is given, normal
processing is suppressed. This option can be used by a package to
determine where to install a macro file.
@file{/usr/local/share/aclocal}. The only way to force
@file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
always call @samp{aclocal -I /usr/local/share/aclocal}. This is
-inconvenient. With @file{dirlist}, one may create the file
-@file{/usr/share/aclocal/dirlist} which contains only the single line
+inconvenient. With @file{dirlist}, one may create a file
+@file{/usr/share/aclocal/dirlist} containing only the single line
@example
/usr/local/share/aclocal
The @command{aclocal} program doesn't have any built-in knowledge of any
macros, so it is easy to extend it with your own macros.
-This can be used by libraries which want to supply their own Autoconf
+This can be used by libraries that want to supply their own Autoconf
macros for use by other programs. For instance the @command{gettext}
-library supplies a macro @code{AM_GNU_GETTEXT} which should be used by
+library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
any package using @command{gettext}. When the library is installed, it
installs this macro so that @command{aclocal} will find it.
for this temporary inconvenience. The reason we have to be stricter
is that a future implementation of @command{aclocal} (@pxref{Future of
aclocal}) will have to temporary include all these third party
-@file{.m4} files, maybe several times, even those which are not
-actually needed. Doing so should alleviate many problem of the
+@file{.m4} files, maybe several times, including even files that are
+not actually needed. Doing so should alleviate many problems of the
current implementation, however it requires a stricter style from the
macro authors. Hopefully it is easy to revise the existing macros.
For instance
flooded by mails.
Another situation where @command{aclocal} is commonly used is to
-manage macros which are used locally by the package, @ref{Local
+manage macros that are used locally by the package, @ref{Local
Macros}.
@node Local Macros
macros that your package may use. Many libraries install their own
macro in the system-wide @command{aclocal} directory (@pxref{Extending
aclocal}). For instance Guile ships with a file called
-@file{guile.m4} that contains the macro @code{GUILE_FLAGS} which can
+@file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
be used to define setup compiler and linker flags appropriate for
using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
cause @command{aclocal} to copy @file{guile.m4} into
@file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
-it will not be distributed. Technically, that means a user which
+it will not be distributed. Technically, that means a user who
needs to rebuild @file{aclocal.m4} will have to install Guile first.
This is probably OK, if Guile already is a requirement to build the
package. However, if Guile is only an optional feature, or if your
@vindex AUTOMAKE_OPTIONS
This macro has two forms, the first of which is preferred.
In this form, @code{AM_INIT_AUTOMAKE} is called with a
-single argument: a space-separated list of Automake options which should
+single argument: a space-separated list of Automake options that should
be applied to every @file{Makefile.am} in the tree. The effect is as if
each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
needed; there should be no need to invoke it manually.
@item AM_PROG_INSTALL_STRIP
-This is used to find a version of @code{install} which can be used to
+This is used to find a version of @code{install} that can be used to
strip a program at installation time. This macro is automatically
included when required.
both locally and in all specified subdirectories. Note that the
directories listed in @code{SUBDIRS} are not required to contain
@file{Makefile.am}s; only @file{Makefile}s (after configuration).
-This allows inclusion of libraries from packages which do not use
+This allows inclusion of libraries from packages that do not use
Automake (such as @code{gettext}; see also @ref{Third-Party
Makefiles}).
subdirectories. Automake can be used to construct packages of
arbitrary depth this way.
-By default, Automake generates @file{Makefiles} which work depth-first
+By default, Automake generates @file{Makefiles} that work depth-first
in postfix order: the subdirectories are built before the current
directory. However, it is possible to change this ordering. You can
do this by putting @samp{.} into @code{SUBDIRS}. For instance,
conditionally so that some directory will be omitted from the build.
@code{DIST_SUBDIRS} is used in rules that need to recurse in all
-directories, even those which have been conditionally left out of the
+directories, even those that have been conditionally left out of the
build. Recall our example where we may not want to build subdirectory
@file{opt/}, but yet we want to distribute it? This is where
@code{DIST_SUBDIRS} come into play: @samp{opt} may not appear in
@samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
= $(SUBDIRS)}.
-Of course, directories which are omitted from @code{DIST_SUBDIRS} will
+Of course, directories that are omitted from @code{DIST_SUBDIRS} will
not be distributed unless you make other arrangements for this to
happen (for instance always running @samp{make dist} in a
configuration where all directories are known to appear in
In this simple case, the resulting @file{Makefile.in} will contain code
to generate a program named @code{hello}.
-Associated with each program are several assisting variables which are
+Associated with each program are several assisting variables that are
named after the program. These variables are all optional, and have
reasonable defaults. Each variable, its use, and default is spelled out
below; we use the ``hello'' example throughout.
@cindex @code{_DEPENDENCIES}, defined
@vindex maude_DEPENDENCIES
It is also occasionally useful to have a program depend on some other
-target which is not actually part of that program. This can be done
+target that is not actually part of that program. This can be done
using the @code{@var{prog}_DEPENDENCIES} variable. Each program depends
on the contents of such a variable, but no further interpretation is
done.
Automake must know all the source files that could possibly go into a
program, even if not all the files are built in every circumstance. Any
-files which are only conditionally built should be listed in the
+files that are only conditionally built should be listed in the
appropriate @code{EXTRA_} variable. For instance, if
@file{hello-linux.c} or @file{hello-generic.c} were conditionally included
in @code{hello}, the @file{Makefile.am} would contain:
@vindex noinst_LTLIBRARIES
@vindex check_LTLIBRARIES
-Sometimes you want to build libtool libraries which should not be
+Sometimes you want to build libtool libraries that should not be
installed. These are called @dfn{libtool convenience libraries} and
are typically used to encapsulate many sublibraries, later gathered
into one big installed library.
when the @code{prog_CFLAGS} is defined, it is used instead of
@code{AM_CFLAGS}. However as a side effect it will cause
@file{prog.c} and @file{foo.c} to be compiled as
-@file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)} which solves
+@file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
the issue.
@node Program and Library Variables
@section Program and Library Variables
-Associated with each program are a collection of variables which can be
+Associated with each program are a collection of variables that can be
used to modify how that program is built. There is a similar list of
such variables for each library. The canonical name of the program (or
library) is used as a base for naming these variables.
@vtable @code
@item maude_SOURCES
-This variable, if it exists, lists all the source files which are
+This variable, if it exists, lists all the source files that are
compiled to build the program. These files are added to the
distribution by default. When building the program, Automake will cause
each source file to be compiled to a single @file{.o} file (or
being put into the library. You can override this by setting the
@code{_AR} variable. This is usually used with C++; some C++
compilers require a special invocation in order to instantiate all the
-templates which should go into a library. For instance, the SGI C++
+templates that should go into a library. For instance, the SGI C++
compiler likes this variable set like so:
@example
libmaude_a_AR = $(CXX) -ar -o
@item maude_DEPENDENCIES
It is also occasionally useful to have a program depend on some other
-target which is not actually part of that program. This can be done
+target that is not actually part of that program. This can be done
using the @code{_DEPENDENCIES} variable. Each program depends on the
contents of such a variable, but no further interpretation is done.
linker is chosen according to the languages used by the program. For
instance, a program that includes C++ source code would use the C++
compiler to link. The @code{_LINK} variable must hold the name of a
-command which can be passed all the @file{.o} file names as arguments.
+command that can be passed all the @file{.o} file names as arguments.
Note that the name of the underlying program is @emph{not} passed to
@code{_LINK}; typically one uses @samp{$@@}:
@item maude_SHORTNAME
On some platforms the allowable file names are very short. In order to
support these systems and per-target compilation flags at the same
-time, Automake allows you to set a ``short name'' which will influence
+time, Automake allows you to set a ``short name'' that will influence
how intermediate object files are named. For instance, in the following
example,
@vindex LDFLAGS
@vindex LIBS
-There are some additional variables which Automake itself defines:
+There are some additional variables that Automake defines on its own:
@vtable @code
@item AM_CPPFLAGS
-The contents of this variable are passed to every compilation which invokes
+The contents of this variable are passed to every compilation that invokes
the C preprocessor; it is a list of arguments to the preprocessor. For
instance, @option{-I} and @option{-D} options should be listed here.
@code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
@item AM_CFLAGS
-This is the variable which the @file{Makefile.am} author can use to pass
+This is the variable the @file{Makefile.am} author can use to pass
in additional C compiler flags. It is more fully documented elsewhere.
In some situations, this is not used, in preference to the
per-executable (or per-library) @code{_CFLAGS}.
file name is appended to form the complete command line.
@item AM_LDFLAGS
-This is the variable which the @file{Makefile.am} author can use to pass
+This is the variable the @file{Makefile.am} author can use to pass
in additional linker flags. In some situations, this is not used, in
preference to the per-executable (or per-library) @code{_LDFLAGS}.
@node Other objects
@chapter Other Derived Objects
-Automake can handle derived objects which are not C programs. Sometimes
+Automake can handle derived objects that are not C programs. Sometimes
the support for actually building such objects must be explicitly
supplied, but Automake will still automatically handle installation and
distribution.
@cindex Primary variable, @code{SCRIPTS}
@vindex _SCRIPTS
-It is possible to define and install programs which are scripts. Such
+It is possible to define and install programs that are scripts. Such
programs are listed using the @code{SCRIPTS} primary name. Automake
doesn't define any dependencies for scripts; the @file{Makefile.am}
should include the appropriate rules.
@end example
You don't have to list @emph{all} the dependencies of @file{foo.o}
-explicitly, only those which might need to be built. If a dependency
+explicitly, only those that might need to be built. If a dependency
already exists, it will not hinder the first compilation and will be
recorded by the normal dependency tracking code. (Note that after
this first compilation the dependency tracking code will also have
@file{.class} file names cannot be predicted without parsing the
@file{.java} file.
-There are a few variables which are used when compiling Java sources:
+There are a few variables that are used when compiling Java sources:
@vtable @code
@item JAVAC
@code{javac}. It defaults to @samp{$(top_builddir)}.
@item CLASSPATH_ENV
-This variable is an @code{sh} expression which is used to set the
+This variable is an @code{sh} expression that is used to set the
@env{CLASSPATH} environment variable on the @code{javac} command line.
(In the future we will probably handle class path setting differently.)
@end vtable
@code{noinst_PYTHON} will not be compiled. Python source files are
included in the distribution by default.
-Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} which
+Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} that
will determine some Python-related directory variables (see below). If
you have called @code{AM_PATH_PYTHON} from @file{configure.ac}, then you
may use the following variables to list you Python source files in your
Search a Python interpreter on the system. This macro takes three
optional arguments. The first argument, if present, is the minimum
version of Python required for this package: @code{AM_PATH_PYTHON}
-will skip any Python interpreter which is older than @var{VERSION}.
+will skip any Python interpreter that is older than @var{VERSION}.
If an interpreter is found and satisfies @var{VERSION}, then
@var{ACTION-IF-FOUND} is run. Otherwise, @var{ACTION-IF-NOT-FOUND} is
run.
@item PYTHON_PREFIX
The string @samp{$@{prefix@}}. This term may be used in future work
-which needs the contents of Python's @samp{sys.prefix}, but general
+that needs the contents of Python's @samp{sys.prefix}, but general
consensus is to always use the value from configure.
@item PYTHON_EXEC_PREFIX
The string @samp{$@{exec_prefix@}}. This term may be used in future work
-which needs the contents of Python's @samp{sys.exec_prefix}, but general
+that needs the contents of Python's @samp{sys.exec_prefix}, but general
consensus is to always use the value from configure.
@item PYTHON_PLATFORM
standard Python install tree.
@item pkgpythondir
-This is is the directory under @code{pythondir} which is named after the
+This is the directory under @code{pythondir} that is named after the
package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
as a convenience.
should be installed.
@item pkgpyexecdir
-This is a convenience variable which is defined as
+This is a convenience variable that is defined as
@samp{$(pyexecdir)/$(PACKAGE)}.
@end vtable
Sometimes it is useful to avoid the basename step at install time. For
instance, you might have a number of header files in subdirectories of
-the source tree which are laid out precisely how you want to install
+the source tree that are laid out precisely how you want to install
them. In this situation you can use the @code{nobase_} prefix to
suppress the base name step. For example:
@section 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 which
+rules, in case the installer is installing on multiple machines that
share directory structure---these targets allow the machine-independent
parts to be installed only once. @code{install-exec} installs
platform-dependent files, and @code{install-data} installs
@end example
As the GNU Standards aren't always explicit as to which files should
-be removed by which rule, we've adopted a heuristic which we believe
+be removed by which rule, we've adopted a heuristic that we believe
was first formulated by Fran@,{c}ois Pinard:
@itemize @bullet
For the most part, the files to distribute are automatically found by
Automake: all source files are automatically included in a distribution,
as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
-has a built-in list of commonly used files which are automatically
+has a built-in list of commonly used files that are automatically
included if they are found in the current directory (either physically,
or as the target of a @file{Makefile.am} rule). This list is printed by
-@samp{automake --help}. Also, files which are read by @command{configure}
+@samp{automake --help}. Also, files that are read by @command{configure}
(i.e. the source files corresponding to the files specified in various
Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
automatically distributed. Files included in @file{Makefile.am}s (using
distributed.
@vindex EXTRA_DIST
-Still, sometimes there are files which must be distributed, but which
+Still, sometimes there are files that must be distributed, but which
are not covered in the automatic rules. These files should be listed in
the @code{EXTRA_DIST} variable. You can mention files from
subdirectories in @code{EXTRA_DIST}.
@vindex dist_
@vindex nodist_
Sometimes you need tighter control over what does @emph{not} go into the
-distribution; for instance you might have source files which are
-generated and which you do not want to distribute. In this case
+distribution; for instance you might have source files that are
+generated and that you do not want to distribute. In this case
Automake gives fine-grained control using the @code{dist} and
@code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
prefixed with @code{dist_} to add the listed files to the distribution.
@vindex distuninstallcheck_listfiles
@trindex distcheck
-Automake also generates a @code{distcheck} rule which can be of help
+Automake also generates a @code{distcheck} rule that can be of help
to ensure that a given distribution will actually work.
@code{distcheck} makes a distribution, then tries to do a @code{VPATH}
build, run the test suite, and finally make another tarfile to ensure the
@@:
@end example
-If you want @code{distcleancheck} to ignore built files which have not
+If you want @code{distcleancheck} to ignore built files that have not
been cleaned because they are also part of the distribution, add the
following definition instead:
If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
@code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
-assumed. The variable @code{DEJATOOL} is a list of names which are
+assumed. The variable @code{DEJATOOL} is a list of names that are
passed, one at a time, as the @option{--tool} argument to
@command{runtest} invocations; it defaults to the name of the package.
@option{-I} to tell it where to find @file{.m4} files. Since
sometimes @command{make} will automatically run @command{aclocal}, you
need a way to specify these arguments. You can do this by defining
-@code{ACLOCAL_AMFLAGS}; this holds arguments which are passed verbatim
+@code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
to @command{aclocal}. This variable is only useful in the top-level
@file{Makefile.am}.
@item @option{nostdinc}
@cindex Option, @option{nostdinc}
@opindex nostdinc
-This option can be used to disable the standard @option{-I} options which
+This option can be used to disable the standard @option{-I} options that
are ordinarily automatically provided by Automake.
@item @option{no-texinfo.tex}
@option{tar-pax} selects the new pax interchange format defined by POSIX
1003.1-2001. It does not limit the length of file names. However,
this format is very young and should probably be restricted to
-packages which target only very modern platforms. There are moves to
+packages that target only very modern platforms. There are moves to
change the pax format in an upward-compatible way, so this option may
refer to a more recent version in the future.
variables like @code{nodist_noinst_HEADERS} or
@code{nodist_@var{prog}_SOURCES} or they will be ignored.
-At the topmost directory of a multi-directory package, a @code{tags}
-rule will be output which, when run, will generate a @file{TAGS} file
-that includes by reference all @file{TAGS} files from subdirectories.
+A @code{tags} rule will be output at the topmost directory of a
+multi-directory package. When run from this topmost directory,
+@samp{make tags} will generate a @file{TAGS} file that includes by
+reference all @file{TAGS} files from subdirectories.
The @code{tags} rule will also be generated if the variable
@code{ETAGS_ARGS} is defined. This variable is intended for use in
-directories which contain taggable source that @command{etags} does
+directories that contain taggable source that @command{etags} does
not understand. The user can use the @code{ETAGSFLAGS} to pass
additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
available for use in @file{Makefile.am}.
are added directly to the dependencies for the @code{tags} rule.
@vindex TAGS_DEPENDENCIES
-Automake also generates a @code{ctags} rule which can be used to
+Automake also generates a @code{ctags} rule that can be used to
build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
is the name of the program to invoke (by default @command{ctags});
@code{CTAGSFLAGS} can be used by the user to pass additional flags,
and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
-Automake will also generate an @code{ID} rule which will run
+Automake will also generate an @code{ID} rule that will run
@command{mkid} on the source. This is only supported on a
directory-by-directory basis.
@trindex id
@uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
The @code{GTAGS} rule runs Global Tags and puts the
result in the top build directory. The variable @code{GTAGS_ARGS}
-holds arguments which are passed to @command{gtags}.
+holds arguments that are passed to @command{gtags}.
@vindex GTAGS_ARGS
It is sometimes useful to introduce a new implicit rule to handle a file
type that Automake does not know about.
-For instance, suppose you had a compiler which could compile @file{.foo}
+For instance, suppose you had a compiler that could compile @file{.foo}
files to @file{.o} files. You would simply define an suffix rule for
your language:
@section Support for Multilibs
Automake has support for an obscure feature called multilibs. A
-@dfn{multilib} is a library which is built for multiple different ABIs
+@dfn{multilib} is a library that is built for multiple different ABIs
at a single time; each time the library is built with a different target
flag combination. This is only useful when the library is intended to
be cross-compiled, and it is almost exclusively used for compiler
@cindex Including @file{Makefile} fragment
@cindex @file{Makefile} fragment, including
-Automake supports an @code{include} directive which can be used to
+Automake supports an @code{include} directive that can be used to
include other @file{Makefile} fragments when @command{automake} is run.
Note that these fragments are read and interpreted by @command{automake},
not by @command{make}. As with conditionals, @command{make} has no idea that
@table @code
@item include $(srcdir)/file
-Include a fragment which is found relative to the current source
+Include a fragment that is found relative to the current source
directory.
@item include $(top_srcdir)/file
-Include a fragment which is found relative to the top source directory.
+Include a fragment that is found relative to the top source directory.
@end table
Note that if a fragment is included inside a conditional, then the
The conditional name, @var{conditional}, should be a simple string
starting with a letter and containing only letters, digits, and
underscores. It must be different from @samp{TRUE} and @samp{FALSE}
-which are reserved by Automake.
+that are reserved by Automake.
The shell @var{condition} (suitable for use in a shell @code{if}
statement) is evaluated when @command{configure} is run. Note that you
@cindex Example conditional @option{--enable-debug}
@cindex Conditional example, @option{--enable-debug}
-Conditionals typically depend upon options which the user provides to
+Conditionals typically depend upon options that the user provides to
the @command{configure} script. Here is an example of how to write a
-conditional which is true if the user uses the @option{--enable-debug}
+conditional that is true if the user uses the @option{--enable-debug}
option.
@example
Conditionals may be nested to any depth. You may specify an argument to
@code{else} in which case it must be the negation of the condition used
for the current @code{if}. Similarly you may specify the condition
-which is closed by an @code{end}:
+that is closed by an @code{end}:
@example
if DEBUG
The variables @samp{$(top_distdir)} and @samp{$(distdir)}
(@pxref{Dist}) 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 which is being recursed into, so they
+been adjusted for the directory that is being recursed into, so they
are ready to use.
@item install
implement all these targets. That way they can be added to
@code{SUBDIRS} in Automake packages.
-Directories which are only listed in @code{DIST_SUBDIRS} but not in
+Directories that are only listed in @code{DIST_SUBDIRS} but not in
@code{SUBDIRS} need only the @code{distclean},
@code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
Subdirectories}).
The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
not Automake's version. If a bug fix release is made, for instance
Automake 1.6.1, the API version will remain 1.6. This means that a
-package which work with Automake 1.6 should also work with 1.6.1; after
+package that works with Automake 1.6 should also work with 1.6.1; after
all, this is what people expect from bug fix releases.
If your package relies on a feature or a bug fix introduced in
@samp{cvs import -d} operations.
When you check out a file using @samp{cvs checkout} its timestamp is
-set to that of the revision which is being checked out.
+set to that of the revision that is being checked out.
However, during @command{cvs update}, files will have the date of the
update, not the original timestamp of this revision. This is meant to
@subsubheading 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 which
+store generated files in CVS, i.e., do not CVS-control files that
are @file{Makefile} targets (also called @emph{derived} files).
This way developers are not annoyed by changes to generated files. It
@cindex third-party files and CVS
Another class of files not discussed here (because they do not cause
-timestamp issues) are files which are shipped with a package, but
+timestamp issues) are files that are shipped with a package, but
maintained elsewhere. For instance tools like @command{gettextize}
and @command{autopoint} (from Gettext) or @command{libtoolize} (from
Libtool), will install or update files in your package.
However, if for some reason a rebuild rule is triggered and involves a
missing tool, @command{missing} will notice it and warn the user.
Besides the warning, when a tool is missing, @command{missing} will
-attempt to fix timestamps in a way which allow the build to continue.
+attempt to fix timestamps in a way that allows the build to continue.
For instance @command{missing} will touch @file{configure} if
@command{autoconf} is not installed. When all distributed files are
kept under CVS, this feature of @command{missing} allows user
@file{configure.ac}, and run @samp{./configure && make}, then
@command{make} will *never* attempt to rebuilt @file{configure},
@file{Makefile.in}s, Lex or Yacc outputs, etc. I.e., this disables
-build rules for files which are usually distributed and that users
+build rules for files that are usually distributed and that users
should normally not have to update.
If you run @samp{./configure --enable-maintainer-mode}, then these
@item
Using wildcards makes easy to distribute files by mistake. For
instance some code a developer is experimenting with (a test case,
-say) but which should not be part of the distribution.
+say) but that should not be part of the distribution.
@item
Using wildcards it's easy to omit some files by mistake. For
an @emph{execution} of @file{foo$(EXEEXT)}.
Another context where such errors are common is when distributed files
-are built by tools which are built by the package. The pattern is similar:
+are built by tools that are built by the package. The pattern is
+similar:
@example
distributed-file: built-tools distributed-sources
devised many ways to cope with the limitation of previous
@command{aclocal} versions, notably using handwritten
@code{m4_include}s: @command{aclocal} must make sure not to redefine a
-rule which is already included by such statement.
+rule that is already included by such statement.
Automake also has seen its guts rewritten. Although this rewriting
took a lot of efforts, it is only apparent to the users in that some
make Manual})
This version worked by precomputing dependencies ahead of time. For
-each source file, it had a special @file{.P} file which held the
+each source file, it had a special @file{.P} file that held the
dependencies. There was a rule to generate a @file{.P} file by
invoking the compiler appropriately. All such @file{.P} files were
included by the @file{Makefile}, thus implicitly becoming dependencies
doubled--the compiler had to be run twice per source file.
@item
@samp{make dist} re-ran @command{automake} to generate a
-@file{Makefile} which did not have automatic dependency tracking (and
-which was thus portable to any version of @command{make}). In order to
+@file{Makefile} that did not have automatic dependency tracking (and
+that was thus portable to any version of @command{make}). In order to
do this portably, Automake had to scan the dependency files and remove
-any reference which was to a source file not in the distribution.
+any reference that was to a source file not in the distribution.
This process was error-prone. Also, if @samp{make dist} was run in an
environment where some object file had a dependency on a source file
-which was only conditionally created, Automake would generate a
-@file{Makefile} which referred to a file which might not appear in the
+that was only conditionally created, Automake would generate a
+@file{Makefile} that referred to a file that might not appear in the
end user's build. A special, hacky mechanism was required to work
around this.
@end itemize
avoided the performance penalty associated with scanning each file
twice. It also let us avoid the other problems associated with the
first, eager, implementation. For instance, dependencies would never
-be generated for a source file which was not compilable on a given
+be generated for a source file that was not compilable on a given
architecture (because it in fact would never be compiled).
@unnumberedsubsubsec Bugs
of compilation.
In the end we found that most modern make implementations support some
-form of include directive. Also, we wrote a wrapper script which let
+form of include directive. Also, we wrote a wrapper script that let
us abstract away differences between dependency tracking methods for
compilers. For instance, some compilers cannot generate dependencies
as a side effect of compilation. In this case we simply have the
script run the compiler twice. Currently our wrapper script
(@command{depcomp}) knows about twelve different compilers (including
-a "compiler" which simply invokes @command{makedepend} and then the
+a "compiler" that simply invokes @command{makedepend} and then the
real compiler, which is assumed to be a standard Unix-like C compiler
with no way to do dependency tracking).