* Miscellaneous:: Miscellaneous rules
* Include:: Including extra files in an Automake template.
* Conditionals:: Conditionals
-* Gnits:: The effect of @code{--gnu} and @code{--gnits}
-* Cygnus:: The effect of @code{--cygnus}
+* Gnits:: The effect of @option{--gnu} and @option{--gnits}
+* 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
Automake is a tool for automatically generating @file{Makefile.in}s from
files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
-series of @code{make} variable definitions@footnote{These variables are
+series of @command{make} variable definitions@footnote{These variables are
also called @dfn{make macros} in Make terminology, however in this
manual we reserve the term @dfn{macro} for Autoconf's macros.}, with
rules being thrown in occasionally. The generated @file{Makefile.in}s
@cindex Automake requirements
@cindex Requirements, Automake
-Automake requires @code{perl} in order to generate the
+Automake requires @command{perl} in order to generate the
@file{Makefile.in}s. However, the distributions created by Automake are
-fully GNU standards-compliant, and do not require @code{perl} in order
+fully GNU standards-compliant, and do not require @command{perl} in order
to be built.
@cindex Bugs, reporting
Automake works by reading a @file{Makefile.am} and generating a
@file{Makefile.in}. Certain variables and rules defined in the
@file{Makefile.am} instruct Automake to generate more specialized code;
-for instance, a @samp{bin_PROGRAMS} variable definition will cause rules
+for instance, a @code{bin_PROGRAMS} variable definition will cause rules
for compiling and linking programs to be generated.
@cindex Non-standard targets
A rule defined in @file{Makefile.am} generally overrides any such
rule of a similar name that would be automatically generated by
-@code{automake}. Although this is a supported feature, it is generally
+@command{automake}. Although this is a supported feature, it is generally
best to avoid making use of it, as sometimes the generated rules are
very particular.
@cindex Overriding make variables
Similarly, a variable defined in @file{Makefile.am} or
-@code{AC_SUBST}'ed from @file{configure.ac} will override any
-definition of the variable that @code{automake} would ordinarily
+@code{AC_SUBST}ed from @file{configure.ac} will override any
+definition of the variable that @command{automake} would ordinarily
create. This feature is more often useful than the ability to
override a rule. Be warned that many of the variables generated by
-@code{automake} are considered to be for internal use only, and their
+@command{automake} are considered to be for internal use only, and their
names might change in future releases.
@cindex Recursive operation of Automake
not want to use all the GNU conventions.
@cindex Strictness, defined
-@cindex Strictness, @code{foreign}
-@cindex @code{foreign} strictness
-@cindex Strictness, @code{gnu}
-@cindex @code{gnu} strictness
-@cindex Strictness, @code{gnits}
-@cindex @code{gnits} strictness
+@cindex Strictness, @option{foreign}
+@cindex @option{foreign} strictness
+@cindex Strictness, @option{gnu}
+@cindex @option{gnu} strictness
+@cindex Strictness, @option{gnits}
+@cindex @option{gnits} strictness
To this end, Automake supports three levels of @dfn{strictness}---the
strictness indicating how stringently Automake should check standards
The valid strictness levels are:
-@table @samp
+@table @option
@item foreign
Automake will check for only those things which are absolutely
required for proper operations. For instance, whereas GNU standards
Automake variables generally follow a @dfn{uniform naming scheme} that
makes it easy to decide how programs (and other derived objects) are
built, and how they are installed. This scheme also supports
-@code{configure} time determination of what should be built.
+@command{configure} time determination of what should be built.
@cindex @code{_PROGRAMS} primary variable
@cindex @code{PROGRAMS} primary variable
@cindex Primary variable, defined
@vindex _PROGRAMS
-At @code{make} time, certain variables are used to determine which
+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.
Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
versions, but with @samp{$(PACKAGE)} appended. For instance,
-@code{pkglibdir} is defined as @code{$(libdir)/$(PACKAGE)}.
+@code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
@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
-@code{configure} decides. This variable is required because Automake
+@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, @code{cpio} decides at configure time which programs are
+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}:
@end example
Defining a primary without a prefix as a variable, e.g.,
-@code{PROGRAMS}, is an error.
+@samp{PROGRAMS}, is an error.
Note that the common @samp{dir} suffix is left off when constructing the
variable names; thus one writes @samp{bin_PROGRAMS} and not
directory. To this end, Automake allows you to extend the list of
possible installation directories. A given prefix (e.g. @samp{zar})
is valid if a variable of the same name with @samp{dir} appended is
-defined (e.g. @code{zardir}).
+defined (e.g. @samp{zardir}).
@cindex HTML installation, example
html_DATA = automake.html
@end example
-@cindex @code{noinst_} primary prefix, definition
+@cindex @samp{noinst_} primary prefix, definition
@vindex noinst_
-The special prefix @samp{noinst} indicates that the objects in question
+The special prefix @samp{noinst_} indicates that the objects in question
should be built but not installed at all. This is usually used for
objects required to build the rest of your package, for instance static
libraries (@pxref{A Library}), or helper scripts.
-@cindex @code{check_} primary prefix, definition
+@cindex @samp{check_} primary prefix, definition
@vindex check_
-The special prefix @samp{check} indicates that the objects in question
-should not be built until the @code{make check} command is run. Those
+The special prefix @samp{check_} indicates that the objects in question
+should not be built until the @samp{make check} command is run. Those
objects are not installed either.
The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
@vindex TEXINFOS
Some primaries also allow additional prefixes which control other
-aspects of @code{automake}'s behavior. The currently defined prefixes
+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}).
strudel (@@), and the underscore are turned into underscores when making
variable references.
-For example, if your program is named @code{sniff-glue}, the derived
-variable name would be @code{sniff_glue_SOURCES}, not
-@code{sniff-glue_SOURCES}. Similarly the sources for a library named
-@code{libmumble++.a} should be listed in the
-@code{libmumble___a_SOURCES} variable.
+For example, if your program is named @file{sniff-glue}, the derived
+variable name would be @samp{sniff_glue_SOURCES}, not
+@samp{sniff-glue_SOURCES}. Similarly the sources for a library named
+@file{libmumble++.a} should be listed in the
+@samp{libmumble___a_SOURCES} variable.
The strudel is an addition, to make the use of Autoconf substitutions in
variable names less obfuscating.
@cindex variables, reserved for the user
@cindex user variables
-Some @code{Makefile} variables are reserved by the GNU Coding Standards
+Some @file{Makefile} variables are reserved by the GNU Coding Standards
for the use of the ``user''---the person building the package. For
instance, @code{CFLAGS} is one such variable.
(@pxref{ANSI}).
@item compile
-This is a wrapper for compilers which don't accept both @samp{-c} and
-@samp{-o} at the same time. It is only used when absolutely required.
+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.
@item config.guess
This program is used to byte-compile Emacs Lisp code.
@item install-sh
-This is a replacement for the @code{install} program which works on
-platforms where @code{install} is unavailable or unusable.
+This is a replacement for the @command{install} program which works on
+platforms where @command{install} is unavailable or unusable.
@item mdate-sh
This script is used to generate a @file{version.texi} file. It examines
@item missing
This wraps a number of programs which are typically only required by
-maintainers. If the program in question doesn't exist, @code{missing}
-prints an informative warning and attempts to fix things so that the
-build can continue.
+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.
@item mkinstalldirs
-This script used to be a wrapper around @code{mkdir -p}, which is not
-portable. Now we use prefer to use @code{install-sh -d} when configure
-finds that @code{mkdir -p} does not work, this makes one less script to
+This script used to be a wrapper around @samp{mkdir -p}, which is not
+portable. Now we use prefer to use @samp{install-sh -d} when configure
+finds that @samp{mkdir -p} does not work, this makes one less script to
distribute.
-For backward compatibility @code{mkinstalldirs} is still used and
-distributed when @code{automake} finds it in a package. But it is no
+For backward compatibility @file{mkinstalldirs} is still used and
+distributed when @command{automake} finds it in a package. But it is no
longer installed automatically, and it should be safe to remove it.
@item py-compile
This is used to byte-compile Python scripts.
@item texinfo.tex
-Not a program, this file is required for @code{make dvi}, @code{make ps}
-and @code{make pdf} to work when Texinfo sources are in the package.
+Not a program, this file is required for @samp{make dvi}, @samp{make ps}
+and @samp{make pdf} to work when Texinfo sources are in the package.
@item ylwrap
-This program wraps @code{lex} and @code{yacc} and ensures that, for
-instance, multiple @code{yacc} instances can be invoked in a single
-directory in parallel.
+This program wraps @command{lex} and @command{yacc} and ensures that,
+for instance, multiple @command{yacc} instances can be invoked in a
+single directory in parallel.
@end table
@cindex @code{AM_INIT_AUTOMAKE}, example use
The first step is to update your @file{configure.ac} to include the
-commands that @code{automake} needs. The way to do this is to add an
+commands that @command{automake} needs. The way to do this is to add an
@code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
@example
@cindex @file{acinclude.m4}, defined
Now you must regenerate @file{configure}. But to do that, you'll need
-to tell @code{autoconf} how to find the new macro you've used. The
-easiest way to do this is to use the @code{aclocal} program to generate
-your @file{aclocal.m4} for you. But wait@dots{} maybe you already have an
-@file{aclocal.m4}, because you had to write some hairy macros for your
-program. The @code{aclocal} program lets you put your own macros into
-@file{acinclude.m4}, so simply rename and then run:
+to tell @command{autoconf} how to find the new macro you've used. The
+easiest way to do this is to use the @command{aclocal} program to
+generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
+already have an @file{aclocal.m4}, because you had to write some hairy
+macros for your program. The @command{aclocal} program lets you put
+your own macros into @file{acinclude.m4}, so simply rename and then
+run:
@example
mv aclocal.m4 acinclude.m4
info_TEXINFOS = zardoz.texi
@end example
-Now you can run @code{automake --add-missing} to generate your
+Now you can run @samp{automake --add-missing} to generate your
@file{Makefile.in} and grab any auxiliary files you might need, and
you're done!
As you can see, all the work here is really done in subdirectories.
The @file{po} and @file{intl} directories are automatically generated
-using @code{gettextize}; they will not be discussed here.
+using @command{gettextize}; they will not be discussed here.
@cindex Texinfo file handling example
@cindex Example, handling Texinfo files
EXTRA_DIST = hello.in testdata
@end example
-The script @file{hello} is generated by @code{configure}, and is the
-only test case. @code{make check} will run this test.
+The script @file{hello} is generated by @command{configure}, and is the
+only test case. @samp{make check} will run this test.
@cindex @code{INCLUDES}, example usage
@vindex INCLUDES
Note that there is no @code{true_SOURCES} definition. Automake will
implicitly assume that there is a source file named @file{true.c}, and
define rules to compile @file{true.o} and link @file{true}. The
-@code{true.o: true.c} rule supplied by the above @file{Makefile.am},
+@samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
will override the Automake generated rule to build @file{true.o}.
@code{false_SOURCES} is defined to be empty---that way no implicit value
@code{false_LDADD}.
The above rules won't work if your compiler doesn't accept both
-@samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
-bogus dependency (to avoid problems with a parallel @code{make}):
+@option{-c} and @option{-o}. The simplest fix for this is to introduce a
+bogus dependency (to avoid problems with a parallel @command{make}):
@example
true.o: true.c false.o
@cindex @command{automake}, invoking
To create all the @file{Makefile.in}s for a package, run the
-@code{automake} program in the top level directory, with no arguments.
-@code{automake} will automatically find each appropriate
-@file{Makefile.am} (by scanning @file{configure.ac}; @pxref{configure})
-and generate the corresponding @file{Makefile.in}. Note that
-@code{automake} has a rather simplistic view of what constitutes a
-package; it assumes that a package has only one @file{configure.ac}, at
-the top. If your package has multiple @file{configure.ac}s, then you
-must run @code{automake} in each directory holding a
-@file{configure.ac}. (Alternatively, you may rely on Autoconf's
-@code{autoreconf}, which is able to recurse your package tree and run
-@code{automake} where appropriate.)
-
-You can optionally give @code{automake} an argument; @file{.am} is
-appended to the argument and the result is used as the name of the input
-file. This feature is generally only used to automatically rebuild an
-out-of-date @file{Makefile.in}. Note that @code{automake} must always
-be run from the topmost directory of a project, even if being used to
-regenerate the @file{Makefile.in} in some subdirectory. This is
-necessary because @code{automake} must scan @file{configure.ac}, and
-because @code{automake} uses the knowledge that a @file{Makefile.in} is
-in a subdirectory to change its behavior in some cases.
+@command{automake} program in the top level directory, with no
+arguments. @command{automake} will automatically find each
+appropriate @file{Makefile.am} (by scanning @file{configure.ac};
+@pxref{configure}) and generate the corresponding @file{Makefile.in}.
+Note that @command{automake} has a rather simplistic view of what
+constitutes a package; it assumes that a package has only one
+@file{configure.ac}, at the top. If your package has multiple
+@file{configure.ac}s, then you must run @command{automake} in each
+directory holding a @file{configure.ac}. (Alternatively, you may rely
+on Autoconf's @command{autoreconf}, which is able to recurse your
+package tree and run @command{automake} where appropriate.)
+
+You can optionally give @command{automake} an argument; @file{.am} is
+appended to the argument and the result is used as the name of the
+input file. This feature is generally only used to automatically
+rebuild an out-of-date @file{Makefile.in}. Note that
+@command{automake} must always be run from the topmost directory of a
+project, even if being used to regenerate the @file{Makefile.in} in
+some subdirectory. This is necessary because @command{automake} must
+scan @file{configure.ac}, and because @command{automake} uses the
+knowledge that a @file{Makefile.in} is in a subdirectory to change its
+behavior in some cases.
@vindex AUTOCONF
-Automake will run @code{autoconf} to scan @file{configure.ac} and its
-dependencies (i.e., @file{aclocal.m4} and any included file),
-therefore @code{autoconf} must be in your @code{PATH}. If there is an
-@code{AUTOCONF} variable in your environment it will be used instead
-of @code{autoconf}, this allows you to select a particular version of
-Autoconf. By the way, don't misunderstand this paragraph: Automake
-runs @code{autoconf} to @strong{scan} your @file{configure.ac}, this
-won't build @file{configure} and you still have to run @code{autoconf}
-yourself for this purpose.
+Automake will run @command{autoconf} to scan @file{configure.ac} and
+its dependencies (i.e., @file{aclocal.m4} and any included file),
+therefore @command{autoconf} must be in your @env{PATH}. If there is
+an @env{AUTOCONF} variable in your environment it will be used
+instead of @command{autoconf}, this allows you to select a particular
+version of Autoconf. By the way, don't misunderstand this paragraph:
+@command{automake} runs @command{autoconf} to @strong{scan} your
+@file{configure.ac}, this won't build @file{configure} and you still
+have to run @command{autoconf} yourself for this purpose.
@cindex @command{automake} options
@cindex Options, @command{automake}
@cindex Files distributed with Automake
@cindex @file{config.guess}
-@table @samp
+@table @code
@item -a
@itemx --add-missing
@opindex -a
ones to be automatically added to the package, whenever possible. In
general if Automake tells you a file is missing, try using this option.
By default Automake tries to make a symbolic link pointing to its own
-copy of the missing file; this can be changed with @code{--copy}.
+copy of the missing file; this can be changed with @option{--copy}.
Many of the potentially-missing files are common scripts whose
location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
@opindex -c
@itemx --copy
@opindex --copy
-When used with @code{--add-missing}, causes installed files to be
+When used with @option{--add-missing}, causes installed files to be
copied. The default is to make a symbolic link.
@item --cygnus
@opindex -f
@itemx --force-missing
@opindex --force-missing
-When used with @code{--add-missing}, causes standard files to be reinstalled
+When used with @option{--add-missing}, causes standard files to be reinstalled
even if they already exist in the source tree. This involves removing
the file from the source tree before creating the new symlink (or, with
-@code{--copy}, copying the new file).
+@option{--copy}, copying the new file).
@item --foreign
@opindex --foreign
-Set the global strictness to @samp{foreign}. For more information, see
+Set the global strictness to @option{foreign}. For more information, see
@ref{Strictness}.
@item --gnits
@opindex --gnits
-Set the global strictness to @samp{gnits}. For more information, see
+Set the global strictness to @option{gnits}. For more information, see
@ref{Gnits}.
@item --gnu
@opindex --gnu
-Set the global strictness to @samp{gnu}. For more information, see
+Set the global strictness to @option{gnu}. For more information, see
@ref{Gnits}. This is the default strictness.
@item --help
@item --no-force
@opindex --no-force
-Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
+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
dependents.
@opindex --warnings
Output warnings falling in @var{category}. @var{category} can be
one of:
-@table @samp
+@table @code
@item gnu
warnings related to the GNU Coding Standards
(@pxref{Top, , , standards, The GNU Coding Standards}).
@end table
A category can be turned off by prefixing its name with @samp{no-}. For
-instance @samp{-Wno-syntax} will hide the warnings about unused
+instance @option{-Wno-syntax} will hide the warnings about unused
variables.
The categories output by default are @samp{syntax} and
-@samp{unsupported}. Additionally, @samp{gnu} is enabled in @samp{--gnu} and
-@samp{--gnits} strictness.
+@samp{unsupported}. Additionally, @samp{gnu} is enabled in @option{--gnu} and
+@option{--gnits} strictness.
@samp{portability} warnings are currently disabled by default, but they
-will be enabled in @samp{--gnu} and @samp{--gnits} strictness in a
+will be enabled in @option{--gnu} and @option{--gnits} strictness in a
future release.
@vindex WARNINGS
-The environment variable @samp{WARNINGS} can contain a comma separated
+The environment variable @env{WARNINGS} can contain a comma separated
list of categories to enable. It will be taken into account before the
-command-line switches, this way @samp{-Wnone} will also ignore any
-warning category enabled by @samp{WARNINGS}. This variable is also used
+command-line switches, this way @option{-Wnone} will also ignore any
+warning category enabled by @env{WARNINGS}. This variable is also used
by other tools like @command{autoconf}; unknown categories are ignored
for this reason.
@cindex Scanning @file{configure.ac}
Automake scans the package's @file{configure.ac} to determine certain
-information about the package. Some @code{autoconf} macros are required
+information about the package. Some @command{autoconf} macros are required
and some variables must be defined in @file{configure.ac}. Automake
will also use information from @file{configure.ac} to further tailor its
output.
Automake also supplies some Autoconf macros to make the maintenance
easier. These macros can automatically be put into your
-@file{aclocal.m4} using the @code{aclocal} program.
+@file{aclocal.m4} using the @command{aclocal} program.
@menu
* Requirements:: Configuration requirements
Creating Output Files, autoconf, The Autoconf Manual}). A listed file
is considered to be an Automake generated @file{Makefile} if there
exists a file with the same name and the @file{.am} extension appended.
-Typically, @code{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
+Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
When using @code{AC_CONFIG_FILES} with multiple input files, as in
-@code{AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])}, Automake
-will generate the first @file{.in} input file for which a @file{.am}
-file exists. If no such file exists the output file is not considered
-to be Automake generated.
+
+@example
+AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
+@end example
+
+@noindent
+@command{automake} will generate the first @file{.in} input file for
+which a @file{.am} file exists. If no such file exists the output
+file is not considered to be Automake generated.
Files created by @code{AC_CONFIG_FILES}, be they Automake
-@file{Makefile}s or not, are all removed by @code{make distclean}.
+@file{Makefile}s or not, are all removed by @samp{make distclean}.
Their inputs are automatically distributed, except for inputs that
turn out the be outputs of prior @code{AC_CONFIG_FILES} commands.
Finally, rebuild rules are generated in the Automake @file{Makefile}
@command{automake} will output rules to clean @file{output}, and
rebuild it. However the rebuild rule will not depend on @file{input},
and this file will not be distributed either. (You must add
-@code{EXTRA_DIST = input} to your @file{Makefile} if @file{input} is a
+@samp{EXTRA_DIST = input} to your @file{Makefile} if @file{input} is a
source file.)
Similarly
@noindent
will only cause @file{input} to be distributed. No file will be
-cleaned automatically (add @code{DISTCLEANFILES = output out}
+cleaned automatically (add @samp{DISTCLEANFILES = output out}
yourself), and no rebuild rule will be output.
-Obviously @command{automake} cannot guess what value @code{$file} is
+Obviously @command{automake} cannot guess what value @samp{$file} is
going to hold later when @file{configure} is run, and it cannot use
-the shell variable @code{$file} in a @file{Makefile}. However, if you
-make reference to @code{$file} as @code{$@{file@}} (i.e., in a way
+the shell variable @samp{$file} in a @file{Makefile}. However, if you
+make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
that is compatible with @command{make}'s syntax) and furthermore use
-@code{AC_SUBST} to ensure that @code{$@{file@}} is meaningful in a
+@code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
@file{Makefile}, then @command{automake} will be able to use
-@code{$@{file@}} to generate all these rules. For instance here is
+@samp{$@{file@}} to generate all these rules. For instance here is
how the Automake package itself generates versioned scripts for its
test suite:
@noindent
Here cleaning, distributing, and rebuilding are done automatically,
-because @code{$@{APIVERSION@}} is known at @code{make}-time.
+because @samp{$@{APIVERSION@}} is known at @command{make}-time.
Note that you should not use shell variables to declare
@file{Makefile} files for which @command{automake} must create
@item
Use literals for @file{Makefile}s, and for other files whenever possible.
@item
-Use @code{$file} (or @code{$@{file@}} without @code{AC_SUBST([file])})
+Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
for files that @command{automake} should ignore.
@item
-Use @code{$@{file@}} and @code{AC_SUBST([file])} for files
+Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
that @command{automake} should not ignore.
@end itemize
@item AC_CONFIG_LINKS
Automake will generate rules to remove @file{configure} generated
-links on @code{make distclean} and to distribute named source files as
-part of @code{make dist}.
+links on @samp{make distclean} and to distribute named source files as
+part of @samp{make dist}.
As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
specification using shell variables will be ignored as far as cleaning
@vindex host_triplet
@vindex target_triplet
Automake will ensure that @file{config.guess} and @file{config.sub}
-exist. Also, the @file{Makefile} variables @samp{build_triplet},
-@samp{host_triplet} and @samp{target_triplet} are introduced. See
+exist. Also, the @file{Makefile} variables @code{build_triplet},
+@code{host_triplet} and @code{target_triplet} are introduced. See
@ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
The Autoconf Manual}.
@code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
-an Autoconf macro is documented to call @code{AC_LIBOBJ([file])}, then
+an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
@file{file.c} will be distributed automatically by Automake. This
encompasses many macros like @code{AC_FUNC_ALLOCA},
@code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
@item AC_PROG_LIBTOOL
-Automake will turn on processing for @code{libtool} (@pxref{Top, ,
+Automake will turn on processing for @command{libtool} (@pxref{Top, ,
Introduction, libtool, The Libtool Manual}).
@item AC_PROG_YACC
@vindex YACC
If a Yacc source file is seen, then you must either use this macro or
-define the variable @samp{YACC} in @file{configure.ac}. The former is
+define the variable @code{YACC} in @file{configure.ac}. The former is
preferred (@pxref{Particular Programs, , Particular Program Checks,
autoconf, The Autoconf Manual}).
@item AM_MAINTAINER_MODE
@opindex --enable-maintainer-mode
-This macro adds a @samp{--enable-maintainer-mode} option to
-@code{configure}. If this is used, @code{automake} will cause
-@samp{maintainer-only} rules to be turned off by default in the
+This macro adds a @option{--enable-maintainer-mode} option to
+@command{configure}. If this is used, @command{automake} will cause
+``maintainer-only'' rules to be turned off by default in the
generated @file{Makefile.in}s. This macro defines the
-@samp{MAINTAINER_MODE} conditional, which you can use in your own
+@code{MAINTAINER_MODE} conditional, which you can use in your own
@file{Makefile.am}. @xref{maintainer-mode}.
@item m4_include
leader.
When a file selected by @command{aclocal} is located in a subdirectory
-specified as a relative search path with @command{aclocal}'s @code{-I}
+specified as a relative search path with @command{aclocal}'s @option{-I}
argument, @command{aclocal} assumes the file belongs to the package
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
system-wide directory, or via an absolute search path will be copied.
-So use @code{-I `pwd`/reldir} instead of @code{-I reldir} whenever
+So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
some relative directory need to be considered outside the package.
The contents of @file{acinclude.m4}, if this file exists, are also
using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
@vindex AUTOM4TE
-While computing @file{aclocal.m4}, @code{aclocal} runs @code{autom4te}
-(@pxref{Using autom4te, , Using @code{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 mentioned but
-otherwise unexpanded (this can happen when a macro is called
-conditionally). @code{autom4te} is expected to be in the @code{PATH},
-just as @code{autoconf}. Its location can be overridden using the
-@code{AUTOM4TE} environment variable.
+@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
+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
+overridden using the @env{AUTOM4TE} environment variable.
@menu
* aclocal options:: Options supported by aclocal
@cindex @command{aclocal}, Options
@cindex Options, @command{aclocal}
-@code{aclocal} accepts the following options:
+@command{aclocal} accepts the following options:
@table @code
@item --acdir=@var{dir}
@item --diff[=@var{command}]
@opindex --diff
Run @var{command} on M4 file that would be installed or overwritten
-by @code{--install}. The default @var{command} is @code{diff -u}.
-This option implies @code{--install} and @code{--dry-run}.
+by @option{--install}. The default @var{command} is @samp{diff -u}.
+This option implies @option{--install} and @option{--dry-run}.
@item --dry-run
@opindex --dry-run
Do not actually overwrite (or create) @file{aclocal.m4} and M4
-files installed by @code{--install}.
+files installed by @option{--install}.
@item --help
@opindex --help
@item --install
@opindex --install
Install system-wide third-party macros into the first directory
-specified with @code{-I @var{dir}} instead of copying them in the
+specified with @samp{-I @var{dir}} instead of copying them in the
output file.
-@cindex serial number and @code{--install}
+@cindex serial number and @option{--install}
When this option is used, and only when this option is used,
-@command{aclocal} will also honor @code{#serial @var{NUMBER}} lines
+@command{aclocal} will also honor @samp{#serial @var{NUMBER}} lines
that appear in macros: an M4 file is ignored if there exists another
M4 file with the same basename and a greater serial number in the
search path (@pxref{Serials}).
This option forces the update of @file{aclocal.m4} (or the file
specified with @file{--output} below) and only this file, it has
absolutely no influence on files that may need to be installed by
-@code{--install}.
+@option{--install}.
@item --output=@var{file}
@opindex --output
@item --print-ac-dir
@opindex --print-ac-dir
-Prints the name of the directory which @code{aclocal} will search to
+Prints the name of the directory which @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.
@opindex --warnings
Output warnings falling in @var{category}. @var{category} can be
one of:
-@table @samp
+@table @code
@item syntax
dubious syntactic constructs, underquoted macros, unused macros, etc.
@item unsupported
All warnings are output by default.
@vindex WARNINGS
-The environment variable @samp{WARNINGS} is honored in the same
+The environment variable @env{WARNINGS} is honored in the same
way as it is for @command{automake} (@pxref{Invoking Automake}).
@end table
configured when @command{automake} itself is built. This is
@file{@@datadir@@/aclocal/}, which typically
expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
-value of @var{acdir}, use the @code{--print-ac-dir} option
+value of @var{acdir}, use the @option{--print-ac-dir} option
(@pxref{aclocal options}).
@end table
As an example, suppose that @command{automake-1.6.2} was configured with
-@code{--prefix=@-/usr/local}. Then, the search path would be:
+@option{--prefix=@-/usr/local}. Then, the search path would be:
@enumerate
@item @file{/usr/local/share/aclocal-1.6/}
As explained in (@pxref{aclocal options}), there are several options that
can be used to change or extend this search path.
-@subsubsection Modifying the macro search path: @code{--acdir}
+@subsubsection Modifying the macro search path: @option{--acdir}
The most erroneous option to modify the search path is
-@code{--acdir=@var{dir}}, which changes default directory and
+@option{--acdir=@var{dir}}, which changes default directory and
drops the @var{APIVERSION} directory. For example, if one specifies
-@code{--acdir=/opt/private/}, then the search path becomes:
+@samp{--acdir=/opt/private/}, then the search path becomes:
@enumerate
@item @file{/opt/private/}
@end enumerate
-This option, @code{--acdir}, is intended for use by the internal
+This option, @option{--acdir}, is intended for use by the internal
automake test suite only; it is not ordinarily needed by end-users.
-@subsubsection Modifying the macro search path: @code{-I @var{dir}}
+@subsubsection Modifying the macro search path: @samp{-I @var{dir}}
-Any extra directories specified using @code{-I} options
+Any extra directories specified using @option{-I} options
(@pxref{aclocal options}) are @emph{prepended} to this search list. Thus,
-@code{aclocal -I /foo -I /bar} results in the following search path:
+@samp{aclocal -I /foo -I /bar} results in the following search path:
@enumerate
@item @file{/foo}
@end example
@noindent
-and that @code{aclocal} was called with the @code{-I /foo -I /bar} options.
+and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
Then, the search path would be
+@c @code looks better than @file here
@enumerate
-@item @file{/foo}
-@item @file{/bar}
+@item @code{/foo}
+@item @code{/bar}
@item @var{acdir}-@var{APIVERSION}
@item @var{acdir}
-@item @file{/test1}
-@item @file{/test2}
+@item @code{/test1}
+@item @code{/test2}
@end enumerate
-If the @code{--acdir=@var{dir}} option is used, then @command{aclocal}
+If the @option{--acdir=@var{dir}} option is used, then @command{aclocal}
will search for the @file{dirlist} file in @var{dir}. In the
-@code{--acdir=/opt/private/} example above, @command{aclocal} would look
-for @file{/opt/private/dirlist}. Again, however, the @code{--acdir}
+@samp{--acdir=/opt/private/} example above, @command{aclocal} would look
+for @file{/opt/private/dirlist}. Again, however, the @option{--acdir}
option is intended for use by the internal automake test suite only;
-@code{--acdir} is not ordinarily needed by end-users.
+@option{--acdir} is not ordinarily needed by end-users.
@file{dirlist} is useful in the following situation: suppose that
-@code{automake} version @code{1.6.2} is installed with
+@command{automake} version @code{1.6.2} is installed with
$prefix=/usr by the system vendor. Thus, the default search
directories are
+@c @code looks better than @file here
@enumerate
-@item @file{/usr/share/aclocal-1.6/}
-@item @file{/usr/share/aclocal/}
+@item @code{/usr/share/aclocal-1.6/}
+@item @code{/usr/share/aclocal/}
@end enumerate
However, suppose further that many packages have been manually
-installed on the system, with $prefix=/usr/local, as is typical.
-In that case, many of these ``extra'' @file{.m4} files are in
+installed on the system, with $prefix=/usr/local, as is typical. In
+that case, many of these ``extra'' @file{.m4} files are in
@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 @code{aclocal -I /usr/local/share/aclocal}.
-This is inconvenient. With @file{dirlist}, one may create the file
-
-@file{/usr/share/aclocal/dirlist}
+@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
-@noindent
-which contains only the single line
-
-@file{/usr/local/share/aclocal}
+@example
+/usr/local/share/aclocal
+@end example
Now, the ``default'' search path on the affected system is
+@c @code looks better than @file here
@enumerate
-@item @file{/usr/share/aclocal-1.6/}
-@item @file{/usr/share/aclocal/}
-@item @file{/usr/local/share/aclocal/}
+@item @code{/usr/share/aclocal-1.6/}
+@item @code{/usr/share/aclocal/}
+@item @code{/usr/local/share/aclocal/}
@end enumerate
-without the need for @code{-I} options; @code{-I} options can be reserved
+without the need for @option{-I} options; @option{-I} options can be reserved
for project-specific needs (@file{my-source-dir/m4/}), rather than
using it to work around local system-dependent tool installation
directories.
@noindent
Please do use @file{$(datadir)/aclocal}, and not something based on
-the result of @code{aclocal --print-ac-dir}. @xref{Hard-Coded Install
+the result of @samp{aclocal --print-ac-dir}. @xref{Hard-Coded Install
Paths}, for arguments.
A file of macros should be a series of properly quoted
in its own file and gather all these files in a directory. This
directory is usually called @file{m4/}. To build @file{aclocal.m4},
one should therefore instruct @command{aclocal} to scan @file{m4/}.
-From the command line, this is done with @code{aclocal -I m4}. The
+From the command line, this is done with @samp{aclocal -I m4}. The
top-level @file{Makefile.am} should also be updated to define
@example
@end example
@code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
-when @file{aclocal.m4} is to be rebuilt by @code{make}. This line is
+when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
Using @command{autoreconf} to Update @file{configure} Scripts,
autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
do not really care about the rebuild rules, you should define
@code{ACLOCAL_AMFLAGS}.
-When @code{aclocal -I m4} is run, it will build a @code{aclocal.m4}
+When @samp{aclocal -I m4} is run, it will build a @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}.
installed macros will have precedence over the system-wide installed
macros each time @command{aclocal} is run again.
-One reason why you should keep @code{--install} in the flags even
+One reason why you should keep @option{--install} in the flags even
after the first run is that when you later edit @file{configure.ac}
and depend on a new macro, this macro will be installed in your
@file{m4/} automatically. Another one is that serial numbers
where @var{NNN} contains only digits and dots. It should appear in
the M4 file before any macro definition. It is a good practice to
maintain a serial number for each macro you distribute, even if you do
-not use the @code{--install} option of @command{aclocal}: this allows
+not use the @option{--install} option of @command{aclocal}: this allows
other people to use it.
Because third-party macros defined in @file{*.m4} files are naturally
shared between multiple projects, some people like to version them.
This makes it easier to tell which of two M4 files is newer. Since at
-least 1996, the tradition is to use a @code{#serial} line for this.
+least 1996, the tradition is to use a @samp{#serial} line for this.
A serial number should be a single line of the form
time they change the macro (hence the name of ``serial''). Such a
line should appear in the M4 file before any macro definition.
-The @code{#} must be the first character on the line,
+The @samp{#} must be the first character on the line,
and it is OK to have extra words after the version, as in
@example
Normally these serial numbers are completely ignored by
@command{aclocal} and @command{autoconf}, like any genuine comment.
-However when using @command{aclocal}'s @code{--install} feature, these
+However when using @command{aclocal}'s @option{--install} feature, these
serial numbers will modify the way @command{aclocal} selects the
macros to install in the package: if two files with the same basename
exists in your search path, and if at least one of them use a
-@code{#serial} line, @command{aclocal} will ignore the file that has
-the older @code{#serial} line (or the file that has none).
+@samp{#serial} line, @command{aclocal} will ignore the file that has
+the older @samp{#serial} line (or the file that has none).
Note that a serial number applies to a whole M4 file, not to any macro
it contains. A file can contains multiple macros, but only one
serial.
-Here is a use case that illustrate the use of @code{--install} and its
-interaction with serial numbers. Let's assume we maintain a package
-called MyPackage, whose @file{configure.ac} uses a third-party macro
-@code{AX_THIRD_PARTY} defined in
+Here is a use case that illustrate the use of @option{--install} and
+its interaction with serial numbers. Let's assume we maintain a
+package called MyPackage, the @file{configure.ac} of which requires a
+third-party macro @code{AX_THIRD_PARTY} defined in
@file{/usr/share/aclocal/thirdparty.m4} as follows:
@example
Initially the @file{m4/} directory is empty. The first time we run
@command{autoreconf}, it will fetch the options to pass to
-@command{aclocal} in @file{Makefile.am}, and run @code{aclocal -I m4
+@command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
--install}. @command{aclocal} will notice that
@itemize @bullet
@noindent
Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
-and @command{aclocal} was given the @code{--install} option, it will
+and @command{aclocal} was given the @option{--install} option, it will
copy this file in @file{m4/thirdparty.m4}, and output an
-@file{aclocal.m4} that contains @code{m4_include([m4/thirdparty.m4])}.
+@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
-The next time @code{aclocal -I m4 --install} is run (either via
+The next time @samp{aclocal -I m4 --install} is run (either via
@command{autoreconf}, by hand, or from the @file{Makefile} rebuild
rules) something different happens. @command{aclocal} notices that
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 @code{m4_include([m4/thirdparty.m4])}.
+@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
-Local directories specified with @code{-I} are always searched before
+Local directories specified with @option{-I} are always searched before
system-wide directories, so a local file will always be preferred to
the system-wide file in case of equal serial numbers.
Now suppose the system-wide third-party macro is changed. This can
happen if the package installing this macro is updated. Let's suppose
-the new macro has serial number 2. The next time @code{aclocal -I m4
+the new macro has serial number 2. The next time @samp{aclocal -I m4
--install} is run the situation is the following:
@itemize @bullet
running @command{aclocal}.
If you are leery of letting @command{aclocal} update your local macro,
-you can run @code{aclocal -I m4 --diff} to review the changes
-@code{aclocal -I m4 --install} would perform on these macros.
+you can run @samp{aclocal -I m4 --diff} to review the changes
+@samp{aclocal -I m4 --install} would perform on these macros.
-Finally, note that the @code{--force} option of @command{aclocal} has
-absolutely no effect on the files installed by @code{--install}. For
+Finally, note that the @option{--force} option of @command{aclocal} has
+absolutely no effect on the files installed by @option{--install}. For
instance you have modified your local macros, do not expect
-@code{--install --force} to replace the local macros by their
+@option{--install --force} to replace the local macros by their
system-wide versions. If you want to do so, simply erase the local
-macros you want to revert, and run @code{aclocal -I m4 --install}.
+macros you want to revert, and run @samp{aclocal -I m4 --install}.
@node Future of aclocal
you will not call @command{aclocal} directly anymore.
For the time being, third-party packages should continue to install
-public macros into @code{/usr/share/aclocal/}. If @command{aclocal}
+public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
is replaced by another tool it might make sense to rename the
-directory, but supporting @code{/usr/share/aclocal/} for backward
+directory, but supporting @file{/usr/share/aclocal/} for backward
compatibility should be really easy provided all macros are properly
written (@pxref{Extending aclocal}).
Automake ships with several Autoconf macros that you can use from your
@file{configure.ac}. When you use one of them it will be included by
-@code{aclocal} in @file{aclocal.m4}.
+@command{aclocal} in @file{aclocal.m4}.
@menu
* Public macros:: Macros that you can use.
@vindex ANSI2KNR
@vindex U
Check to see if function prototypes are understood by the compiler. If
-so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
-@samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
-@samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
+so, define @samp{PROTOTYPES} and set the output variables @code{U} and
+@code{ANSI2KNR} to the empty string. Otherwise, set @code{U} to
+@samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
values to implement automatic de-ANSI-fication.
@item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
@cindex @code{PACKAGE}, prevent definition
@cindex @code{VERSION}, prevent definition
@opindex no-define
-By default this macro @code{AC_DEFINE}'s @samp{PACKAGE} and
-@samp{VERSION}. This can be avoided by passing the @samp{no-define}
+By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
+@code{VERSION}. This can be avoided by passing the @option{no-define}
option, as in:
@example
AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
@acindex AM_PATH_LISPDIR
@vindex EMACS
@vindex lispdir
-Searches for the program @code{emacs}, and, if found, sets the output
-variable @code{lispdir} to the full path to Emacs' site-lisp directory.
-
-Note that this test assumes the @code{emacs} found to be a version that
-supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other emacsen
-can cause this test to hang (some, like old versions of MicroEmacs,
-start up in interactive mode, requiring @samp{C-x C-c} to exit, which
-is hardly obvious for a non-emacs user). In most cases, however, you
-should be able to use @samp{C-c} to kill the test. In order to avoid
-problems, you can set @code{EMACS} to ``no'' in the environment, or
-use the @samp{--with-lispdir} option to @command{configure} to
-explicitly set the correct path (if you're sure you have an @code{emacs}
-that supports Emacs Lisp.
+Searches for the program @command{emacs}, and, if found, sets the
+output variable @code{lispdir} to the full path to Emacs' site-lisp
+directory.
+
+Note that this test assumes the @command{emacs} found to be a version
+that supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other
+emacsen can cause this test to hang (some, like old versions of
+MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
+exit, which is hardly obvious for a non-emacs user). In most cases,
+however, you should be able to use @kbd{C-c} to kill the test. In
+order to avoid problems, you can set @env{EMACS} to ``no'' in the
+environment, or use the @option{--with-lispdir} option to
+@command{configure} to explicitly set the correct path (if you're sure
+you have an @command{emacs} that supports Emacs Lisp.
@item AM_PROG_AS
@acindex AM_PROG_AS
@cindex @command{lex} problems with HP-UX 10
Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
Program Checks, autoconf, The Autoconf Manual}), but uses the
-@code{missing} script on systems that do not have @code{lex}.
-@samp{HP-UX 10} is one such system.
+@command{missing} script on systems that do not have @command{lex}.
+HP-UX 10 is one such system.
@item AM_PROG_GCJ
@acindex AM_PROG_GCJ
@vindex GCJ
@vindex GCJFLAGS
-This macro finds the @code{gcj} program or causes an error. It sets
-@samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
+This macro finds the @command{gcj} program or causes an error. It sets
+@code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
GNU Compiler Collection.
@item AM_SYS_POSIX_TERMIOS
@vindex WITH_DMALLOC
@opindex --with-dmalloc
Add support for the @uref{http://dmalloc.com/, Dmalloc package}.
-If the user configures with @samp{--with-dmalloc}, then define
-@code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
+If the user configures with @option{--with-dmalloc}, then define
+@code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
@item AM_WITH_REGEX
@acindex AM_WITH_REGEX
@opindex --with-regex
@cindex regex package
@cindex rx package
-Adds @samp{--with-regex} to the @code{configure} command line. If
+Adds @option{--with-regex} to the @command{configure} command line. If
specified (the default), then the @samp{regex} regular expression
-library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
-@samp{WITH_REGEX} is defined. If @samp{--without-regex} is given, then
-the @samp{rx} regular expression library is used, and @file{rx.o} is put
-into @samp{LIBOBJS}.
+library is used, @file{regex.o} is put into @code{LIBOBJS}, and
+@code{WITH_REGEX} is defined. If @option{--without-regex} is given, then
+the @code{rx} regular expression library is used, and @file{rx.o} is put
+into @code{LIBOBJS}.
@end table
required, and there should be no need to invoke them manually.
@item AM_MAKE_INCLUDE
-This macro is used to discover how the user's @code{make} handles
+This macro is used to discover how the user's @command{make} handles
@code{include} statements. This macro is automatically invoked when
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
-@code{strip} a program at installation time. This macro is
-automatically included when required.
+strip a program at installation time. This macro is automatically
+included when required.
@item AM_SANITY_CHECK
This checks to make sure that a file created in the build directory is
SUBDIRS = doc intl po src tests
@end example
-When Automake invokes @code{make} in a subdirectory, it uses the value
+When Automake invokes @command{make} in a subdirectory, it uses the value
of the @code{MAKE} variable. It passes the value of the variable
-@code{AM_MAKEFLAGS} to the @code{make} invocation; this can be set in
+@code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
@file{Makefile.am} if there are flags you must always pass to
-@code{make}.
+@command{make}.
@vindex MAKE
@vindex AM_MAKEFLAGS
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,
-putting @samp{.} first will cause a @samp{prefix} ordering of
+putting @samp{.} first will cause a prefix ordering of
directories.
Using
built after everything else since they are meant to test what has
been constructed.
-All @samp{clean} rules are run in reverse order of build rules.
+All @code{clean} rules are run in reverse order of build rules.
@node Conditional Subdirectories
@section Conditional Subdirectories
@cindex Conditional @code{SUBDIRS}
It is possible to define the @code{SUBDIRS} variable conditionally if,
-like in the case of GNU @code{Inetutils}, you want to only build a
-subset of the entire package.
+like in the case of GNU Inetutils, you want to only build a subset of
+the entire package.
To illustrate how this works, let's assume we have two directories
@file{src/} and @file{opt/}. @file{src/} should always be built, but we
-want to decide in @code{./configure} whether @file{opt/} will be built
+want to decide in @command{configure} whether @file{opt/} will be built
or not. (For this example we will assume that @file{opt/} should be
-built when the variable @code{$want_opt} was set to @code{yes}.)
+built when the variable @samp{$want_opt} was set to @samp{yes}.)
-Running @code{make} should thus recurse into @file{src/} always, and
+Running @command{make} should thus recurse into @file{src/} always, and
then maybe in @file{opt/}.
-However @code{make dist} should always recurse into both @file{src/}
+However @samp{make dist} should always recurse into both @file{src/}
and @file{opt/}. Because @file{opt/} should be distributed even if it
is not needed in the current configuration. This means
@file{opt/Makefile} should be created @emph{unconditionally}.
directories, even those which 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: @code{opt} may not appear in
+@code{DIST_SUBDIRS} come into play: @samp{opt} may not appear in
@code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
-Precisely, @code{DIST_SUBDIRS} is used by @code{make dist}, @code{make
-distclean}, and @code{make maintainer-clean}. All other recursive
-rules use @code{SUBDIRS}.
+Precisely, @code{DIST_SUBDIRS} is used by @samp{make
+maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
+other recursive rules use @code{SUBDIRS}.
If @code{SUBDIRS} is defined conditionally using Automake
conditionals, Automake will define @code{DIST_SUBDIRS} automatically
SUBDIRS = src $(MAYBE_OPT)
@end example
-As you can see, running @code{make} will rightly recurse into
+As you can see, running @command{make} will rightly recurse into
@file{src/} and maybe @file{opt/}.
@vindex DIST_SUBDIRS
-As you can't see, running @code{make dist} will recurse into both
-@file{src/} and @file{opt/} directories because @code{make dist}, unlike
-@code{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
+As you can't see, running @samp{make dist} will recurse into both
+@file{src/} and @file{opt/} directories because @samp{make dist}, unlike
+@samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
@code{DIST_SUBDIRS} variable.
-In this case Automake will define @code{DIST_SUBDIRS = src opt}
+In this case Automake will define @samp{DIST_SUBDIRS = src opt}
automatically because it knows that @code{MAYBE_OPT} can contain
-@code{opt} in some condition.
+@samp{opt} in some condition.
@subsection Conditional Subdirectories with @code{AC_SUBST}
@cindex @code{SUBDIRS} and @code{AC_SUBST}
The above examples all assume that every @file{Makefile} is created,
even in directories that are not going to be built. The simple reason
-is that we want @code{make dist} to distribute even the directories
+is that we want @samp{make dist} to distribute even the directories
that are not being built (e.g. platform-dependent code), hence
@file{make dist} must recurse into the subdirectory, hence this
directory must be configured and appear in @code{DIST_SUBDIRS}.
@item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
must be configured.
-I.e., the @file{Makefile} must exists or the recursive @code{make}
+I.e., the @file{Makefile} must exists or the recursive @command{make}
rules will not be able to process the directory.
@item Any configured directory must be listed in @code{DIST_SUBDIRS}.
@code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance if you define
@code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
@code{DIST_SUBDIRS} explicitly, it will be default to
-@code{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
+@samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
= $(SUBDIRS)}.
Of course, directories which are omitted from @code{DIST_SUBDIRS} will
not be distributed unless you make other arrangements for this to
-happen (for instance always running @code{make dist} in a
+happen (for instance always running @samp{make dist} in a
configuration where all directories are known to appear in
@code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
distribute these directories).
Recursive Make Considered Harmful}, the preceding sections on the use of
subdirectories will probably come as unwelcome advice. For those who
haven't read the paper, Miller's main thesis is that recursive
-@code{make} invocations are both slow and error-prone.
+@command{make} invocations are both slow and error-prone.
Automake provides sufficient cross-directory support @footnote{We
believe. This work is new and there are probably warts.
libhand_a_SOURCES = hand.c
@end example
-When @code{make dist} is run from the top-level directory it will
+When @samp{make dist} is run from the top-level directory it will
create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
code as well as the @file{hand} subdirectory. This package can be
built and installed like any ordinary package, with the usual
-@code{./configure && make && make install} sequence (the @code{hand}
+@samp{./configure && make && make install} sequence (the @code{hand}
subpackage will be built and installed by the process).
-When @code{make dist} is run from the hand directory, it will create a
+When @samp{make dist} is run from the hand directory, it will create a
self-contained @file{hand-1.2.tar.gz} archive. So although it appears
to be embedded in another package, it can still be used separately.
-The purpose of the @code{AC_CONFIG_AUX_DIR([.])} instruction is to
+The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
force Automake and Autoconf into search auxiliary script in the
current directory. For instance this means that there will be two
copies of @file{install-sh}: one in the top-level of the @code{arm}
The historical default is to search these auxiliary scripts in the
immediate parent and grand-parent directories. So if the
-@code{AC_CONFIG_AUX_DIR([.])} line was removed from
+@samp{AC_CONFIG_AUX_DIR([.])} line was removed from
@file{hand/configure.ac}, that subpackage would share the auxiliary
script of the @code{arm} package. This may looks like a gain in size
(a few kilobytes), but it is actually a loss of modularity as the
-@code{hand} subpackage is no longer self-contained (@code{make dist}
+@code{hand} subpackage is no longer self-contained (@samp{make dist}
in the subdirectory will not work anymore).
Packages that do not use Automake need more work to be integrated this
@vindex check_PROGRAMS
In a directory containing source that gets built into a program (as
-opposed to a library or a script), the @samp{PROGRAMS} primary is used.
+opposed to a library or a script), the @code{PROGRAMS} primary is used.
Programs can be installed in @code{bindir}, @code{sbindir},
-@code{libexecdir}, @code{pkglibdir}, or not at all (@samp{noinst}).
-They can also be built only for @code{make check}, in which case the
-prefix is @samp{check}.
+@code{libexecdir}, @code{pkglibdir}, or not at all (@code{noinst_}).
+They can also be built only for @samp{make check}, in which case the
+prefix is @samp{check_}.
For instance:
hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
@end example
-This causes each mentioned @samp{.c} file to be compiled into the
-corresponding @samp{.o}. Then all are linked to produce @file{hello}.
+This causes each mentioned @file{.c} file to be compiled into the
+corresponding @file{.o}. Then all are linked to produce @file{hello}.
@cindex @code{_SOURCES} primary, defined
@cindex @code{SOURCES} primary, defined
@cindex Primary variable, @code{SOURCES}
@vindex _SOURCES
-If @samp{hello_SOURCES} is not specified, then it defaults to the single
+If @code{hello_SOURCES} is not specified, then it defaults to the single
file @file{hello.c} (@pxref{Default _SOURCES}).
@vindex _SOURCES
@vindex SOURCES
Multiple programs can be built in a single directory. Multiple programs
can share a single source file, which must be listed in each
-@samp{_SOURCES} definition.
+@code{_SOURCES} definition.
@cindex Header files in @code{_SOURCES}
@cindex @code{_SOURCES} and header files
-Header files listed in a @samp{_SOURCES} definition will be included in
+Header files listed in a @code{_SOURCES} definition will be included in
the distribution but otherwise ignored. In case it isn't obvious, you
should not include the header file generated by @file{configure} in a
-@samp{_SOURCES} variable; this file should not be distributed. Lex
-(@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
+@code{_SOURCES} variable; this file should not be distributed. Lex
+(@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
and Lex}.
@subsection Linking the program
If you need to link against libraries that are not found by
-@code{configure}, you can use @code{LDADD} to do so. This variable is
+@command{configure}, you can use @code{LDADD} to do so. This variable is
used to specify additional objects or libraries to link with; it is
inappropriate for specifying specific linker flags, you should use
@code{AM_LDFLAGS} for this purpose.
Sometimes, multiple programs are built in one directory but do not share
the same link-time requirements. In this case, you can use the
-@samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
-program as it appears in some @samp{_PROGRAMS} variable, and usually
+@code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
+program as it appears in some @code{_PROGRAMS} variable, and usually
written in lowercase) to override the global @code{LDADD}. If this
variable exists for a given program, then that program is not linked
using @code{LDADD}.
@cindex @code{_LDFLAGS}, defined
@vindex maude_LDFLAGS
-@samp{@var{prog}_LDADD} is inappropriate for passing program-specific
-linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
-@samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
+@code{@var{prog}_LDADD} is inappropriate for passing program-specific
+linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
+@option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
this purpose.
@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
-using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
+using the @code{@var{prog}_DEPENDENCIES} variable. Each program depends
on the contents of such a variable, but no further interpretation is
done.
-If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
+If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
Automake. The automatically-assigned value is the contents of
-@samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
-@samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
+@code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
+@option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
configure substitutions that are left in are only @samp{$(LIBOBJS)} and
@samp{$(ALLOCA)}; these are left because it is known that they will not
-cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
+cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
generated.
You can't put a configure substitution (e.g., @samp{@@FOO@@} or
@samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
-@samp{_SOURCES} variable. The reason for this is a bit hard to
+@code{_SOURCES} variable. The reason for this is a bit hard to
explain, but suffice to say that it simply won't work. Automake will
give an error if you try to do this.
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
-appropriate @samp{EXTRA_} variable. For instance, if
+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:
@end example
@noindent
-You can then setup the @code{$(HELLO_SYSTEM)} substitution from
+You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
@file{configure.ac}:
@example
conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
When using conditionals like this you don't need to use the
-@samp{EXTRA_} variable, because Automake will examine the contents of
+@code{EXTRA_} variable, because Automake will examine the contents of
each variable to construct the complete list of source files.
If your program uses a lot of files, you will probably prefer a
-conditional @code{+=}.
+conditional @samp{+=}.
@example
bin_PROGRAMS = hello
achieve conditional compilation of programs are the same you can use
to compile source files conditionally: substitutions or conditionals.
-@subsubsection Conditional programs using @code{configure} substitutions
+@subsubsection Conditional programs using @command{configure} substitutions
@vindex EXTRA_PROGRAMS
@cindex @code{EXTRA_PROGRAMS}, defined
In this case, you must notify Automake of all the programs that can
possibly be built, but at the same time cause the generated
-@file{Makefile.in} to use the programs specified by @code{configure}.
-This is done by having @code{configure} substitute values into each
-@samp{_PROGRAMS} definition, while listing all optionally built programs
+@file{Makefile.in} to use the programs specified by @command{configure}.
+This is done by having @command{configure} substitute values into each
+@code{_PROGRAMS} definition, while listing all optionally built programs
in @code{EXTRA_PROGRAMS}.
@example
As explained in @ref{EXEEXT}, Automake will rewrite
@code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
-@code{EXTRA_PROGRAMS}, appending @code{$(EXEEXT)} to each binary.
+@code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
Obviously it cannot rewrite values obtained at run-time through
-@code{configure} substitutions, therefore you should take care of
-appending @code{$(EXEEXT)} yourself, as in @code{AC_SUBST([MT],
+@command{configure} substitutions, therefore you should take care of
+appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
['mt$@{EXEEXT@}'])}.
@subsubsection 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
-about @code{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
+about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
@example
bin_PROGRAMS = cpio pax
@vindex noinst_LIBRARIES
Building a library is much like building a program. In this case, the
-name of the primary is @samp{LIBRARIES}. Libraries can be installed in
+name of the primary is @code{LIBRARIES}. Libraries can be installed in
@code{libdir} or @code{pkglibdir}.
@xref{A Shared Library}, for information on how to build shared
-libraries using libtool and the @samp{LTLIBRARIES} primary.
+libraries using libtool and the @code{LTLIBRARIES} primary.
-Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
+Each @code{_LIBRARIES} variable is a list of the libraries to be built.
For instance to create a library named @file{libcpio.a}, but not install
it, you would write:
@end example
The sources that go into a library are determined exactly as they are
-for programs, via the @samp{_SOURCES} variables. Note that the library
-name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
+for programs, via the @code{_SOURCES} variables. Note that the library
+name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
not @samp{libcpio.a_SOURCES}.
@vindex maude_LIBADD
Extra objects can be added to a library using the
-@samp{@var{library}_LIBADD} variable. This should be used for objects
-determined by @code{configure}. Again from @code{cpio}:
+@code{@var{library}_LIBADD} variable. This should be used for objects
+determined by @command{configure}. Again from @code{cpio}:
@example
libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
(@pxref{Sources}).
Building a static library is done by compiling all object files, then
-by invoking @code{$(AR) $(ARFLAGS)} followed by the name of the
+by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
library and the list of objects, and finally by calling
-@code{$(RANLIB)} on that library. You should call
+@samp{$(RANLIB)} on that library. You should call
@code{AC_PROG_RANLIB} from your @file{configure.ac} to define
@code{RANLIB} (Automake will complain otherwise). @code{AR} and
@code{ARFLAGS} default to @code{ar} and @code{cru} respectively; you
@vindex _LTLIBRARIES
Automake uses libtool to build libraries declared with the
-@samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a
+@code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
list of libtool libraries to build. For instance, to create a libtool
-library named @file{libgettext.la}, and install it in @samp{libdir},
+library named @file{libgettext.la}, and install it in @code{libdir},
write:
@example
libgettext_la_SOURCES = gettext.c gettext.h @dots{}
@end example
-Automake predefines the variable @samp{pkglibdir}, so you can use
+Automake predefines the variable @code{pkglibdir}, so you can use
@code{pkglib_LTLIBRARIES} to install libraries in
-@code{$(libdir)/@@PACKAGE@@/}.
+@samp{$(libdir)/@@PACKAGE@@/}.
If @file{gettext.h} is a public header file that needs to be installed
in order for people to use the library, it should be declared using a
A package can build and install such a library along with other
programs that use it. This dependency should be specified using
@code{LDADD}. The following example builds a program named
-@file{hello} that is linked with @code{libgettext.la}.
+@file{hello} that is linked with @file{libgettext.la}.
@example
lib_LTLIBRARIES = libgettext.la
@noindent
Whether @file{hello} is statically or dynamically linked with
-@code{libgettext.la} is not yet known: this will depend on the
+@file{libgettext.la} is not yet known: this will depend on the
configuration of libtool and the capabilities of the host.
The important implementation detail you have to be aware of is that
the place where a library will be installed matters to libtool: it
-needs to be indicated @emph{at link-time} using the @code{-rpath}
+needs to be indicated @emph{at link-time} using the @option{-rpath}
option.
For libraries whose destination directory is known when Automake runs,
-Automake will automatically supply the appropriate @samp{-rpath}
+Automake will automatically supply the appropriate @option{-rpath}
option to libtool. This is the case for libraries listed explicitly in
some installable @code{_LTLIBRARIES} variables such as
@code{lib_LTLIBRARIES}.
However, for libraries determined at configure time (and thus
mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
final installation directory. For such libraries you must add the
-@samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
+@option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
hand.
The examples below illustrate the differences between these two methods.
Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
variable set at @file{./configure}-time to either @file{libfoo.la},
-@file{libbar.la}, both, or none. Although @code{$(WANTEDLIBS)}
+@file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
relates to @file{libfoo.la} or @file{libbar.la} by the time it creates
-the link rule for these two libraries. Therefore the @code{-rpath}
+the link rule for these two libraries. Therefore the @option{-rpath}
argument must be explicitly supplied.
@example
Here is how the same @file{Makefile.am} would look using Automake
conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
-Automake is able to compute the @code{-rpath} setting itself, because
-it's clear that both libraries will end up in @code{$(libdir)} if they
+Automake is able to compute the @option{-rpath} setting itself, because
+it's clear that both libraries will end up in @samp{$(libdir)} if they
are installed.
@example
@end example
@noindent
-And make sure @code{$(HELLO_SYSTEM)} is set to either
-@file{hello-linux.lo} or @file{hello-generic.lo} in
-@file{./configure}.
+And make sure @command{configure} defines @code{HELLO_SYSTEM} as
+either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
Or we could simply use an Automake conditional as follows.
Libtool convenience libraries are declared by directory-less variables
such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
@code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
-not need an @code{-rpath} flag at link time (actually this is the only
+not need an @option{-rpath} flag at link time (actually this is the only
difference).
Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
built. Those listed in @code{check_LTLIBRARIES} are built only upon
-@code{make check}. Finally, libraries listed in
+@samp{make check}. Finally, libraries listed in
@code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
rules to build them, but if the library does not appear as a Makefile
dependency anywhere it won't be built (this is why
@dots{}
@end example
-@code{EXTRA_*_SOURCES} variables are used to keep track of source
+@samp{EXTRA_*_SOURCES} variables are used to keep track of source
files that might be compiled (this is mostly useful when doing
conditional compilation using @code{AC_SUBST}, @pxref{Conditional
Libtool Sources}), and the @code{nodist_} prefix means the listed
@subsection Libtool Modules
@cindex modules, libtool
@cindex libtool modules
-@cindex @code{-module}, libtool
+@cindex @option{-module}, libtool
These are libtool libraries meant to be dlopened. They are
-indicated to libtool by passing @code{-module} at link-time.
+indicated to libtool by passing @option{-module} at link-time.
@example
pkglib_LTLIBRARIES = mymodule.la
@end example
Ordinarily, Automake requires that a library's name starts with
-@samp{lib}. However, when building a dynamically loadable module you
+@code{lib}. However, when building a dynamically loadable module you
might wish to use a "nonstandard" name. Automake will not complain
about such nonstandard name if it knows the library being built is a
-libtool module, i.e., if @samp{-module} explicitly appears in the
+libtool module, i.e., if @option{-module} explicitly appears in the
library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
variable when no per-library @code{_LDFLAGS} variable is defined).
As always, @code{AC_SUBST} variables are black boxes to Automake since
their values are not yet known when @command{automake} is run.
-Therefore if @code{-module} is set via such a variable, Automake
+Therefore if @option{-module} is set via such a variable, Automake
cannot notice it and will proceed as if the library was an ordinary
libtool library, with strict naming.
-If @samp{mymodule_la_SOURCES} is not specified, then it defaults to
+If @code{mymodule_la_SOURCES} is not specified, then it defaults to
the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
@node Libtool Flags
files) or libtool libraries (@file{.la}) to add to @var{library}.
The @samp{@var{library}_LDFLAGS} variable is the place to list
-additional libtool linking flags, such as @samp{-version-info},
-@samp{-static}, and a lot more. @xref{Link mode, , Link mode,
+additional libtool linking flags, such as @option{-version-info},
+@option{-static}, and a lot more. @xref{Link mode, , Link mode,
libtool, The Libtool Manual}.
The @command{libtool} command has two kinds of options: mode-specific
aforementioned linking flags should be lumped with the other flags
passed to the tool invoked by @command{libtool} (hence the use of
@samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
-options include @samp{--tag=@var{TAG}} and @samp{--silent}
+options include @option{--tag=@var{TAG}} and @option{--silent}
(@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
Libtool Manual} for more options) should appear before the mode
selection on the command line; in @file{Makefile.am}s they should
be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
If @samp{@var{library}_LIBTOOLFLAGS} is not defined, the global
-@samp{AM_LIBTOOLFLAGS} variable is used instead.
+@code{AM_LIBTOOLFLAGS} variable is used instead.
-These flags are passed to libtool after the @samp{--tag=@var{TAG}}
+These flags are passed to libtool after the @option{--tag=@var{TAG}}
option computed by Automake (if any), so
-@samp{@var{library}_LIBTOOLFLAGS} (or @samp{AM_LIBTOOLFLAGS}) is the
-good place to override or supplement the @samp{--tag=@var{TAG}}
+@samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is the
+good place to override or supplement the @option{--tag=@var{TAG}}
setting.
The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
@vindex ALLOCA
@acindex AC_LIBOBJ
-Where an ordinary library might include @code{$(LIBOBJS)} or
-@code{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
-@code{$(LTLIBOBJS)} or @code{$(LTALLOCA)}. This is required because
+Where an ordinary library might include @samp{$(LIBOBJS)} or
+@samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
+@samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
the object files that libtool operates on do not necessarily end in
@file{.o}.
@node Libtool Issues
@subsection Common Issues Related to Libtool's Use
-@subsubsection @code{required file `./ltmain.sh' not found}
+@subsubsection @samp{required file `./ltmain.sh' not found}
@cindex @file{ltmain.sh} not found
@cindex @command{libtoolize}, no longer run by @command{automake}
@cindex @command{libtoolize} and @command{autoreconf}
a call to @command{autoreconf} should also free you from any similar
incompatible change in the future.
-@subsubsection Objects @code{created with both libtool and without}
+@subsubsection Objects @samp{created with both libtool and without}
Sometimes, the same source file is used both to build a libtool
library and to build another non-libtool target (be it a program or
@end example
@noindent
-Adding @code{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
+Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
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
libraries; the documentation below notes situations where programs and
libraries differ.
-@vtable @samp
+@vtable @code
@item maude_SOURCES
This variable, if it exists, lists all the source files which are
compiled to build the program. These files are added to the
each source file to be compiled to a single @file{.o} file (or
@file{.lo} when using libtool). Normally these object files are named
after the source file, but other factors can change this. If a file in
-the @samp{_SOURCES} variable has an unrecognized extension, Automake
+the @code{_SOURCES} variable has an unrecognized extension, Automake
will do one of two things with it. If a suffix rule exists for turning
files with the unrecognized extension into @file{.o} files, then
automake will treat this file as it will any other source file
(@pxref{Support for Other Languages}). Otherwise, the file will be
ignored as though it were a header file.
-The prefixes @samp{dist_} and @samp{nodist_} can be used to control
-whether files listed in a @samp{_SOURCES} variable are distributed.
-@samp{dist_} is redundant, as sources are distributed by default, but it
+The prefixes @code{dist_} and @code{nodist_} can be used to control
+whether files listed in a @code{_SOURCES} variable are distributed.
+@code{dist_} is redundant, as sources are distributed by default, but it
can be specified for clarity if desired.
-It is possible to have both @samp{dist_} and @samp{nodist_} variants of
-a given @samp{_SOURCES} variable at once; this lets you easily
+It is possible to have both @code{dist_} and @code{nodist_} variants of
+a given @code{_SOURCES} variable at once; this lets you easily
distribute some files and not others, for instance:
@example
dist_maude_SOURCES = dist-me.c
@end example
-By default the output file (on Unix systems, the @file{.o} file) will be
-put into the current build directory. However, if the option
-@code{subdir-objects} is in effect in the current directory then the
-@file{.o} file will be put into the subdirectory named after the source
-file. For instance, with @code{subdir-objects} enabled,
+By default the output file (on Unix systems, the @file{.o} file) will
+be put into the current build directory. However, if the option
+@option{subdir-objects} is in effect in the current directory then the
+@file{.o} file will be put into the subdirectory named after the
+source file. For instance, with @option{subdir-objects} enabled,
@file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
people prefer this mode of operation. You can specify
-@code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
+@option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
@cindex Subdirectory, objects in
@cindex Objects in subdirectory
configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
variable. If you intend to conditionally compile source files and use
@file{configure} to substitute the appropriate object names into, e.g.,
-@samp{_LDADD} (see below), then you should list the corresponding source
-files in the @samp{EXTRA_} variable.
+@code{_LDADD} (see below), then you should list the corresponding source
+files in the @code{EXTRA_} variable.
-This variable also supports @samp{dist_} and @samp{nodist_} prefixes.
-For instance @samp{nodist_EXTRA_maude_SOURCES} would list extra
+This variable also supports @code{dist_} and @code{nodist_} prefixes.
+For instance @code{nodist_EXTRA_maude_SOURCES} would list extra
sources that may need to be built, but should not be distributed.
@item maude_AR
-A static library is created by default by invoking @code{$(AR)
+A static library is created by default by invoking @samp{$(AR)
$(ARFLAGS)} followed by the name of the library and then the objects
being put into the library. You can override this by setting the
-@samp{_AR} variable. This is usually used with C++; some C++
+@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++
compiler likes this variable set like so:
@end example
@item maude_LIBADD
-Extra objects can be added to a @emph{library} using the @samp{_LIBADD}
+Extra objects can be added to a @emph{library} using the @code{_LIBADD}
variable. For instance this should be used for objects determined by
-@code{configure} (@pxref{A Library}).
+@command{configure} (@pxref{A Library}).
In the case of libtool libraries, @code{maude_LIBADD} can also refer
to other libtool libraries.
@item maude_LDADD
Extra objects (@file{*.$(OBJDIR)}) and libraries (@file{*.a},
@file{*.la}) can be added to a @emph{program} by listing them in the
-@samp{_LDADD} variable. For instance this should be used for objects
-determined by @code{configure} (@pxref{Linking}).
+@code{_LDADD} variable. For instance this should be used for objects
+determined by @command{configure} (@pxref{Linking}).
-@samp{_LDADD} and @samp{_LIBADD} are inappropriate for passing
-program-specific linker flags (except for @samp{-l}, @samp{-L},
-@samp{-dlopen} and @samp{-dlpreopen}). Use the @samp{_LDFLAGS} variable
+@code{_LDADD} and @code{_LIBADD} are inappropriate for passing
+program-specific linker flags (except for @option{-l}, @option{-L},
+@option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
for this purpose.
For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
@item maude_LIBTOOLFLAGS
This variable is used to pass extra options to @command{libtool}.
It overrides the global @code{AM_LIBTOOLFLAGS} variable.
-These options are output before @command{libtool}'s @code{--mode=MODE}
+These options are output before @command{libtool}'s @option{--mode=@var{MODE}}
option, so they should not be mode-specific options (those belong to
the compiler or linker flags). @xref{Libtool Flags}.
@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
-using the @samp{_DEPENDENCIES} variable. Each program depends on the
+using the @code{_DEPENDENCIES} variable. Each program depends on the
contents of such a variable, but no further interpretation is done.
-If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
-The automatically-assigned value is the contents of @samp{_LDADD} or
-@samp{_LIBADD}, with most configure substitutions, @samp{-l}, @samp{-L},
-@samp{-dlopen} and @samp{-dlpreopen} options removed. The configure
+If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
+The automatically-assigned value is the contents of @code{_LDADD} or
+@code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
+@option{-dlopen} and @option{-dlpreopen} options removed. The configure
substitutions that are left in are only @samp{$(LIBOBJS)} and
@samp{$(ALLOCA)}; these are left because it is known that they will not
-cause an invalid value for @samp{_DEPENDENCIES} to be generated.
+cause an invalid value for @code{_DEPENDENCIES} to be generated.
@item maude_LINK
You can override the linker on a per-program basis. By default the
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 @samp{_LINK} variable must hold the name of a
+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.
Note that the name of the underlying program is @emph{not} passed to
-@samp{_LINK}; typically one uses @samp{$@@}:
+@code{_LINK}; typically one uses @samp{$@@}:
@example
maude_LINK = $(CCLD) -magic -o $@@
When using a per-target compilation flag, Automake will choose a
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 @samp{_CFLAGS} variable is set, then the
+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
with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
the flags variable is @emph{not} automatically included in the
compilation (however, the user form of the variable @emph{is} included).
So for instance, if you want the hypothetical @file{maude} compilations
-to also use the value of @samp{AM_CFLAGS}, you would need to write:
+to also use the value of @code{AM_CFLAGS}, you would need to write:
@example
maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
@end example
@xref{Flag Variables Ordering}, for more discussion about the
-interaction between user variables, @code{AM_} shadow variables, and
+interaction between user variables, @samp{AM_} shadow variables, and
per-target variables.
@item maude_SHORTNAME
historical reasons.)
For example if you have the following somewhere in your
-@file{Makefile.am} with no corresponding @samp{libfoo_a_SOURCES}:
+@file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
@example
lib_LIBRARIES = libfoo.a sub/libc++.a
@vindex LTALLOCA
@vindex ALLOCA
-The @code{$(LIBOBJS)} and @code{$(ALLOCA)} variables list object
+The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
files that should be compiled into the project to provide an
implementation for functions that are missing or broken on the host
system. They are substituted by @file{configure}.
@code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
-populate @code{$(LIBOBJS)}.
+populate @samp{$(LIBOBJS)}.
@acindex AC_LIBSOURCE
Using these variables is very similar to doing conditional compilation
using @code{AC_SUBST} variables, as described in @ref{Conditional
-Sources}. That is, when building a program, @code{$(LIBOBJS)} and
-@code{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
+Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
+@samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
variable, or to the @samp{*_LIBADD} variable when building a library.
However there is no need to list the corresponding sources in
-@code{EXTRA_*_SOURCES} nor to define @code{*_DEPENDENCIES}. Automake
-automatically adds @code{$(LIBOBJS)} and @code{$(ALLOCA)} to the
+@samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
+automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
dependencies, and it will discover the list of corresponding source
files automatically (by tracing the invocations of the
@code{AC_LIBSOURCE} Autoconf macros).
The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
of these object files are to be found in the @file{lib/} directory.
Automake does not yet use this information; it knows the source files
-are expected to be in the directory where the @code{$(LIBOBJS)} and
-@code{$(ALLOCA)} variables are used.
+are expected to be in the directory where the @samp{$(LIBOBJS)} and
+@samp{$(ALLOCA)} variables are used.
The @file{lib/} directory should therefore contain @file{malloc.c},
@file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
also include extra functions, specific to the project, in that
library: they are simply added on the @code{_SOURCES} line.
-@cindex Empty libraries and @code{$(LIBOBJS)}
-@cindex @code{$(LIBOBJS)} and empty libraries
-There is a small trap here, though: @code{$(LIBOBJS)} and
-@code{$(ALLOCA)} might be empty, and building an empty library is not
+@cindex Empty libraries and @samp{$(LIBOBJS)}
+@cindex @samp{$(LIBOBJS)} and empty libraries
+There is a small trap here, though: @samp{$(LIBOBJS)} and
+@samp{$(ALLOCA)} might be empty, and building an empty library is not
portable. You should ensure that there is always something to put in
@file{libcompat.a}. Most projects will also add some utility
functions in that directory, and list them in
tool2_SOURCES = @dots{}
@end example
-Please note it would be wrong to use the variables @code{$(LIBOBJS)} or
-@code{$(ALLOCA)} in @file{src/Makefile.am}, because these variables
+Please note it would be wrong to use the variables @samp{$(LIBOBJS)} or
+@samp{$(ALLOCA)} in @file{src/Makefile.am}, because these variables
contains unprefixed object names, and for instance
@file{malloc.$(OBJEXT)} is not buildable in the @file{src/} directory.
-(Actually if you try using @code{$(LIBOBJS)} in @file{src/}, Automake
+(Actually if you try using @samp{$(LIBOBJS)} in @file{src/}, Automake
will require a copy of @file{malloc.c}, @file{memcmp.c},
@file{strdup.c}, @file{alloca.c} in @file{src/} too.)
-Because @code{$(LIBOBJS)} and @code{$(ALLOCA)} contain object
-file names that end with @code{.$(OBJEXT)}, they are not suitable for
+Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
+file names that end with @samp{.$(OBJEXT)}, they are not suitable for
Libtool libraries (where the expected object extension is @file{.lo}):
@code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
@item AM_CPPFLAGS
The contents of this variable are passed to every compilation which invokes
the C preprocessor; it is a list of arguments to the preprocessor. For
-instance, @samp{-I} and @samp{-D} options should be listed here.
+instance, @option{-I} and @option{-D} options should be listed here.
-Automake already provides some @samp{-I} options automatically. In
-particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
-pointing to the directory holding @file{config.h} (if you've used
-@code{AC_CONFIG_HEADERS} or @code{AM_CONFIG_HEADER}). You can disable
-the default @samp{-I} options using the @samp{nostdinc} option.
+Automake already provides some @option{-I} options automatically. In
+particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a
+@option{-I} pointing to the directory holding @file{config.h} (if
+you've used @code{AC_CONFIG_HEADERS} or @code{AM_CONFIG_HEADER}). You
+can disable the default @option{-I} options using the
+@option{nostdinc} option.
@code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
per-library) @code{_CPPFLAGS} variable if it is defined.
@item INCLUDES
-This does the same job as @samp{AM_CPPFLAGS} (or any per-target
-@samp{_CPPFLAGS} variable if it is used). It is an older name for the
+This does the same job as @code{AM_CPPFLAGS} (or any per-target
+@code{_CPPFLAGS} variable if it is used). It is an older name for the
same functionality. This variable is deprecated; we suggest using
-@samp{AM_CPPFLAGS} and per-target @samp{_CPPFLAGS} instead.
+@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
Automake has somewhat idiosyncratic support for Yacc and Lex.
-Automake assumes that the @file{.c} file generated by @code{yacc} (or
-@code{lex}) should be named using the basename of the input file. That
-is, for a yacc source file @file{foo.y}, Automake will cause the
-intermediate file to be named @file{foo.c} (as opposed to
+Automake assumes that the @file{.c} file generated by @command{yacc}
+(or @command{lex}) should be named using the basename of the input
+file. That is, for a yacc source file @file{foo.y}, Automake will
+cause the intermediate file to be named @file{foo.c} (as opposed to
@file{y.tab.c}, which is more traditional).
The extension of a yacc source file is used to determine the extension
-of the resulting @samp{C} or @samp{C++} file. Files with the extension
-@samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
-become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
-@samp{.cxx}.
+of the resulting C or C++ file. Files with the extension @file{.y}
+will be turned into @file{.c} files; likewise, @file{.yy} will become
+@file{.cc}; @file{.y++}, @file{c++}; and @file{.yxx}, @file{.cxx}.
-Likewise, lex source files can be used to generate @samp{C} or
-@samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
-@samp{.lxx} are recognized.
+Likewise, lex source files can be used to generate C or C++; the
+extensions @file{.l}, @file{.ll}, @file{.l++}, and @file{.lxx} are
+recognized.
-You should never explicitly mention the intermediate (@samp{C} or
-@samp{C++}) file in any @samp{SOURCES} variable; only list the source
-file.
+You should never explicitly mention the intermediate (C or C++) file
+in any @code{SOURCES} variable; only list the source file.
-The intermediate files generated by @code{yacc} (or @code{lex}) will be
-included in any distribution that is made. That way the user doesn't
-need to have @code{yacc} or @code{lex}.
+The intermediate files generated by @command{yacc} (or @command{lex})
+will be included in any distribution that is made. That way the user
+doesn't need to have @command{yacc} or @command{lex}.
-If a @code{yacc} source file is seen, then your @file{configure.ac} must
-define the variable @samp{YACC}. This is most easily done by invoking
-the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
+If a @command{yacc} source file is seen, then your @file{configure.ac} must
+define the variable @code{YACC}. This is most easily done by invoking
+the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
Program Checks, autoconf, The Autoconf Manual}).
@vindex YFLAGS
@vindex AM_YFLAGS
-When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
-@samp{AM_YFLAGS}. The former is a user variable and the latter is
+When @code{yacc} is invoked, it is passed @code{YFLAGS} and
+@code{AM_YFLAGS}. The former is a user variable and the latter is
intended for the @file{Makefile.am} author.
-@samp{AM_YFLAGS} is usually used to pass the @code{-d} option to
-@code{yacc}. Automake knows what this means and will automatically
+@code{AM_YFLAGS} is usually used to pass the @option{-d} option to
+@command{yacc}. Automake knows what this means and will automatically
adjust its rules to update and distribute the header file built by
-@code{yacc -d}. What Automake cannot guess, though, is where this
+@samp{yacc -d}. What Automake cannot guess, though, is where this
header will be used: it is up to you to ensure the header gets built
before it is first used. Typically this is necessary in order for
dependency tracking to work when the header is included by another
foo_SOURCES = @dots{} parser.y @dots{}
@end example
-If a @code{lex} source file is seen, then your @file{configure.ac}
-must define the variable @samp{LEX}. You can use @samp{AC_PROG_LEX}
+If a @command{lex} source file is seen, then your @file{configure.ac}
+must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
to do this (@pxref{Particular Programs, , Particular Program Checks,
autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
(@pxref{Macros}) is recommended.
@vindex LFLAGS
@vindex AM_LFLAGS
-When @code{lex} is invoked, it is passed @samp{LFLAGS} and
-@samp{AM_LFLAGS}. The former is a user variable and the latter is
+When @command{lex} is invoked, it is passed @code{LFLAGS} and
+@code{AM_LFLAGS}. The former is a user variable and the latter is
intended for the @file{Makefile.am} author.
When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
@cindex @command{lex}, multiple lexers
-Automake makes it possible to include multiple @code{yacc} (or
-@code{lex}) source files in a single program. When there is more than
-one distinct @code{yacc} (or @code{lex}) source file in a directory,
-Automake uses a small program called @code{ylwrap} to run @code{yacc}
-(or @code{lex}) in a subdirectory. This is necessary because yacc's
-output file name is fixed, and a parallel make could conceivably invoke
-more than one instance of @code{yacc} simultaneously. The
-@code{ylwrap} program is distributed with Automake. It should appear
-in the directory specified by @samp{AC_CONFIG_AUX_DIR}, or one of its
-default locations (@pxref{Input, , Finding `configure' Input,
-autoconf, The Autoconf Manual}).
+Automake makes it possible to include multiple @command{yacc} (or
+@command{lex}) source files in a single program. When there is more
+than one distinct @command{yacc} (or @command{lex}) source file in a
+directory, Automake uses a small program called @command{ylwrap} to run
+@command{yacc} (or @command{lex}) in a subdirectory. This is
+necessary because yacc's output file name is fixed, and a parallel
+make could conceivably invoke more than one instance of @command{yacc}
+simultaneously. The @command{ylwrap} program is distributed with
+Automake. It should appear in the directory specified by
+@code{AC_CONFIG_AUX_DIR}, or one of its default locations
+(@pxref{Input, , Finding `configure' Input, autoconf, The Autoconf
+Manual}).
-For @code{yacc}, simply managing locking is insufficient. The output of
-@code{yacc} always uses the same symbol names internally, so it isn't
-possible to link two @code{yacc} parsers into the same executable.
+For @command{yacc}, simply managing locking is insufficient. The output of
+@command{yacc} always uses the same symbol names internally, so it isn't
+possible to link two @command{yacc} parsers into the same executable.
-We recommend using the following renaming hack used in @code{gdb}:
+We recommend using the following renaming hack used in @command{gdb}:
@example
#define yymaxdepth c_maxdepth
#define yyparse c_parse
@end example
For each define, replace the @samp{c_} prefix with whatever you like.
-These defines work for @code{bison}, @code{byacc}, and traditional
-@code{yacc}s. If you find a parser generator that uses a symbol not
-covered here, please report the new name so it can be added to the list.
+These defines work for @command{bison}, @command{byacc}, and
+traditional @code{yacc}s. If you find a parser generator that uses a
+symbol not covered here, please report the new name so it can be added
+to the list.
@node C++ Support
Automake includes full support for C++.
Any package including C++ code must define the output variable
-@samp{CXX} in @file{configure.ac}; the simplest way to do this is to use
+@code{CXX} in @file{configure.ac}; the simplest way to do this is to use
the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
Program Checks, autoconf, The Autoconf Manual}).
@vindex AM_CPPFLAGS
The variable @code{CCAS} holds the name of the compiler used to build
assembly code. This compiler must work a bit like a C compiler; in
-particular it must accept @samp{-c} and @samp{-o}. The values of
+particular it must accept @option{-c} and @option{-o}. The values of
@code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
definition) is passed to the compilation. For preprocessed files,
@code{CPPFLAGS} and @code{AM_CPPFLAGS} are also used.
flags), but you are free to define these variables by other means.
Only the suffixes @file{.s} and @file{.S} are recognized by
-@code{automake} as being files containing assembly code.
+@command{automake} as being files containing assembly code.
@node Fortran 77 Support
Automake includes full support for Fortran 77.
Any package including Fortran 77 code must define the output variable
-@samp{F77} in @file{configure.ac}; the simplest way to do this is to use
+@code{F77} in @file{configure.ac}; the simplest way to do this is to use
the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
Program Checks, autoconf, The Autoconf Manual}).
@uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
addresses all of these inter-language issues, and runs under nearly all
Fortran 77, C and C++ compilers on nearly all platforms. However,
-@code{cfortran} is not yet Free Software, but it will be in the next
+@command{cfortran} is not yet Free Software, but it will be in the next
major release.}.
@page
source code.
@item
-Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
-@samp{-l}) to pass to the automatically selected linker in order to link
+Automatic selection of the appropriate linker flags (e.g. @option{-L} and
+@option{-l}) to pass to the automatically selected linker in order to link
in the appropriate Fortran 77 intrinsic and run-time libraries.
@cindex @code{FLIBS}, defined
@file{configure.ac}, and that either @code{$(FLIBS)}
appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
(for shared libraries) variables. It is the responsibility of the
-person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
+person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
appears in the appropriate @code{_LDADD} or
@code{_LIBADD} variable.
@end example
In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
-is mentioned in @file{configure.ac}. Also, if @code{$(FLIBS)} hadn't
+is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
Automake would have issued a warning.
Automake includes full support for Fortran 9x.
Any package including Fortran 9x code must define the output variable
-@samp{FC} in @file{configure.ac}; the simplest way to do this is to use
+@code{FC} in @file{configure.ac}; the simplest way to do this is to use
the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
Program Checks, autoconf, The Autoconf Manual}).
@cindex Java support
@cindex Support for Java
-Automake includes support for compiled Java, using @code{gcj}, the Java
+Automake includes support for compiled Java, using @command{gcj}, the Java
front end to the GNU Compiler Collection.
Any package including Java code to be compiled must define the output
-variable @samp{GCJ} in @file{configure.ac}; the variable @samp{GCJFLAGS}
+variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
must also be defined somehow (either in @file{configure.ac} or
@file{Makefile.am}). The simplest way to do this is to use the
@code{AM_PROG_GCJ} macro.
@vindex GCJFLAGS
By default, programs including Java source files are linked with
-@code{gcj}.
+@command{gcj}.
-As always, the contents of @samp{AM_GCJFLAGS} are passed to every
-compilation invoking @code{gcj} (in its role as an ahead-of-time
+As always, the contents of @code{AM_GCJFLAGS} are passed to every
+compilation invoking @command{gcj} (in its role as an ahead-of-time
compiler, when invoking it to create @file{.class} files,
-@samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
-options to @code{gcj} from @file{Makefile.am}, this variable, and not
-the user variable @samp{GCJFLAGS}, should be used.
+@code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
+options to @command{gcj} from @file{Makefile.am}, this variable, and not
+the user variable @code{GCJFLAGS}, should be used.
@vindex AM_GCJFLAGS
-@code{gcj} can be used to compile @file{.java}, @file{.class},
+@command{gcj} can be used to compile @file{.java}, @file{.class},
@file{.zip}, or @file{.jar} files.
-When linking, @code{gcj} requires that the main class be specified
-using the @samp{--main=} option. The easiest way to do this is to use
+When linking, @command{gcj} requires that the main class be specified
+using the @option{--main=} option. The easiest way to do this is to use
the @code{_LDFLAGS} variable for the program.
@opindex ansi2knr
If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
-(@pxref{Options}) contains the option @code{ansi2knr} then code to
+(@pxref{Options}) contains the option @option{ansi2knr} then code to
handle de-ANSI-fication is inserted into the generated
@file{Makefile.in}.
This causes each C source file in the directory to be treated as ANSI C@.
If an ANSI C compiler is available, it is used. If no ANSI C compiler
-is available, the @code{ansi2knr} program is used to convert the source
+is available, the @command{ansi2knr} program is used to convert the source
files into K&R C, which is then compiled.
-The @code{ansi2knr} program is simple-minded. It assumes the source
-code will be formatted in a particular way; see the @code{ansi2knr} man
+The @command{ansi2knr} program is simple-minded. It assumes the source
+code will be formatted in a particular way; see the @command{ansi2knr} man
page for details.
@acindex AM_C_PROTOTYPES
@file{configure.ac} must call the macro @code{AM_C_PROTOTYPES}
(@pxref{Macros}).
-Automake also handles finding the @code{ansi2knr} support files in some
+Automake also handles finding the @command{ansi2knr} support files in some
other directory in the current package. This is done by prepending the
-relative path to the appropriate directory to the @code{ansi2knr}
+relative path to the appropriate directory to the @command{ansi2knr}
option. For instance, suppose the package has ANSI C code in the
@file{src} and @file{lib} subdirectories. The files @file{ansi2knr.c} and
@file{ansi2knr.1} appear in @file{lib}. Then this could appear in
Note that automatic de-ANSI-fication will not work when the package is
being built for a different host architecture. That is because automake
-currently has no way to build @code{ansi2knr} for the build machine.
+currently has no way to build @command{ansi2knr} for the build machine.
@c FIXME: this paragraph might be better moved to an `upgrading' section.
@cindex @code{LTLIBOBJS} and @code{ansi2knr}
@cindex @code{ansi2knr} and @code{LTLIBOBJS}
@cindex @code{ansi2knr} and @code{LIBOBJS}
Using @code{LIBOBJS} with source de-ANSI-fication used to require
-hand-crafted code in @file{configure} to append @code{$U} to basenames
+hand-crafted code in @file{configure} to append @samp{$U} to basenames
in @code{LIBOBJS}. This is no longer true today. Starting with version
2.54, Autoconf takes care of rewriting @code{LIBOBJS} and
@code{LTLIBOBJS}. (@pxref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ}
@cindex Dependency tracking
@cindex Automatic dependency tracking
-Automake always uses complete dependencies for a compilation, including
-system headers. Automake's model is that dependency computation should
-be a side effect of the build. To this end, dependencies are computed
-by running all compilations through a special wrapper program called
-@code{depcomp}. @code{depcomp} understands how to coax many different C
-and C++ compilers into generating dependency information in the format
-it requires. @code{automake -a} will install @code{depcomp} into your
-source tree for you. If @code{depcomp} can't figure out how to properly
+Automake always uses complete dependencies for a compilation,
+including system headers. Automake's model is that dependency
+computation should be a side effect of the build. To this end,
+dependencies are computed by running all compilations through a
+special wrapper program called @command{depcomp}. @command{depcomp}
+understands how to coax many different C and C++ compilers into
+generating dependency information in the format it requires.
+@samp{automake -a} will install @command{depcomp} into your source
+tree for you. If @command{depcomp} can't figure out how to properly
invoke your compiler, dependency tracking will simply be disabled for
your build.
time.
Automatic dependency tracking can be suppressed by putting
-@code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
-passing @code{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
-(this should be the preferred way). Or, you can invoke @code{automake}
-with the @code{-i} option. Dependency tracking is enabled by default.
+@option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
+passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
+(this should be the preferred way). Or, you can invoke @command{automake}
+with the @option{-i} option. Dependency tracking is enabled by default.
@vindex AUTOMAKE_OPTIONS
@opindex no-dependencies
The person building your package also can choose to disable dependency
-tracking by configuring with @code{--disable-dependency-tracking}.
+tracking by configuring with @option{--disable-dependency-tracking}.
@cindex Disabling dependency tracking
@cindex Dependency tracking, disabling
@cindex Windows
On some platforms, such as Windows, executables are expected to have an
-extension such as @samp{.exe}. On these platforms, some compilers (GCC
+extension such as @file{.exe}. On these platforms, some compilers (GCC
among them) will automatically generate @file{foo.exe} when asked to
generate @file{foo}.
@end example
The targets Automake generates are likewise given the @samp{$(EXEEXT)}
-extension. @code{EXEEXT}
+extension.
-However, Automake cannot apply this rewriting to @code{configure}
+However, Automake cannot apply this rewriting to @command{configure}
substitutions. This means that if you are conditionally building a
program using such a substitution, then your @file{configure.ac} must
take care to add @samp{$(EXEEXT)} when constructing the output variable.
Unfortunately, due to the change in Autoconf 2.50, this means you must
always add this extension. However, this is a problem for maintainers
who know their package will never run on a platform that has
-executable extensions. For those maintainers, the @code{no-exeext}
+executable extensions. For those maintainers, the @option{no-exeext}
option (@pxref{Options}) will disable this feature. This works in a
-fairly ugly way; if @code{no-exeext} is seen, then the presence of a
+fairly ugly way; if @option{no-exeext} is seen, then the presence of a
rule for a target named @code{foo} in @file{Makefile.am} will override
-an automake-generated rule for @code{foo$(EXEEXT)}. Without
-the @code{no-exeext} option, this use will give a diagnostic.
+an automake-generated rule for @samp{foo$(EXEEXT)}. Without
+the @option{no-exeext} option, this use will give a diagnostic.
@node Other objects
@vindex _SCRIPTS
It is possible to define and install programs which are scripts. Such
-programs are listed using the @samp{SCRIPTS} primary name. Automake
+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.
@vindex SCRIPTS
Automake does not assume that scripts are derived objects; such objects
must be deleted by hand (@pxref{Clean}).
-The @code{automake} program itself is a Perl script that is generated
+The @command{automake} program itself is a Perl script that is generated
from @file{automake.in}. Here is how this is handled:
@example
specified using a @code{dist_} prefix as in other primaries. For
instance the following @file{Makefile.am} declares that
@file{my_script} should be distributed and installed in
-@code{$(sbindir)}.
+@samp{$(sbindir)}.
@example
dist_sbin_SCRIPTS = my_script
Scripts that need not being installed can be listed in
@code{noinst_SCRIPTS}, and among them, those which are needed only by
-@code{make check} should go in @code{check_SCRIPTS}.
+@samp{make check} should go in @code{check_SCRIPTS}.
@node Headers
Header files that must be installed are specified by the
-@samp{HEADERS} family of variables. Headers can be installed in
+@code{HEADERS} family of variables. Headers can be installed in
@code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
other directory you may have defined (@pxref{Uniform}). For instance
will install the two files as @file{$(includedir)/foo.h} and
@file{$(includedir)/bar.h}.
-The @samp{nobase_} prefix is also supported,
+The @code{nobase_} prefix is also supported,
@example
nobase_include_HEADERS = foo.h bar/bar.h
not installed. The @code{noinst_HEADERS} variable can be used for
such headers. However when the header actually belongs to one
convenient library or program, we recommend listing it in the
-program's or library's @samp{_SOURCES} variable (@pxref{Program
+program's or library's @code{_SOURCES} variable (@pxref{Program
Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
right variable to use in a directory containing only headers and no
associated library or program.
-All header files must be listed somewhere; in a @samp{_SOURCES}
-variable or in a @samp{_HEADERS} variable. Missing ones will not
+All header files must be listed somewhere; in a @code{_SOURCES}
+variable or in a @code{_HEADERS} variable. Missing ones will not
appear in the distribution.
For header files that are built and must not be distributed, use the
-@samp{nodist_} prefix as in @code{nodist_include_HEADERS} or
+@code{nodist_} prefix as in @code{nodist_include_HEADERS} or
@code{nodist_prog_SOURCES}. If these generated headers are needed
during the build, you must also ensure they exist before they are
used (@pxref{Sources}).
@vindex _DATA
Automake supports the installation of miscellaneous data files using the
-@samp{DATA} family of variables.
+@code{DATA} family of variables.
@vindex DATA
@vindex data_DATA
@code{pkgdatadir}.
By default, data files are @emph{not} included in a distribution. Of
-course, you can use the @samp{dist_} prefix to change this on a
+course, you can use the @code{dist_} prefix to change this on a
per-variable basis.
Here is how Automake declares its auxiliary data files:
sources: they preexist and do not need to be built. Suppose that
@file{foo.c} includes @file{foo.h}. When it first compiles
@file{foo.o}, @command{make} only knows that @file{foo.o} depends on
-@file{foo.c}. As a side-effect of this compilation @code{depcomp}
+@file{foo.c}. As a side-effect of this compilation @command{depcomp}
records the @file{foo.h} dependency so that following invocations of
@command{make} will honor it. In these conditions, it's clear there is
no problem: either @file{foo.o} doesn't exist and has to be built
@cindex @code{BUILT_SOURCES}, defined
The @code{BUILT_SOURCES} variable is a workaround for this problem. A
-source file listed in @code{BUILT_SOURCES} is made on @code{make all}
-or @code{make check} (or even @code{make install}) before other
+source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
+or @samp{make check} (or even @samp{make install}) before other
targets are processed. However, such a source file is not
@emph{compiled} unless explicitly requested by mentioning it in some
-other @samp{_SOURCES} variable.
+other @code{_SOURCES} variable.
So, to conclude our introductory example, we could use
-@code{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
-any other target (including @file{foo.o}) during @code{make all} or
-@code{make check}.
+@samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
+any other target (including @file{foo.o}) during @samp{make all} or
+@samp{make check}.
@code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
must be created early in the build process can be listed in this
object.
It might be important to emphasize that @code{BUILT_SOURCES} is
-honored only by @code{make all}, @code{make check} and @code{make
+honored only by @samp{make all}, @samp{make check} and @samp{make
install}. This means you cannot build a specific target (e.g.,
-@code{make foo}) in a clean tree if it depends on a built source.
-However it will succeed if you have run @code{make all} earlier,
+@samp{make foo}) in a clean tree if it depends on a built source.
+However it will succeed if you have run @samp{make all} earlier,
because accurate dependencies are already available.
The next section illustrates and discusses the handling of built sources
In this example @file{bindir.h} is not distributed, not installed, and
it is not even being built on-time. One may wonder what the
-@code{nodist_foo_SOURCES = bindir.h} line has any use at all. This
+@samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
line simply states that @file{bindir.h} is a source of @code{foo}, so
for instance it should be inspected while generating tags
(@pxref{Tags}). In other words, it does not help our present problem,
However, as said earlier, @code{BUILT_SOURCES} applies only to the
@code{all}, @code{check}, and @code{install} targets. It still fails
-if you try to run @code{make foo} explicitly:
+if you try to run @samp{make foo} explicitly:
@example
% make clean
@unnumberedsubsec Recording dependencies manually
Usually people are happy enough with @code{BUILT_SOURCES} because they
-never build targets such as @code{make foo} before @code{make all}, as
+never build targets such as @samp{make foo} before @samp{make all}, as
in the previous example. However if this matters to you, you can
avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
the @file{Makefile.am}.
echo '#define bindir "$(bindir)"' >$@@
@end example
-You don't have to list @emph{all} the dependencies of @code{foo.o}
+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
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 recorded
-the dependency between @code{foo.o} and @code{bindir.h}; so our explicit
-dependency is really useful to the first build only.)
+recorded by the normal dependency tracking code. (Note that after
+this first compilation the dependency tracking code will also have
+recorded the dependency between @file{foo.o} and
+@file{bindir.h}; so our explicit dependency is really useful to
+the first build only.)
Adding explicit dependencies like this can be a bit dangerous if you are
not careful enough. This is due to the way Automake tries not to
overwrite your rules (it assumes you know better than it).
-@code{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
-output to build @code{foo.$(OBJEXT)}. It happens to work in this case
-because Automake doesn't have to output any @code{foo.$(OBJEXT):}
-target: it relies on a suffix rule instead (i.e., @code{.c.$(OBJEXT):}).
+@samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
+output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
+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.
@unnumberedsubsec Build @file{bindir.h} from @file{configure}
There is no panacea, of course. Each solution has its merits and
drawbacks.
-You cannot use @code{BUILT_SOURCES} if the ability to run @code{make
+You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
foo} on a clean tree is important to you.
You won't add explicit dependencies if you are leery of overriding
@vindex lisp_LISP
@vindex noinst_LISP
-Automake provides some support for Emacs Lisp. The @samp{LISP} primary
+Automake provides some support for Emacs Lisp. The @code{LISP} primary
is used to hold a list of @file{.el} files. Possible prefixes for this
-primary are @samp{lisp_} and @samp{noinst_}. Note that if
+primary are @code{lisp_} and @code{noinst_}. Note that if
@code{lisp_LISP} is defined, then @file{configure.ac} must run
@code{AM_PATH_LISPDIR} (@pxref{Macros}).
@section Libtool
Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
-libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
+libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
@xref{A Shared Library}.
@cindex Primary variable, @code{JAVA}
Automake provides some minimal support for Java compilation with the
-@samp{JAVA} primary.
+@code{JAVA} primary.
-Any @file{.java} files listed in a @samp{_JAVA} variable will be
+Any @file{.java} files listed in a @code{_JAVA} variable will be
compiled with @code{JAVAC} at build time. By default, @file{.java}
files are not included in the distribution, you should use the
@code{dist_} prefix to distribute them.
@cindex @code{JAVA} restrictions
@cindex Restrictions for @code{JAVA}
-Currently Automake enforces the restriction that only one @samp{_JAVA}
+Currently Automake enforces the restriction that only one @code{_JAVA}
primary can be used in a given @file{Makefile.am}. The reason for this
restriction is that, in general, it isn't possible to know which
@file{.class} files were generated from which @file{.java} files, so
compiler flags into @file{Makefile.am}.
@item JAVAROOT
-The value of this variable is passed to the @samp{-d} option to
+The value of this variable is passed to the @option{-d} option to
@code{javac}. It defaults to @samp{$(top_builddir)}.
@item CLASSPATH_ENV
This variable is an @code{sh} expression which is used to set the
-@code{CLASSPATH} environment variable on the @code{javac} command line.
+@env{CLASSPATH} environment variable on the @code{javac} command line.
(In the future we will probably handle class path setting differently.)
@end vtable
@cindex Primary variable, @code{PYTHON}
@vindex _PYTHON
-Automake provides support for Python compilation with the @samp{PYTHON}
+Automake provides support for Python compilation with the @code{PYTHON}
primary.
-Any files listed in a @samp{_PYTHON} variable will be byte-compiled with
-@code{py-compile} at install time. @code{py-compile} actually creates
-both standard (@file{.pyc}) and byte-compiled (@file{.pyo}) versions of
-the source files. Note that because byte-compilation occurs at install
-time, any files listed in @samp{noinst_PYTHON} will not be compiled.
-Python source files are included in the distribution by default.
+Any files listed in a @code{_PYTHON} variable will be byte-compiled
+with @command{py-compile} at install time. @command{py-compile}
+actually creates both standard (@file{.pyc}) and byte-compiled
+(@file{.pyo}) versions of the source files. Note that because
+byte-compilation occurs at install time, any files listed in
+@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
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
-variables: @samp{python_PYTHON}, @samp{pkgpython_PYTHON},
-@samp{pyexecdir_PYTHON}, @samp{pkgpyexecdir_PYTHON}, depending where you
+variables: @code{python_PYTHON}, @code{pkgpython_PYTHON},
+@code{pyexecdir_PYTHON}, @code{pkgpyexecdir_PYTHON}, depending where you
want your files installed.
@defmac AM_PATH_PYTHON ([@var{VERSION}], [@var{ACTION-IF-FOUND}], [@var{ACTION-IF-NOT-FOUND}])
@vtable @code
@item PYTHON
-The name of the Python executable, or @code{:} if no suitable
+The name of the Python executable, or @samp{:} if no suitable
interpreter could be found.
Assuming @var{ACTION-IF-NOT-FOUND} is used (otherwise @file{./configure}
@item PYTHON_VERSION
The Python version number, in the form @var{major}.@var{minor}
(e.g. @samp{1.5}). This is currently the value of
-@code{sys.version[:3]}.
+@samp{sys.version[:3]}.
@item PYTHON_PREFIX
-The string @code{$@{prefix@}}. This term may be used in future work
-which needs the contents of Python's @code{sys.prefix}, but general
+The string @samp{$@{prefix@}}. This term may be used in future work
+which 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 @code{$@{exec_prefix@}}. This term may be used in future work
-which needs the contents of Python's @code{sys.exec_prefix}, but general
+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
consensus is to always use the value from configure.
@item PYTHON_PLATFORM
The canonical name used by Python to describe the operating system, as
-given by @code{sys.platform}. This value is sometimes needed when
+given by @samp{sys.platform}. This value is sometimes needed when
building Python extensions.
@item pythondir
@end vtable
All these directory variables have values that start with either
-@code{$@{prefix@}} or @code{$@{exec_prefix@}} unexpanded. This works
+@samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
fine in @file{Makefiles}, but it makes these variables hard to use in
@file{configure}. This is mandated by the GNU coding standards, so
-that the user can run @code{make prefix=/foo install}. The Autoconf
+that the user can run @samp{make prefix=/foo install}. The Autoconf
manual has a section with more details on this topic
(@pxref{Installation Directory Variables, , Installation Directory
Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
@vindex info_TEXINFOS
If the current directory contains Texinfo source, you must declare it
-with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
+with the @code{TEXINFOS} primary. Generally Texinfo files are converted
into info, and thus the @code{info_TEXINFOS} variable is most commonly used
here. Any Texinfo source file must end in the @file{.texi},
@file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
Automake generates rules to build @file{.info}, @file{.dvi},
@file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
sources. Following the GNU Coding Standards, only the @file{.info}
-files are built by @code{make all} and installed by @code{make
-install} (unless you use @code{no-installinfo}, see below).
+files are built by @samp{make all} and installed by @samp{make
+install} (unless you use @option{no-installinfo}, see below).
Furthermore, @file{.info} files are automatically distributed so that
Texinfo is not a prerequisite for installing your package.
@trindex install-html
@trindex install-pdf
@trindex install-ps
-Other documentation formats can be built on request by @code{make
-dvi}, @code{make ps}, @code{make pdf} and @code{make html}, and they
-can be installed with @code{make install-dvi}, @code{make install-ps},
-@code{make install-pdf} and @code{make install-html} explicitly.
-@code{make uninstall} will remove everything: the Texinfo
+Other documentation formats can be built on request by @samp{make
+dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
+can be installed with @samp{make install-dvi}, @samp{make install-ps},
+@samp{make install-pdf} and @samp{make install-html} explicitly.
+@samp{make uninstall} will remove everything: the Texinfo
documentation installed by default as well as all the above optional
formats.
-All these targets can be extended using @code{-local} rules
+All these targets can be extended using @samp{-local} rules
(@pxref{Extending}).
@cindex Texinfo flag, @code{VERSION}
was last modified.
@end table
-The @file{version.texi} support requires the @code{mdate-sh} program;
-this program is supplied with Automake and automatically included when
-@code{automake} is invoked with the @code{--add-missing} option.
+The @file{version.texi} support requires the @command{mdate-sh}
+script; this script is supplied with Automake and automatically
+included when @command{automake} is invoked with the
+@option{--add-missing} option.
If you have multiple Texinfo files, and you want to use the
@file{version.texi} feature, then you have to have a separate version
file for each Texinfo file. Automake will treat any include in a
-Texinfo file that matches @samp{vers*.texi} just as an automatically
+Texinfo file that matches @file{vers*.texi} just as an automatically
generated version file.
Sometimes an info file actually depends on more than one @file{.texi}
@code{AC_CONFIG_AUX_DIR} in @file{configure.ac} (@pxref{Input, , Finding
`configure' Input, autoconf, The Autoconf Manual}), then
@file{texinfo.tex} is looked for there. Automake supplies
-@file{texinfo.tex} if @samp{--add-missing} is given.
+@file{texinfo.tex} if @option{--add-missing} is given.
@opindex no-texinfo.tex
-The option @samp{no-texinfo.tex} can be used to eliminate the
+The option @option{no-texinfo.tex} can be used to eliminate the
requirement for the file @file{texinfo.tex}. Use of the variable
@code{TEXINFO_TEX} is preferable, however, because that allows the
@code{dvi}, @code{ps}, and @code{pdf} targets to still work.
install}, so running @code{make install-info} is pointless. This can
be prevented via the @code{no-installinfo} option. In this case,
@file{.info} files are not installed by default, and user must
-request this explicitly using @code{make install-info}
+request this explicitly using @samp{make install-info}
The following variables are used by the Texinfo build rules.
@vtable @code
@item MAKEINFO
The name of the program invoked to build @file{.info} files. This
-variable is defined by Automake. If the @code{makeinfo} program is
+variable is defined by Automake. If the @command{makeinfo} program is
found on the system then it will be used by default; otherwise
-@code{missing} will be used instead.
+@command{missing} will be used instead.
@item MAKEINFOHTML
The command invoked to build @file{.html} files. Automake
-defines this to @code{$(MAKEINFO) --html}.
+defines this to @samp{$(MAKEINFO) --html}.
@item MAKEINFOFLAGS
-User flags passed to each invocation of @code{$(MAKEINFO)} and
-@code{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
+User flags passed to each invocation of @samp{$(MAKEINFO)} and
+@samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
not expected to be defined in any @file{Makefile}; it can be used by
users to pass extra flags to suit their needs.
@item AM_MAKEINFOFLAGS
@itemx AM_MAKEINFOHTMLFLAGS
-Maintainer flags passed to each @code{makeinfo} invocation. Unlike
+Maintainer flags passed to each @command{makeinfo} invocation. Unlike
@code{MAKEINFOFLAGS}, these variables are meant to be defined by
-maintainers in @file{Makefile.am}. @code{$(AM_MAKEINFOFLAGS)} is
+maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
passed to @code{makeinfo} when building @file{.info} files; and
-@code{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
+@samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
files.
For instance the following setting can be used to obtain one single
AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
@end example
-@code{AM_MAKEINFOHTMLFLAGS} Default to @code{$(AM_MAKEINFOFLAGS)}.
+@code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
This means that defining @code{AM_MAKEINFOFLAGS} without defining
@code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
and @file{.html} files.
@item TEXI2DVI
The name of the command that converts a @file{.texi} file into a
-@file{.dvi} file. This defaults to @code{texi2dvi}, a script that ships
+@file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
with the Texinfo package.
@item TEXI2PDF
The name of the command that translates a @file{.texi} file into a
-@file{.pdf} file. This defaults to @code{$(TEXI2DVI) --pdf --batch}.
+@file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
@item DVIPS
The name of the command that build a @file{.ps} file out of a
-@file{.dvi} file. This defaults to @code{dvips}.
+@file{.dvi} file. This defaults to @samp{dvips}.
@item TEXINFO_TEX
@vindex man_MANS
A package can also include man pages (but see the GNU standards on this
matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
-pages are declared using the @samp{MANS} primary. Generally the
+pages are declared using the @code{MANS} primary. Generally the
@code{man_MANS} variable is used. Man pages are automatically installed in
the correct subdirectory of @code{mandir}, based on the file extension.
-File extensions such as @samp{.1c} are handled by looking for the valid
+File extensions such as @file{.1c} are handled by looking for the valid
part of the extension and using that to determine the correct
subdirectory of @code{mandir}. Valid section names are the digits
@samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
suffix, e.g. @file{foo.1}, when installing the file. Automake also
supports this mode. For a valid section named @var{SECTION}, there is a
corresponding directory named @samp{man@var{SECTION}dir}, and a
-corresponding @samp{_MANS} variable. Files listed in such a variable
+corresponding @code{_MANS} variable. Files listed in such a variable
are installed in the indicated section. If the file already has a
valid suffix, then it is installed as-is; otherwise the file suffix is
changed to match the section.
installed, but the other files will keep their names.
@cindex Target, @code{install-man}
-@cindex Option, @code{noinstall-man}
+@cindex Option, @option{noinstall-man}
@cindex @code{install-man} target
-@cindex @code{noinstall-man} option
+@cindex @option{noinstall-man} option
@opindex no-installman
@trindex install-man
-@c Use @samp{make install} per documentation: (texi)code.
By default, man pages are installed by @samp{make install}. However,
since the GNU project does not require man pages, many maintainers do
not expend effort to keep the man pages up to date. In these cases, the
-@code{no-installman} option will prevent the man pages from being
+@option{no-installman} option will prevent the man pages from being
installed by default. The user can still explicitly install them via
@samp{make install-man}.
Man pages are not currently considered to be source, because it is not
uncommon for man pages to be automatically generated. Therefore they
are not automatically included in the distribution. However, this can
-be changed by use of the @samp{dist_} prefix.
+be changed by use of the @code{dist_} prefix.
-The @samp{nobase_} prefix is meaningless for man pages and is
+The @code{nobase_} prefix is meaningless for man pages and is
disallowed.
@chapter What Gets Installed
@cindex Installation support
-@cindex @code{make install} support
+@cindex @samp{make install} support
@section 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 @code{make install}.
+user runs @samp{make install}.
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
@end example
In this example, both @samp{hello} and @samp{goodbye} will be installed
-in @code{$(bindir)}.
+in @samp{$(bindir)}.
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
-them. In this situation you can use the @samp{nobase_} prefix to
+them. In this situation you can use the @code{nobase_} prefix to
suppress the base name step. For example:
@example
nobase_include_HEADERS = stdio.h sys/types.h
@end example
-Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
-in @code{$(includedir)/sys}.
+Will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
+in @samp{$(includedir)/sys}.
@section The two parts of install
Variables using the standard directory prefixes @samp{data},
@samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
@samp{pkgdata}, or @samp{pkginclude} are installed by
-@samp{install-data}.
+@code{install-data}.
Variables using the standard directory prefixes @samp{bin},
@samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
-@samp{lib}, or @samp{pkglib} are installed by @samp{install-exec}.
+@samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
-For instance @samp{data_DATA} files are installed by @samp{install-data},
-while @samp{bin_PROGRAMS} files are installed by @code{install-exec}.
+For instance @code{data_DATA} files are installed by @code{install-data},
+while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
Any variable using a user-defined directory prefix with @samp{exec} in
-the name (e.g. @samp{myexecbin_PROGRAMS}) is installed by
-@samp{install-exec}. All other user-defined prefixes are installed by
-@samp{install-data}.
+the name (e.g. @code{myexecbin_PROGRAMS}) is installed by
+@code{install-exec}. All other user-defined prefixes are installed by
+@code{install-data}.
@section Extending installation
@section Staged installs
@vindex DESTDIR
-Automake generates support for the @samp{DESTDIR} variable in all
-install rules. @samp{DESTDIR} is used during the @samp{make install}
+Automake generates support for the @code{DESTDIR} variable in all
+install rules. @code{DESTDIR} is used during the @samp{make install}
step to relocate install objects into a staging area. Each object and
-path is prefixed with the value of @samp{DESTDIR} before being copied
+path is prefixed with the value of @code{DESTDIR} before being copied
into the install area. Here is an example of typical DESTDIR usage:
@example
more information, see @ref{Makefile Conventions, , , standards, The GNU
Coding Standards}.
-Support for @samp{DESTDIR} is implemented by coding it directly into the
+Support for @code{DESTDIR} is implemented by coding it directly into the
install rules. If your @file{Makefile.am} uses a local install rule
(e.g., @code{install-exec-local}) or an install hook, then you must
-write that code to respect @samp{DESTDIR}.
+write that code to respect @code{DESTDIR}.
@section Rules for the user
@node Clean
@chapter What Gets Cleaned
-@cindex @code{make clean} support
+@cindex @samp{make clean} support
The GNU Makefile Standards specify a number of different clean rules.
@xref{Standard Targets, , Standard Targets for Users, standards,
@itemize @bullet
@item
-If @code{make} built it, and it is commonly something that one would
+If @command{make} built it, and it is commonly something that one would
want to rebuild (for instance, a @file{.o} file), then
@code{mostlyclean} should delete it.
@item
-Otherwise, if @code{make} built it, then @code{clean} should delete it.
+Otherwise, if @command{make} built it, then @code{clean} should delete it.
@item
-If @code{configure} built it, then @code{distclean} should delete it.
+If @command{configure} built it, then @code{distclean} should delete it.
@item
If the maintainer built it (for instance, a @file{.info} file), then
@code{maintainer-clean} should delete it. However
@code{maintainer-clean} should not delete anything that needs to exist
-in order to run @code{./configure && make}.
+in order to run @samp{./configure && make}.
@end itemize
We recommend that you follow this same set of heuristics in your
@section Basics of distribution
-@cindex @code{make dist}
+@cindex @samp{make dist}
@vindex PACKAGE
@vindex VERSION
@trindex dist
The @code{dist} rule in the generated @file{Makefile.in} can be used
to generate a gzip'd @code{tar} file and other flavors of archive for
-distribution. The files is named based on the @samp{PACKAGE} and
-@samp{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
+distribution. The files is named based on the @code{PACKAGE} and
+@code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
(@pxref{Macros}); more precisely the gzip'd @code{tar} file is named
@samp{@var{package}-@var{version}.tar.gz}.
@vindex GZIP_ENV
-You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
-is run. The default setting is @samp{--best}.
+You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
+is run. The default setting is @option{--best}.
@cindex @code{m4_include}, distribution
@cindex @code{include}, distribution
has a built-in list of commonly used files which are automatically
included if they are found in the current directory (either physically,
or as the target of a @file{Makefile.am} rule). This list is printed by
-@samp{automake --help}. Also, files which are read by @code{configure}
+@samp{automake --help}. Also, files which 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
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
-Automake gives fine-grained control using the @samp{dist} and
-@samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
-prefixed with @samp{dist_} to add the listed files to the distribution.
-Similarly, @samp{nodist_} can be used to omit the files from the
+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.
+Similarly, @code{nodist_} can be used to omit the files from the
distribution.
As an example, here is how you would cause some data to be distributed
@vindex distdir
@vindex top_distdir
Two variables that come handy when writing @code{dist-hook} rules are
-@code{$(distdir)} and @code{$(top_distdir)}.
+@samp{$(distdir)} and @samp{$(top_distdir)}.
-@code{$(distdir)} points to the directory where the @code{dist} rule
+@samp{$(distdir)} points to the directory where the @code{dist} rule
will copy files from the current directory before creating the
-tarball. If you are at the top-level directory, then @code{distdir =
+tarball. If you are at the top-level directory, then @samp{distdir =
$(PACKAGE)-$(VERSION)}. When used from subdirectory named
-@file{foo/}, then @code{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
-@code{$(distdir)} can be a relative or absolute path, do not assume
+@file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
+@samp{$(distdir)} can be a relative or absolute path, do not assume
any form.
-@code{$(top_distdir)} always points to the root directory of the
-distributed tree. At the top-level it's equal to @code{$(distdir)}.
+@samp{$(top_distdir)} always points to the root directory of the
+distributed tree. At the top-level it's equal to @samp{$(distdir)}.
In the @file{foo/} subdirectory
-@code{top_distdir = ../$(PACKAGE)-$(VERSION)}.
-@code{$(top_distdir)} too can be a relative or absolute path.
+@samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
+@samp{$(top_distdir)} too can be a relative or absolute path.
Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
-(@pxref{Subpackages}), then @code{$(distdir)} and
-@code{$(top_distdir)} are relative to the package where @code{make
+(@pxref{Subpackages}), then @samp{$(distdir)} and
+@samp{$(top_distdir)} are relative to the package where @samp{make
dist} was run, not to any sub-packages involved.
@section Checking the distribution
-@cindex @code{make distcheck}
-@cindex @code{make distcleancheck}
+@cindex @samp{make distcheck}
+@cindex @samp{make distcleancheck}
@vindex distcleancheck_listfiles
-@cindex @code{make distuninstallcheck}
+@cindex @samp{make distuninstallcheck}
@vindex distuninstallcheck_listfiles
@trindex distcheck
distribution is self-contained.
@vindex DISTCHECK_CONFIGURE_FLAGS
-Building the package involves running @code{./configure}. If you need
-to supply additional flags to @code{configure}, define them in the
+Building the package involves running @samp{./configure}. If you need
+to supply additional flags to @command{configure}, define them in the
@code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
-@file{Makefile.am}, or on the command line when invoking @code{make}.
+@file{Makefile.am}, or on the command line when invoking @command{make}.
@trindex distcheck-hook
If the @code{distcheck-hook} rule is defined in your top-level
standard mechanism. Note that @code{distcheck-hook} as well as
@code{DISTCHECK_CONFIGURE_FLAGS} are not honored in a subpackage
@file{Makefile.am}, but the @code{DISTCHECK_CONFIGURE_FLAGS} are
-passed down to the @code{configure} script of the subpackage.
+passed down to the @command{configure} script of the subpackage.
@trindex distcleancheck
@vindex DISTCLEANFILES
@vindex distcleancheck_listfiles
Speaking about potential distribution errors, @code{distcheck} also
ensures that the @code{distclean} rule actually removes all built
-files. This is done by running @code{make distcleancheck} at the end of
+files. This is done by running @samp{make distcleancheck} at the end of
the @code{VPATH} build. By default, @code{distcleancheck} will run
@code{distclean} and then make sure the build tree has been emptied by
-running @code{$(distcleancheck_listfiles)}. Usually this check will
+running @samp{$(distcleancheck_listfiles)}. Usually this check will
find generated files that you forgot to add to the @code{DISTCLEANFILES}
variable (@pxref{Clean}).
The @code{distcleancheck} behavior should be OK for most packages,
otherwise you have the possibility to override the definition of
either the @code{distcleancheck} rule, or the
-@code{$(distcleancheck_listfiles)} variable. For instance to disable
+@samp{$(distcleancheck_listfiles)} variable. For instance to disable
@code{distcleancheck} completely, add the following rule to your
top-level @file{Makefile.am}:
before playing with @code{distcleancheck_listfiles}.
@code{distcheck} also checks that the @code{uninstall} rule works
-properly, both for ordinary and @samp{DESTDIR} builds. It does this
-by invoking @code{make uninstall}, and then it checks the install tree
+properly, both for ordinary and @code{DESTDIR} builds. It does this
+by invoking @samp{make uninstall}, and then it checks the install tree
to see if any files are left over. This check will make sure that you
correctly coded your @code{uninstall}-related rules.
By default, the checking is done by the @code{distuninstallcheck} rule,
and the list of files in the install tree is generated by
-@code{$(distuninstallcheck_listfiles}) (this is a variable whose value is
+@samp{$(distuninstallcheck_listfiles}) (this is a variable whose value is
a shell command to run that prints the list of files to stdout).
Either of these can be overridden to modify the behavior of
@section DejaGnu Tests
-If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @samp{dejagnu}} appears in
-@code{AUTOMAKE_OPTIONS}, then a @code{dejagnu}-based test suite is
+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
-passed, one at a time, as the @code{--tool} argument to @code{runtest}
-invocations; it defaults to the name of the package.
+passed, one at a time, as the @option{--tool} argument to
+@command{runtest} invocations; it defaults to the name of the package.
-The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
-@code{--srcdir} flags that are passed to dejagnu by default; this can be
+The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
+@option{--srcdir} flags that are passed to dejagnu by default; this can be
overridden if necessary.
@vindex RUNTESTDEFAULTFLAGS
The contents of the variable @code{RUNTESTFLAGS} are passed to the
@code{runtest} invocation. This is considered a ``user variable''
-(@pxref{User Variables}). If you need to set @code{runtest} flags in
+(@pxref{User Variables}). If you need to set @command{runtest} flags in
@file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
@vindex RUNTESTFLAGS
@vindex AM_RUNTESTFLAGS
@cindex @file{site.exp}
Automake will generate rules to create a local @file{site.exp} file,
-defining various variables detected by @code{./configure}. This file
+defining various variables detected by @command{configure}. This file
is automatically read by DejaGnu. It is OK for the user of a package
to edit this file in order to tune the test suite. However this is
not the place where the test suite author should define new variables:
these automatic rebuilding rules are only enabled in maintainer mode.
@vindex ACLOCAL_AMFLAGS
-Sometimes you need to run @code{aclocal} with an argument like @code{-I}
-to tell it where to find @file{.m4} files. Since sometimes @code{make}
-will automatically run @code{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 to @code{aclocal}. This variable
-is only useful in the top-level @file{Makefile.am}.
+Sometimes you need to run @command{aclocal} with an argument like
+@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
+to @command{aclocal}. This variable is only useful in the top-level
+@file{Makefile.am}.
@vindex CONFIG_STATUS_DEPENDENCIES
@vindex CONFIGURE_DEPENDENCIES
AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
@end example
@noindent
-Note the @code{$(top_srcdir)/} in the file name. Since this variable
+Note the @samp{$(top_srcdir)/} in the file name. Since this variable
is to be used in all @file{Makefile}s, its value must be sensible at
any level in the build hierarchy.
@code{CONFIG_STATUS_DEPENDENCIES}.
@code{CONFIGURE_DEPENDENCIES} adds dependencies to the
-@file{configure} rule, whose effect is to run @code{autoconf}. This
-variable should be seldom used, because @code{automake} already tracks
+@file{configure} rule, whose effect is to run @command{autoconf}. This
+variable should be seldom used, because @command{automake} already tracks
@code{m4_include}d files. However it can be useful when playing
tricky games with @code{m4_esyscmd} or similar non-recommendable
macros with side effects.
@noindent
Here, @file{version.sh} is a shell fragment that sets
@code{VERSION_NUMBER}. The problem with this example is that
-@code{automake} cannot track dependencies (listing @file{version.sh}
-in @code{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
+@command{automake} cannot track dependencies (listing @file{version.sh}
+in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
to the user), and that it uses the obsolete form of @code{AC_INIT} and
@code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
straightforward, because shell variables are not allowed in
@end example
@noindent
Here @file{version.m4} could contain something like
-@code{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
-second form is that @code{automake} will take care of the dependencies
-when defining the rebuild rule, and will also distribute the file
-automatically. An inconvenience is that @code{autoconf} will now be
-rerun each time the version number is bumped, when only
+@samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
+second form is that @command{automake} will take care of the
+dependencies when defining the rebuild rule, and will also distribute
+the file automatically. An inconvenience is that @command{autoconf}
+will now be rerun each time the version number is bumped, when only
@file{configure} had to be rerun in the previous setup.
@vindex AUTOMAKE_OPTIONS
@table @asis
-@item @code{gnits}
-@itemx @code{gnu}
-@itemx @code{foreign}
-@itemx @code{cygnus}
-@cindex Option, @code{gnits}
-@cindex Option, @code{gnu}
-@cindex Option, @code{foreign}
-@cindex Option, @code{cygnus}
+@item @option{gnits}
+@itemx @option{gnu}
+@itemx @option{foreign}
+@itemx @option{cygnus}
+@cindex Option, @option{gnits}
+@cindex Option, @option{gnu}
+@cindex Option, @option{foreign}
+@cindex Option, @option{cygnus}
@opindex gnits
@opindex gnu
@opindex foreign
@opindex cygnus
-Set the strictness as appropriate. The @code{gnits} option also implies
-@code{readme-alpha} and @code{check-news}.
+Set the strictness as appropriate. The @option{gnits} option also
+implies options @option{readme-alpha} and @option{check-news}.
-@item @code{ansi2knr}
-@itemx @code{@var{path}/ansi2knr}
-@cindex Option, @code{ansi2knr}
+@item @option{ansi2knr}
+@itemx @option{@var{path}/ansi2knr}
+@cindex Option, @option{ansi2knr}
@opindex ansi2knr
Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
path, the generated @file{Makefile.in} will look in the specified
relative path to another directory in the same distribution (Automake
currently does not check this).
-@item @code{check-news}
-@cindex Option, @code{check-news}
+@item @option{check-news}
+@cindex Option, @option{check-news}
@opindex check-news
-Cause @code{make dist} to fail unless the current version number appears
+Cause @samp{make dist} to fail unless the current version number appears
in the first few lines of the @file{NEWS} file.
-@item @code{dejagnu}
-@cindex Option, @code{dejagnu}
+@item @option{dejagnu}
+@cindex Option, @option{dejagnu}
@opindex dejagnu
-Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
+Cause @command{dejagnu}-specific rules to be generated. @xref{Tests}.
-@item @code{dist-bzip2}
-@cindex Option, @code{dist-bzip2}
+@item @option{dist-bzip2}
+@cindex Option, @option{dist-bzip2}
@opindex dist-bzip2
Hook @code{dist-bzip2} to @code{dist}.
@trindex dist-bzip2
-@item @code{dist-shar}
-@cindex Option, @code{dist-shar}
+@item @option{dist-shar}
+@cindex Option, @option{dist-shar}
@opindex dist-shar
Hook @code{dist-shar} to @code{dist}.
@trindex dist-shar
-@item @code{dist-zip}
-@cindex Option, @code{dist-zip}
+@item @option{dist-zip}
+@cindex Option, @option{dist-zip}
@opindex dist-zip
Hook @code{dist-zip} to @code{dist}.
@trindex dist-zip
-@item @code{dist-tarZ}
-@cindex Option, @code{dist-tarZ}
+@item @option{dist-tarZ}
+@cindex Option, @option{dist-tarZ}
@opindex dist-tarZ
Hook @code{dist-tarZ} to @code{dist}.
@trindex dist-tarZ
-@item @code{filename-length-max=99}
-@cindex Option, @code{filename-length-max=99}
+@item @option{filename-length-max=99}
+@cindex Option, @option{filename-length-max=99}
@opindex filename-length-max=99
Abort if file names longer than 99 characters are found during
-@code{make dist}. Such long file names are generally considered not to
-be portable in tarballs. See the @code{tar-v7} and @code{tar-ustar}
+@samp{make dist}. Such long file names are generally considered not to
+be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
options below. This option should be used in the top-level
@file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
@file{configure.ac}, it will be ignored otherwise.
-@item @code{no-define}
-@cindex Option, @code{no-define}
+@item @option{no-define}
+@cindex Option, @option{no-define}
@opindex no-define
This options is meaningful only when passed as an argument to
@code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
@code{VERSION} variables to be @code{AC_DEFINE}d.
-@item @code{no-dependencies}
-@cindex Option, @code{no-dependencies}
+@item @option{no-dependencies}
+@cindex Option, @option{no-dependencies}
@opindex no-dependencies
-This is similar to using @samp{--include-deps} on the command line,
+This is similar to using @option{--include-deps} on the command line,
but is useful for those situations where you don't have the necessary
bits to make automatic dependency tracking work
(@pxref{Dependencies}). In this case the effect is to effectively
disable automatic dependency tracking.
-@item @code{no-dist}
-@cindex Option, @code{no-dist}
+@item @option{no-dist}
+@cindex Option, @option{no-dist}
@opindex no-dist
Don't emit any code related to @code{dist} target. This is useful
when a package has its own method for making distributions.
-@item @code{no-dist-gzip}
-@cindex Option, @code{no-dist-gzip}
+@item @option{no-dist-gzip}
+@cindex Option, @option{no-dist-gzip}
@opindex no-dist-gzip
Do not hook @code{dist-gzip} to @code{dist}.
@trindex no-dist-gzip
-@item @code{no-exeext}
-@cindex Option, @code{no-exeext}
+@item @option{no-exeext}
+@cindex Option, @option{no-exeext}
@opindex no-exeext
-If your @file{Makefile.am} defines a rule for target @samp{foo}, it
+If your @file{Makefile.am} defines a rule for target @code{foo}, it
will override a rule for a target named @samp{foo$(EXEEXT)}. This is
necessary when @code{EXEEXT} is found to be empty. However, by
default automake will generate an error for this use. The
-@code{no-exeext} option will disable this error. This is intended for
+@option{no-exeext} option will disable this error. This is intended for
use only where it is known in advance that the package will not be
ported to Windows, or any other operating system using extensions on
executables.
-@item @code{no-installinfo}
-@cindex Option, @code{no-installinfo}
+@item @option{no-installinfo}
+@cindex Option, @option{no-installinfo}
@opindex no-installinfo
The generated @file{Makefile.in} will not cause info pages to be built
or installed by default. However, @code{info} and @code{install-info}
targets will still be available. This option is disallowed at
-@samp{GNU} strictness and above.
+@option{gnu} strictness and above.
@trindex info
@trindex install-info
-@item @code{no-installman}
-@cindex Option, @code{no-installman}
+@item @option{no-installman}
+@cindex Option, @option{no-installman}
@opindex no-installman
The generated @file{Makefile.in} will not cause man pages to be
installed by default. However, an @code{install-man} target will still
be available for optional installation. This option is disallowed at
-@samp{GNU} strictness and above.
+@option{gnu} strictness and above.
@trindex install-man
-@item @code{nostdinc}
-@cindex Option, @code{nostdinc}
+@item @option{nostdinc}
+@cindex Option, @option{nostdinc}
@opindex nostdinc
-This option can be used to disable the standard @samp{-I} options which
+This option can be used to disable the standard @option{-I} options which
are ordinarily automatically provided by Automake.
-@item @code{no-texinfo.tex}
-@cindex Option, @code{no-texinfo.tex}
+@item @option{no-texinfo.tex}
+@cindex Option, @option{no-texinfo.tex}
@opindex no-texinfo.tex
Don't require @file{texinfo.tex}, even if there are texinfo files in
this directory.
-@item @code{readme-alpha}
-@cindex Option, @code{readme-alpha}
+@item @option{readme-alpha}
+@cindex Option, @option{readme-alpha}
@opindex readme-alpha
If this release is an alpha release, and the file @file{README-alpha}
exists, then it will be added to the distribution. If this option is
@samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
letter; it should be omitted for non-alpha releases.
-@item @code{std-options}
-@cindex Options, @code{std-options}
-@cindex @code{make installcheck}, testing @code{--help} and @code{--version}
-@cindex @code{--help} check
-@cindex @code{--version} check
+@item @option{std-options}
+@cindex Options, @option{std-options}
+@cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
+@cindex @option{--help} check
+@cindex @option{--version} check
@opindex std-options
Make the @code{installcheck} rule check that installed scripts and
-programs support the @code{--help} and @code{--version} options.
+programs support the @option{--help} and @option{--version} options.
This also provides a basic check that the program's
run-time dependencies are satisfied after installation.
@vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
In a few situations, programs (or scripts) have to be exempted from this
test. For instance @command{false} (from GNU sh-utils) is never
-successful, even for @code{--help} or @code{--version}. You can list
+successful, even for @option{--help} or @option{--version}. You can list
such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
Programs (not scripts) listed in this variable should be suffixed by
-@code{$(EXEEXT)} for the sake of Win32 or OS/2. For instance suppose we
-build @code{false} as a program but @code{true.sh} as a script, and that
-neither of them support @code{--help} or @code{--version}:
+@samp{$(EXEEXT)} for the sake of Win32 or OS/2. For instance suppose we
+build @file{false} as a program but @file{true.sh} as a script, and that
+neither of them support @option{--help} or @option{--version}:
@example
AUTOMAKE_OPTIONS = std-options
AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
@end example
-@item @code{subdir-objects}
-@cindex Options, @code{subdir-objects}
+@item @option{subdir-objects}
+@cindex Options, @option{subdir-objects}
@opindex subdir-objects
If this option is specified, then objects are placed into the
subdirectory of the build directory corresponding to the subdirectory of
In order to use this option with C sources, you should add
@code{AM_PROG_CC_C_O} to @file{configure.ac}.
-@item @code{tar-v7}
-@itemx @code{tar-ustar}
-@itemx @code{tar-pax}
-@cindex Option, @code{tar-v7}
-@cindex Option, @code{tar-ustar}
-@cindex Option, @code{tar-pax}
+@item @option{tar-v7}
+@itemx @option{tar-ustar}
+@itemx @option{tar-pax}
+@cindex Option, @option{tar-v7}
+@cindex Option, @option{tar-ustar}
+@cindex Option, @option{tar-pax}
@cindex @command{tar} formats
@cindex v7 @command{tar} format
@cindex ustar format
@opindex tar-pax
These three mutually exclusive options select the tar format to use
-when generating tarballs with @code{make dist}. (The tar file created
-is then compressed according to the set of @code{no-dist-gzip},
-@code{dist-bzip2} and @code{dist-tarZ} options in use.)
+when generating tarballs with @samp{make dist}. (The tar file created
+is then compressed according to the set of @option{no-dist-gzip},
+@option{dist-bzip2} and @option{dist-tarZ} options in use.)
These options must be passed as argument to @code{AM_INIT_AUTOMAKE}
(@pxref{Macros}) because they can require additional configure checks.
Automake will complain if it sees such options in an
@code{AUTOMAKE_OPTIONS} variable.
-@code{tar-v7} selects the old V7 tar format. This is the historical
+@option{tar-v7} selects the old V7 tar format. This is the historical
default. This antiquated format is understood by all tar
implementations and supports file names with up to 99 characters. When
given longer file names some tar implementations will diagnose the
problem while other will generate broken tarballs or use non-portable
extensions. Furthermore, the V7 format cannot store empty
directories. When using this format, consider using the
-@code{filename-length-max=99} option to catch file names too long.
+@option{filename-length-max=99} option to catch file names too long.
-@code{tar-ustar} selects the ustar format defined by POSIX
+@option{tar-ustar} selects the ustar format defined by POSIX
1003.1-1988. This format is believed to be old enough to be portable.
It fully supports empty directories. It can store file names with up
to 256 characters, provided that the file name can be split at
characters (please report them to @email{bug-automake@@gnu.org} so we
can document this accurately).
-@code{tar-pax} selects the new pax interchange format defined by POSIX
+@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
@xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
further discussion about tar formats.
-@code{configure} knows several ways to construct these formats. It
+@command{configure} knows several ways to construct these formats. It
will not abort if it cannot find a tool up to the task (so that the
-package can still be built), but @code{make dist} will fail.
+package can still be built), but @samp{make dist} will fail.
@item @var{version}
@cindex Option, @var{version}
newer than the version specified, creation of the @file{Makefile.in}
will be suppressed.
-@item @code{-W@var{category}} or @code{--warnings=@var{category}}
+@item @option{-W@var{category}} or @option{--warnings=@var{category}}
@cindex Option, warnings
-@cindex Option, @code{-W@var{category}}
-@cindex Option, @code{--warnings=@var{category}}
+@cindex Option, @option{-W@var{category}}
+@cindex Option, @option{--warnings=@var{category}}
These options behave exactly like their command-line counterpart
(@pxref{Invoking Automake}). This allows you to enable or disable some
warning categories on a per-file basis. You can also setup some warnings
-for your entire project; for instance try @code{AM_INIT_AUTOMAKE([-Wall])}
+for your entire project; for instance try @samp{AM_INIT_AUTOMAKE([-Wall])}
in your @file{configure.ac}.
@end table
-Unrecognized options are diagnosed by @code{automake}.
+Unrecognized options are diagnosed by @command{automake}.
If you want an option to apply to all the files in the tree, you can use
the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
@node Tags
-@section Interfacing to @code{etags}
+@section Interfacing to @command{etags}
@cindex @file{TAGS} support
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 @code{etags} does not
-understand. The user can use the @code{ETAGSFLAGS} to pass additional
-flags to @code{etags}; @code{AM_ETAGSFLAGS} is also available for use
-in @file{Makefile.am}.
+directories which 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}.
@vindex ETAGS_ARGS
@vindex ETAGSFLAGS
@vindex AM_ETAGSFLAGS
--regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
@end example
-If you add file names to @samp{ETAGS_ARGS}, you will probably also
-want to define @samp{TAGS_DEPENDENCIES}. The contents of this variable
+If you add file names to @code{ETAGS_ARGS}, you will probably also
+want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
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
build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
-is the name of the program to invoke (by default @samp{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
-@code{mkid} on the source. This is only supported on a
+@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 @code{gtags}.
+holds arguments which 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 @samp{.foo}
-files to @samp{.o} files. You would simply define an suffix rule for
+For instance, suppose you had a compiler which could compile @file{.foo}
+files to @file{.o} files. You would simply define an suffix rule for
your language:
@example
foocc -c -o $@@ $<
@end example
-Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
+Then you could directly use a @file{.foo} file in a @code{_SOURCES}
variable and expect the correct results:
@example
implicit rule.
For instance the following definition prevents Automake to misinterpret
-@samp{.idlC.cpp:} as an attempt to transform @samp{.idlC} into
-@samp{.cpp}.
+@samp{.idlC.cpp:} as an attempt to transform @file{.idlC} files into
+@file{.cpp} files.
@example
SUFFIXES = .idl C.cpp
@end example
As you may have noted, the @code{SUFFIXES} variable behaves like the
-@code{.SUFFIXES} special target of @code{make}. You should not touch
+@code{.SUFFIXES} special target of @command{make}. You should not touch
@code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
Automake generate the suffix list for @code{.SUFFIXES}. Any given
@code{SUFFIXES} go at the start of the generated suffixes list, followed
@cindex @file{Makefile} fragment, including
Automake supports an @code{include} directive which can be used to
-include other @file{Makefile} fragments when @code{automake} is run.
-Note that these fragments are read and interpreted by @code{automake},
-not by @code{make}. As with conditionals, @code{make} has no idea that
+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
@code{include} is in use.
There are two forms of @code{include}:
@acindex AM_CONDITIONAL
Before using a conditional, you must define it by using
-@code{AM_CONDITIONAL} in the @code{configure.ac} file (@pxref{Macros}).
+@code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
@defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
The conditional name, @var{conditional}, should be a simple string
which are reserved by Automake.
The shell @var{condition} (suitable for use in a shell @code{if}
-statement) is evaluated when @code{configure} is run. Note that you
+statement) is evaluated when @command{configure} is run. Note that you
must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
-time @code{configure} is run. If @code{AM_CONDITIONAL} is run
+time @command{configure} is run. If @code{AM_CONDITIONAL} is run
conditionally (e.g., in a shell @code{if} statement), then the result
will confuse automake.
@end defmac
-@cindex @code{--enable-debug}, example
-@cindex Example conditional @code{--enable-debug}
-@cindex Conditional example, @code{--enable-debug}
+@cindex @option{--enable-debug}, example
+@cindex Example conditional @option{--enable-debug}
+@cindex Conditional example, @option{--enable-debug}
Conditionals typically depend upon options which the user provides to
-the @code{configure} script. Here is an example of how to write a
-conditional which is true if the user uses the @samp{--enable-debug}
+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}
option.
@example
@file{configure} script, and affect the translation from
@file{Makefile.in} 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 @code{make}
+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}.
@node Gnits
-@chapter The effect of @code{--gnu} and @code{--gnits}
+@chapter The effect of @option{--gnu} and @option{--gnits}
-@cindex @code{--gnu}, required files
-@cindex @code{--gnu}, complete description
+@cindex @option{--gnu}, required files
+@cindex @option{--gnu}, complete description
-The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
-variable) causes @code{automake} to check the following:
+The @option{--gnu} option (or @option{gnu} in the
+@code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
+the following:
@itemize @bullet
@item
or @file{COPYING}, are required at the topmost directory of the package.
@item
-The options @samp{no-installman} and @samp{no-installinfo} are
+The options @option{no-installman} and @option{no-installinfo} are
prohibited.
@end itemize
Note that this option will be extended in the future to do even more
checking; it is advisable to be familiar with the precise requirements
-of the GNU standards. Also, @samp{--gnu} can require certain
+of the GNU standards. Also, @option{--gnu} can require certain
non-standard GNU programs to exist for use by various maintainer-only
-rules; for instance in the future @code{pathchk} might be required for
+rules; for instance in the future @command{pathchk} might be required for
@samp{make dist}.
-@cindex @code{--gnits}, complete description
+@cindex @option{--gnits}, complete description
-The @samp{--gnits} option does everything that @samp{--gnu} does, and
+The @option{--gnits} option does everything that @option{--gnu} does, and
checks the following as well:
@itemize @bullet
@item
-@samp{make installcheck} will check to make sure that the @code{--help}
-and @code{--version} really print a usage message and a version string,
-respectively. This is the @code{std-options} option (@pxref{Options}).
+@samp{make installcheck} will check to make sure that the @option{--help}
+and @option{--version} really print a usage message and a version string,
+respectively. This is the @option{std-options} option (@pxref{Options}).
@item
@samp{make dist} will check to make sure the @file{NEWS} file has been
updated to the current version.
@item
-@samp{VERSION} is checked to make sure its format complies with Gnits
+@code{VERSION} is checked to make sure its format complies with Gnits
standards.
@c FIXME xref when standards are finished
@item
@cindex @file{README-alpha}
-If @samp{VERSION} indicates that this is an alpha release, and the file
+If @code{VERSION} indicates that this is an alpha release, and the file
@file{README-alpha} appears in the topmost directory of a package, then
-it is included in the distribution. This is done in @samp{--gnits}
+it is included in the distribution. This is done in @option{--gnits}
mode, and no other, because this mode is the only one where version
number formats are constrained, and hence the only mode where Automake
can automatically determine whether @file{README-alpha} should be
@node Cygnus
-@chapter The effect of @code{--cygnus}
+@chapter The effect of @option{--cygnus}
-@cindex @code{cygnus} strictness
+@cindex @option{cygnus} strictness
Some packages, notably GNU GCC and GNU gdb, have a build environment
originally written at Cygnus Support (subsequently renamed Cygnus
Solutions, and then later purchased by Red Hat). Packages with this
ancestry are sometimes referred to as ``Cygnus'' trees.
-A Cygnus tree has slightly different rules for how a @file{Makefile.in}
-is to be constructed. Passing @samp{--cygnus} to @code{automake} will
-cause any generated @file{Makefile.in} to comply with Cygnus rules.
+A Cygnus tree has slightly different rules for how a
+@file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
+@command{automake} will cause any generated @file{Makefile.in} to
+comply with Cygnus rules.
-Here are the precise effects of @samp{--cygnus}:
+Here are the precise effects of @option{--cygnus}:
@itemize @bullet
@item
@item
Certain tools will be searched for in the build tree as well as in the
-user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
-@code{makeinfo} and @code{texi2dvi}.
+user's @env{PATH}. These tools are @command{runtest}, @command{expect},
+@command{makeinfo} and @command{texi2dvi}.
@item
-@code{--foreign} is implied.
+@option{--foreign} is implied.
@item
-The options @samp{no-installinfo} and @samp{no-dependencies} are
+The options @option{no-installinfo} and @option{no-dependencies} are
implied.
@item
-The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
+The macros @code{AM_MAINTAINER_MODE} and @code{AM_CYGWIN32} are
required.
@item
The @code{check} target doesn't depend on @code{all}.
@end itemize
-GNU maintainers are advised to use @samp{gnu} strictness in preference
+GNU maintainers are advised to use @option{gnu} strictness in preference
to the special Cygnus mode. Some day, perhaps, the differences between
Cygnus trees and GNU trees will disappear (for instance, as GCC is made
more standards compliant). At that time the special Cygnus mode will be
@section Extending Automake Rules
With some minor exceptions (like @code{_PROGRAMS} variables being
-rewritten to append @code{$(EXEEXT)}), the contents of a
+rewritten to append @samp{$(EXEEXT)}), the contents of a
@file{Makefile.am} is copied to @file{Makefile.in} verbatim.
@cindex copying semantics
These copying semantics means that many problems can be worked around
-by simply adding some @code{make} variables and rules to
+by simply adding some @command{make} variables and rules to
@file{Makefile.am}. Automake will ignore these additions.
@cindex conflicting definitions
These overriding semantics make it possible to fine tune some default
settings of Automake, or replace some of its rules. Overriding
Automake rules is often inadvisable, particularly in the topmost
-directory of a package with subdirectories. The @code{-Woverride}
+directory of a package with subdirectories. The @option{-Woverride}
option (@pxref{Invoking Automake}) comes handy to catch overridden
definitions.
Note that Automake does not make any difference between rules with
commands and rules that only specify dependencies. So it is not
-possible to append new dependencies to an @code{automake}-defined
+possible to append new dependencies to an @command{automake}-defined
target without redefining the entire rule.
-@cindex @code{-local} targets
+@cindex @option{-local} targets
@cindex local targets
However, various useful targets have a @samp{-local} version you can
It doesn't make sense to uninstall just data or just executables.
For instance, here is one way to erase a subdirectory during
-@code{make clean} (@pxref{Clean}).
+@samp{make clean} (@pxref{Clean}).
@example
clean-local:
@code{install-data-local} to install a file to some hard-coded
location, but you should avoid this. (@pxref{Hard-Coded Install Paths})
-@cindex @code{-hook} targets
+@cindex @option{-hook} targets
@cindex hook targets
Some rule also have a way to run another rule, called a @dfn{hook},
Although cheaper and more portable than symbolic links, hard links
will not work everywhere (for instance OS/2 does not have
-@command{ln}). Ideally you should fall back to @code{cp -p} when
-@code{ln} does not work. An easy way, if symbolic links are
+@command{ln}). Ideally you should fall back to @samp{cp -p} when
+@command{ln} does not work. An easy way, if symbolic links are
acceptable to you, is to add @code{AC_PROG_LN_S} to
@file{configure.ac} (@pxref{Particular Programs, , Particular Program
-Checks, autoconf, The Autoconf Manual}) and use @code{$(LN_S)} in
+Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
@file{Makefile.am}.
@cindex versioned binaries, installing
@cindex installing versioned binaries
@cindex @code{LN_S} example
For instance, here is how you could install a versioned copy of a
-program using @code{$(LN_S)}:
+program using @samp{$(LN_S)}:
@example
install-exec-hook:
@end example
Note that we rename the program so that a new version will erase the
-symbolic link, not the real binary. Also we @code{cd} into the
+symbolic link, not the real binary. Also we @command{cd} into the
destination directory in order to create relative links.
When writing @code{install-exec-hook} or @code{install-data-hook},
@trindex distdir
@vindex distdir
@vindex top_distdir
-Copy files to distribute into @code{$(distdir)}, before a tarball is
+Copy files to distribute into @samp{$(distdir)}, before a tarball is
constructed. Of course this target is not required if the
-@code{no-dist} option (@pxref{Options}) is used.
+@option{no-dist} option (@pxref{Options}) is used.
-The variables @code{$(top_distdir)} and @code{$(distdir)}
+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
@item tags
@itemx ctags
-Build @code{TAGS} and @code{CTAGS} (@pxref{Tags}).
+Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
@end table
If you have ever used Gettext in a project, this is a good example of
Another aspect of integrating third-party build systems is whether
they support VPATH builds. Obviously if the subpackage does not
support VPATH builds the whole package will not support VPATH builds.
-This in turns means that @code{make distcheck} will not work, because
+This in turns means that @samp{make distcheck} will not work, because
it relies on VPATH builds. Some people can live without this
-(actually, many Automake users have never heard of @code{make
+(actually, many Automake users have never heard of @samp{make
distcheck}). Other people may prefer to revamp the existing
@file{Makefile}s to support VPATH. Doing so does not necessarily
require Automake, only Autoconf is needed (@pxref{Build Directories, ,
Build Directories, autoconf, The Autoconf Manual}). The necessary
-substitutions: @code{@@scrdir@@}, @code{@@top_srcdir@@}, and
-@code{@@top_builddir@@} are defined by @file{configure} when it
+substitutions: @samp{@@scrdir@@}, @samp{@@top_srcdir@@}, and
+@samp{@@top_builddir@@} are defined by @file{configure} when it
processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
Output Variables, autoconf, The Autoconf Manual}), they are not
-computed by the Makefile like the aforementioned @code{$(distdir)} and
-@code{$(top_distdir)} variables..
+computed by the Makefile like the aforementioned @samp{$(distdir)} and
+@samp{$(top_distdir)} variables..
It is sometimes inconvenient to modify a third-party @file{Makefile}
to introduce the above required targets. For instance one may want to
@cindex Proxy @file{Makefile} for third-party packages
A similar idea that does not use @code{include} is to write a proxy
@file{Makefile} that dispatches rules to the real @file{Makefile},
-either with @code{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
-it's OK to rename the original @file{Makefile}) or with @code{cd
+either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
+it's OK to rename the original @file{Makefile}) or with @samp{cd
subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
subdirectory project one directory deeper). The good news is that
this proxy @file{Makefile} can be generated with Automake. All we
-need are @code{-local} targets (@pxref{Extending}) that perform the
+need are @option{-local} targets (@pxref{Extending}) that perform the
dispatch. Of course the other Automake features are available, so you
could decide to let Automake perform distribution or installation.
Here is a possible @file{Makefile.am}:
is not required to use Automake.
Some of the files that can be automatically installed via the
-@code{--add-missing} switch do fall under the GPL@. However, these also
+@option{--add-missing} switch do fall under the GPL@. However, these also
have a special exception allowing you to distribute them with your
package, regardless of the licensing you choose.
Starting with version 1.6, Automake installs versioned binaries. This
means you can install several versions of Automake in the same
@samp{$prefix}, and can select an arbitrary Automake version by running
-@samp{automake-1.6} or @samp{automake-1.7} without juggling with
+@command{automake-1.6} or @command{automake-1.7} without juggling with
@samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
-will use @samp{automake-1.6} explicitly in their rebuild rules.
+will use @command{automake-1.6} explicitly in their rebuild rules.
-The number @samp{1.6} in @samp{automake-1.6} is Automake's API version,
+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
Automake's programming interface is not easy to define. Basically it
should include at least all @strong{documented} variables and targets
-that a @samp{Makefile.am} author can use, any behavior associated with
+that a @file{Makefile.am} author can use, any behavior associated with
them (e.g. the places where @samp{-hook}'s are run), the command line
-interface of @samp{automake} and @samp{aclocal}, @dots{}
+interface of @command{automake} and @command{aclocal}, @dots{}
@heading What is not in the API
autoreconf -vfi
@end example
-The use of @code{--force-missing} ensures that auxiliary tools will be
+The use of @option{--force-missing} ensures that auxiliary tools will be
overridden by new versions (@pxref{Invoking Automake}).
It is important to regenerate all these files each time Automake is
@command{aclocal}. However it never checks whether auxiliary scripts
are up-to-date. In other words, @command{automake} will tell you when
@command{aclocal} needs to be rerun, but it will never diagnose a
-missing @code{--force-missing}.
+missing @option{--force-missing}.
Before upgrading to a new major release, it is a good idea to read the
file @file{NEWS}. This file lists all changes between releases: new
@cindex CVS and timestamps
Unless you use CVS keywords (in which case files must be updated at
-commit time), CVS preserves timestamp during @code{cvs commit} and
-@code{cvs import -d} operations.
+commit time), CVS preserves timestamp during @samp{cvs commit} and
+@samp{cvs import -d} operations.
-When you check out a file using @code{cvs checkout} its timestamp is
+When you check out a file using @samp{cvs checkout} its timestamp is
set to that of the revision which is being checked out.
However, during @command{cvs update}, files will have the date of the
order, @file{configure.ac} will appear older than @file{configure}
after a @command{cvs update} that updates both files, even if
@file{configure} was newer than @file{configure.ac} when it was
-checked in. Calling @code{make} will then trigger a spurious rebuild
+checked in. Calling @command{make} will then trigger a spurious rebuild
of @file{configure}.
@subsection Living with CVS in Autoconfiscated projects
This last change to @file{Makefile.am} make the copy of
@file{Makefile.in} out-of-date. Since CVS processes files
-alphabetically, when another developer @code{cvs update} his or her
+alphabetically, when another developer @samp{cvs update} his or her
tree, @file{Makefile.in} will happen to be newer than
@file{Makefile.am}. This other developer will not see
@file{Makefile.in} is out-of-date.
@subsubheading Generated files out of CVS
-One way to get CVS and @code{make} working peacefully is to never
+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
-are @code{Makefile} targets (also called @emph{derived} files).
+are @file{Makefile} targets (also called @emph{derived} files).
This way developers are not annoyed by changes to generated files. It
does not matter if they all have different versions (assuming they are
@command{autoconf} is not installed. When all distributed files are
kept under CVS, this feature of @command{missing} allows user
@emph{with no maintainer tools} to build a package off CVS, bypassing
-any timestamp inconsistency implied by @code{cvs update}.
+any timestamp inconsistency implied by @samp{cvs update}.
If the required tool is installed, @command{missing} will run it and
won't attempt to continue after failures. This is correct during
@code{AM_MAINTAINER_MODE} disables the so called "rebuild rules" by
default. If you have @code{AM_MAINTAINER_MODE} in
-@file{configure.ac}, and run @code{./configure && make}, then
+@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
should normally not have to update.
-If you run @code{./configure --enable-maintainer-mode}, then these
+If you run @samp{./configure --enable-maintainer-mode}, then these
rebuild rules will be active.
People use @code{AM_MAINTAINER_MODE} either because they do want their
insecurity. By removing dependencies you get non-dependable builds:
change to sources files can have no effect on generated files and this
can be very confusing when unnoticed. He adds that security shouldn't
-be reserved to maintainers (what @code{--enable-maintainer-mode}
+be reserved to maintainers (what @option{--enable-maintainer-mode}
suggests), on the contrary. If one user has to modify a
@file{Makefile.am}, then either @file{Makefile.in} should be updated
or a warning should be output (this is what Automake uses
-@code{missing} for) but the last thing you want is that nothing
+@command{missing} for) but the last thing you want is that nothing
happens and the user doesn't notice it (this is what happens when
rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
@itemize
@item
When using CVS (or similar) developers need to remember they have to
-run @code{cvs add} or @code{cvs rm} anyway. Updating
+run @samp{cvs add} or @samp{cvs rm} anyway. Updating
@file{Makefile.am} accordingly quickly becomes a reflex.
Conversely, if your application doesn't compile
because you forgot to add a file in @file{Makefile.am}, it will help
-you remember to @code{cvs add} it.
+you remember to @samp{cvs add} it.
@item
Using wildcards makes easy to distribute files by mistake. For
@item
Listing files, you control *exactly* what you distribute.
If some file that should be distributed is missing from your
-tree, @code{make dist} will complain. Besides, you don't distribute
+tree, @samp{make dist} will complain. Besides, you don't distribute
more than what you listed.
@item
start writing a patch against Automake to teach it about wildcards,
let's see the main technical issue: portability.
-Although @code{$(wildcard ...)} works with GNU @command{make}, it is
+Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
not portable to other @command{make} implementations.
The only way Automake could support @command{$(wildcard ...)} is by
expending @command{$(wildcard ...)} when @command{automake} is run.
Resulting @file{Makefile.in}s would be portable since they would
-list all files and not use @code{$(wildcard ...)}. However that
-means developers need to remember they must run @code{automake} each
+list all files and not use @samp{$(wildcard ...)}. However that
+means developers need to remember they must run @command{automake} each
time they add, delete, or rename files.
Compared to editing @file{Makefile.am}, this is really little win. Sure,
-it's easier and faster to type @code{automake; make} than to type
-@code{emacs Makefile.am; make}. But nobody bothered enough to write a
+it's easier and faster to type @samp{automake; make} than to type
+@samp{emacs Makefile.am; make}. But nobody bothered enough to write a
patch add support for this syntax. Some people use scripts to
generated file lists in @file{Makefile.am} or in separate
@file{Makefile} fragments.
Even if you don't care about portability, and are tempted to use
-@code{$(wildcard ...)} anyway because you target only GNU Make, you
+@samp{$(wildcard ...)} anyway because you target only GNU Make, you
should know there are many places where Automake need to know exactly
which files should be processed. As Automake doesn't know how to
-expand @code{$(wildcard ...)}, you cannot use it in these places.
-@code{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
+expand @samp{$(wildcard ...)}, you cannot use it in these places.
+@samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
variables as far Automake is concerned.
-You can get warnings about @code{$(wildcard ...}) constructs using the
-@code{-Wportability} flag.
+You can get warnings about @samp{$(wildcard ...}) constructs using the
+@option{-Wportability} flag.
@node distcleancheck
@section Files left in build directory after distclean
@cindex @code{distclean}, diagnostic
-@cindex @code{make distclean}, diagnostic
+@cindex @samp{make distclean}, diagnostic
@cindex dependencies and distributed files
@trindex distclean
@trindex distcleancheck
-This is a diagnostic you might encounter while running @code{make
+This is a diagnostic you might encounter while running @samp{make
distcheck}.
-As explained in @ref{Dist}, @code{make distcheck} attempts to build
+As explained in @ref{Dist}, @samp{make distcheck} attempts to build
and check your package for errors like this one.
-@code{make distcheck} will perform a @code{VPATH} build of your
-package, and then call @code{make distclean}. Files left in the build
-directory after @code{make distclean} has run are listed after this
+@samp{make distcheck} will perform a @code{VPATH} build of your
+package, and then call @samp{make distclean}. Files left in the build
+directory after @samp{make distclean} has run are listed after this
error.
This diagnostic really covers two kinds of errors:
The latter bug is not always easy to understand and fix, so let's
proceed with an example. Suppose our package contains a program for
which we want to build a man page using @command{help2man}. GNU
-@command{help2man} produces simple manual pages from the @code{--help}
-and @code{--version} output of other commands (@pxref{Top, , Overview,
+@command{help2man} produces simple manual pages from the @option{--help}
+and @option{--version} output of other commands (@pxref{Top, , Overview,
help2man, The Help2man Manual}). Because we don't to force want our
users to install @command{help2man}, we decide to distribute the
generated man page using the following setup.
@end example
This will effectively distribute the man page. However,
-@code{make distcheck} will fail with:
+@samp{make distcheck} will fail with:
@example
ERROR: files left in build directory after distclean:
@file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
will always appear to be newer than the distributed @file{foo.1}.
-@code{make distcheck} caught an inconsistency in our package. Our
+@samp{make distcheck} caught an inconsistency in our package. Our
intent was to distribute @file{foo.1} so users do not need installing
@command{help2man}, however since this our rule causes this file to be
always rebuilt, users @emph{do} need @command{help2man}. Either we
@vrindex distcleancheck_listfiles
For desperate cases, it's always possible to disable this check by
setting @code{distcleancheck_listfiles} as documented in @ref{Dist}.
-Make sure you do understand the reason why @code{make distcheck}
+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.
@end example
@noindent
-@file{xyz.o} will be compiled with @code{$(foo_CPPFLAGS) $(CPPFLAGS)},
+@file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
(because @file{xyz.o} is part of the @code{foo} target), while
-@file{main.o} will be compiled with @code{$(AM_CPPFLAGS) $(CPPFLAGS)}
+@file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
(because there is no per-target variable for target @code{bar}).
The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
is a user variable, i.e., a variable that users are entitled to modify
in order to compile the package. This variable, like many others,
-is documented at the end of the output of @code{configure --help}.
+is documented at the end of the output of @samp{configure --help}.
For instance, someone who needs to add @file{/home/my/usr/include} to
the C compiler's search path would configure a package with
make
@end example
-The reason @code{$(CPPFLAGS)} appears after @code{$(AM_CPPFLAGS)} or
-@code{$(mumble_CPPFLAGS)} in the compile command is that users
+The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
+@samp{$(mumble_CPPFLAGS)} in the compile command is that users
should always have the last say. It probably makes more sense if you
-think about it while looking at the @code{CXXFLAGS=-O0} above, which
+think about it while looking at the @samp{CXXFLAGS=-O0} above, which
should supersede any other switch from @code{AM_CXXFLAGS} or
@code{mumble_CXXFLAGS} (and this of course replaces the previous value
of @code{CXXFLAGS}).
You should never redefine a user variable such as @code{CPPFLAGS} in
-@file{Makefile.am}. Use @code{automake -Woverride} to diagnose such
+@file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
mistakes. Even something like
@example
@end example
In this example both programs will be compiled with the flags
-substituted into @code{$(WARNINGCFLAGS)}, and @code{prog2} will
+substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
additionally be compiled with the flags required to link with
@file{libfoo}.
Using variables like this gives you full control over the ordering of
the flags. For instance if there is a flag in $(WARNINGCFLAGS) that
you want to negate for a particular target, you can use something like
-@code{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
+@samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
been forcefully appended to @code{CFLAGS}, there would be no way to
disable one flag. Yet another reason to leave user variables to
users.
@noindent
Obviously the two programs are built from the same source, but it
would be bad if they shared the same object, because @file{generic.o}
-cannot be built with both @code{-DEXIT_CODE=0} @emph{and}
-@code{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
+cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
+@samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
build two different objects: @file{true-generic.o} and
@file{false-generic.o}.
@noindent
@file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
-compiled with @code{-some -flags}. (If you wonder about the names of
+compiled with @samp{-some -flags}. (If you wonder about the names of
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
@end example
Here @file{foo-bar.o} and @file{foo-main.o} will all be
-compiled with @code{-some -flags}, while @file{libfoo_a-foo.o} will
-be compiled using @code{-some -other -flags}. Eventually, all
+compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
+be compiled using @samp{-some -other -flags}. Eventually, all
three objects will be linked to form @file{foo}.
This trick can also be achieved using Libtool convenience libraries,
-for instance @code{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
+for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
Convenience Libraries}).
Another tempting idea to implement per-object flags is to override the
compile rules @command{automake} would output for these files.
Automake will not define a rule for a target you have defined, so you
-could think about defining the @code{foo-foo.o: foo.c} rule yourself.
+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
@noindent
What the above rule really says is that @file{data.c} and
@file{data.h} each depend on @file{data.foo}, and can each be built by
-running @code{foo data.foo}. In other words it is equivalent to:
+running @samp{foo data.foo}. In other words it is equivalent to:
@example
# We do not want this.
@itemize
@item
The most worrying case is when running a parallel @command{make}. If
-@file{data.c} and @file{data.h} are built in parallel, two @code{foo
+@file{data.c} and @file{data.h} are built in parallel, two @samp{foo
data.foo} commands will run concurrently. This is harmful.
@item
-Another case is when the dependency (here @code{data.foo}) is
+Another case is when the dependency (here @file{data.foo}) is
(or depends upon) a phony target.
@end itemize
@end example
@noindent
-The idea is that @code{foo data.foo} is run only when @file{data.c}
+The idea is that @samp{foo data.foo} is run only when @file{data.c}
needs to be updated, but we further state that @file{data.h} depends
upon @file{data.c}. That way, if @file{data.h} is required and
@file{data.foo} is out of date, the dependency on @file{data.c} will
This is almost perfect, but suppose we have built @file{data.h} and
@file{data.c}, and then we erase @file{data.h}. Then, running
-@code{make data.h} will not rebuild @file{data.h}. The above rules
+@samp{make data.h} will not rebuild @file{data.h}. The above rules
just state that @file{data.c} must be up-to-date with respect to
@file{data.foo}, and this is already the case.
have a weird situation. The next time @command{make} is run,
@file{data.h} will appear older than @file{data.c}, the second rule
will be triggered, a shell will be started to execute the
-@code{if...fi} command, but actually it will just execute the
+@samp{if@dots{}fi} command, but actually it will just execute the
@code{then} branch, that is: nothing. In other words, because the
witness we selected is not the first file created by @command{foo},
@command{make} will start a shell to do nothing each time it is run.
@display
My package needs to install some configuration file. I tried to use
-the following rule, but @code{make distcheck} fails. Why?
+the following rule, but @samp{make distcheck} fails. Why?
@example
# Do not do this.
My package needs to populate the installation directory of another
package at install-time. I can easily compute that installation
directory in @file{configure}, but if I install files therein,
-@code{make distcheck} fails. How else should I do?
+@samp{make distcheck} fails. How else should I do?
@end display
-These two setups share their symptoms: @code{make distcheck} fails
+These two setups share their symptoms: @samp{make distcheck} fails
because they are installing files to hard-coded paths. In the later
case the path is not really hard-coded in the package, but we can
consider it to be hard-coded in the system (or in whichever tool that
supplies the path). As long as the path does not use any of the
-standard directory variables (@code{$(prefix)}, @code{$(bindir)},
-@code{$(datadir)}, etc.), the effect will be the same:
+standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
+@samp{$(datadir)}, etc.), the effect will be the same:
user-installations are impossible.
When a (non-root) user wants to install a package, he usually has no
-right to install anything in @code{/usr} or @code{/usr/local}. So he
-does something like @code{./configure --prefix ~/usr} to install
-package in his own @code{~/usr} tree.
+right to install anything in @file{/usr} or @file{/usr/local}. So he
+does something like @samp{./configure --prefix ~/usr} to install
+package in his own @file{~/usr} tree.
If a package attempts to install something to some hard-coded path
-(e.g., @file{/etc/afile}), regardless of this @code{--prefix} setting,
-then the installation will fail. @code{make distcheck} performs such
-a @code{--prefix} installation, hence it will fail too.
+(e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
+then the installation will fail. @samp{make distcheck} performs such
+a @option{--prefix} installation, hence it will fail too.
Now, there are some easy solutions.
@end example
@noindent
-by default @code{sysconfdir} will be @code{$(prefix)/etc}, because
+by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
this is what the GNU Standards require. When such a package is
installed on a FHS compliant system, the installer will have to set
-@code{--sysconfdir=/etc}. As the maintainer of the package you
+@samp{--sysconfdir=/etc}. As the maintainer of the package you
should not be concerned by such site policies: use the appropriate
standard directory variable to install your files so that installer
can easily redefine these variables to match their site conventions.
non-root users will not be able to install the package, hence
distcheck fails.
-Let's do better. The @code{sysconfig.get_python_lib()} function
+Let's do better. The @samp{sysconfig.get_python_lib()} function
actually accepts a third argument that will replace Python's
installation prefix.
You can also use this new path. If you do
@itemize @bullet
@item
-root users can install your package with the same @code{--prefix}
+root users can install your package with the same @option{--prefix}
as Python (you get the behavior of the previous attempt)
@item
@end itemize
The @code{AM_PATH_PYTHON} macro uses similar commands to define
-@code{$(pythondir)} and @code{$(pyexecdir)} (@pxref{Python}).
+@samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
Of course not all tools are as advanced as Python regarding that
substitution of @var{prefix}. So another strategy is to figure the
part of the of the installation directory that must be preserved. For
instance here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
-computes @code{$(lispdir)}:
+computes @samp{$(lispdir)}:
@example
$EMACS -batch -q -eval '(while load-path
I.e., it just picks the first directory that looks like
@file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
-the search path of emacs, and then substitutes @code{$@{libdir@}} or
-@code{$@{datadir@}} appropriately.
+the search path of emacs, and then substitutes @samp{$@{libdir@}} or
+@samp{$@{datadir@}} appropriately.
The emacs case looks complicated because it processes a list and
expect two possible layouts, otherwise it's easy, and the benefit for
This looks pretty much like what we do today, except the
@code{PROGRAMS} variable has no directory prefix specifying where
@file{hello} should be installed: all programs are installed in
-@code{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
+@samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
that must be built but not installed (it is called
@code{noinst_PROGRAMS} nowadays).
has been a source of problems through the whole history of Automake.
If you never used Perl 4, imagine Perl 5 without objects, without
-@code{my} variables (only dynamically scoped @code{local} variables),
+@samp{my} variables (only dynamically scoped @samp{local} variables),
without function prototypes, with function calls that needs to be
-prefixed with @code{&}, etc. Traces of this old style can still be
+prefixed with @samp{&}, etc. Traces of this old style can still be
found in today's @command{automake}.
@item 1995-11-28 Automake 0.22
@file{configure.in} to better automate the Autoconf integration.
0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
-@code{--gnu} and @code{--gnits} options, the latter being stricter.
+@option{--gnu} and @option{--gnits} options, the latter being stricter.
@item 1996-02-07 Automake 0.29
The oldest file in the administrative directory of the CVS repository
that was created on Sourceware is dated 1998-09-19, while the
-announcement that @code{automake} and @code{autoconf} had joined
-@code{sourceware} was made on 1998-10-26. They were among the first
-projects to be hosted there.
+announcement that @command{automake} and @command{autoconf} had joined
+@command{sourceware} was made on 1998-10-26. They were among the
+first projects to be hosted there.
The heedful reader will have noticed Automake was exactly 4-year-old
on 1998-09-19.
@item 1999-01-14 Automake 1.4
This release adds support for Fortran 77 and for the @code{include}
-statement. Also, @code{+=} assignments are introduced, but it is
+statement. Also, @samp{+=} assignments are introduced, but it is
still quite easy to fool Automake when mixing this with conditionals.
These two releases, Automake 1.4 and Autoconf 2.13 makes a duo that
``trace'' feature of Autoconf. The way to scan @file{configure.in} at
this time was to read the file and grep the various macro of interest
to Automake. Doing so could break in many unexpected ways; automake
-could miss some definition (for instance @code{AC_SUBST([$1], [$2])}
+could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
where the arguments are known only when M4 is run), or conversely it
could detect some macro that was not expanded (because it is called
conditionally). In the CVS version of Autoconf, Akim had implemented
-the @code{--trace} option, which provides accurate information about
+the @option{--trace} option, which provides accurate information about
where macros are actually called and with what arguments. Akim will
equip Automake with a second @file{configure.in} scanner that uses
-this @code{--trace} interface. Since it was not sensible to drop the
+this @option{--trace} interface. Since it was not sensible to drop the
Autoconf 2.13 compatibility yet, this experimental scanner was only
used when an environment variable was set, the traditional
grep-scanner being still the default.
Some of these breakages were effectively bugs that would eventually be
fixed in the next release. However, a lot of damage was caused by
some changes made deliberately to render Automake stricter on some
-setup we did consider bogus. For instance @code{make distcheck} was
-improved to check that @code{make uninstall} did remove all the files
-@code{make install} installed, that @code{make distclean} did not omit
+setup we did consider bogus. For instance @samp{make distcheck} was
+improved to check that @samp{make uninstall} did remove all the files
+@samp{make install} installed, that @samp{make distclean} did not omit
some file, and that a VPATH build would work even if the source
directory was read-only. Similarly, Automake now rejects multiple
definitions of the same variable (because that would mix very badly
-with conditionals), and @code{+=} assignments with no previous
+with conditionals), and @samp{+=} assignments with no previous
definition. Because these changes all occurred suddenly after 1.4 had
been established for more that two years, it hurt users.
from @command{automake}. Now @command{automake} can just trace the
@code{m4_include}s to discover the dependencies.
-@command{aclocal} also starts using the @code{--trace} Autoconf option
+@command{aclocal} also starts using the @option{--trace} Autoconf option
in order to discover used macros more accurately. This will turn out
to be very tricky (later releases will improve this) as people had
devised many ways to cope with the limitation of previous
@itemize
@item
-The code to generate the @file{.P} file relied on @code{gcc}.
+The code to generate the @file{.P} file relied on @command{gcc}.
(A limitation, not technically a bug.)
@item
The dependency tracking mechanism itself relied on GNU @command{make}.
@item
Because each @file{.P} file was a dependency of @file{Makefile}, this
meant that dependency tracking was done eagerly by @command{make}.
-For instance, @code{make clean} would cause all the dependency files
+For instance, @samp{make clean} would cause all the dependency files
to be updated, and then immediately removed. This eagerness also
caused problems with some configurations; if a certain source file
could not be compiled on a given architecture for some reason,
As dependency tracking was done as a pre-pass, compile times were
doubled--the compiler had to be run twice per source file.
@item
-@code{make dist} re-ran @command{automake} to generate a
+@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
do this portably, Automake had to scan the dependency files and remove
any reference which was to a source file not in the distribution.
-This process was error-prone. Also, if @code{make dist} was run in an
+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
In this approach, the @file{.P} files were included using the
@code{-include} command, which let us create these files lazily. This
-avoided the @code{make clean} problem.
+avoided the @samp{make clean} problem.
We only computed dependencies when a file was actually compiled. This
avoided the performance penalty associated with scanning each file
@item
Dependency tracking was still done by the developer, so the problems
from the first implementation relating to massaging of dependencies by
-@code{make dist} were still in effect.
+@samp{make dist} were still in effect.
@item
This implementation suffered from the ``deleted header file'' problem.
Suppose a lazily-created @file{.P} file includes a dependency on a
@subsection Dependencies for the User
@unnumberedsubsubsec Description
-The bugs associated with @code{make dist}, over time, became a real
+The bugs associated with @samp{make dist}, over time, became a real
problem. Packages using Automake were being built on a large number
of platforms, and were becoming increasingly complex. Broken
dependencies were distributed in ``portable'' @file{Makefile.in}s,
@node Releases
@section Release Statistics
-The following table (inspired by @code{perlhist(1)}) quantifies the
+The following table (inspired by @samp{perlhist(1)}) quantifies the
evolution of Automake using these metrics:
@table @asis
projects / platform / upstream / automake.git / commitdiff