@section General Operation
Automake works by reading a @file{Makefile.am} and generating a
-@file{Makefile.in}. Certain variables and targets defined in the
+@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 targets
+for instance, a @samp{bin_PROGRAMS} variable definition will cause rules
for compiling and linking programs to be generated.
@cindex Non-standard targets
@cindex cvs-dist, non-standard example
@trindex cvs-dist
-The variable definitions and targets in the @file{Makefile.am} are copied
-verbatim into the generated file. This allows you to add arbitrary code
-into the generated @file{Makefile.in}. For instance the Automake
-distribution includes a non-standard @code{cvs-dist} target, which the
-Automake maintainer uses to make distributions from his source control
-system.
+The variable definitions and rules in the @file{Makefile.am} are
+copied verbatim into the generated file. This allows you to add
+arbitrary code into the generated @file{Makefile.in}. For instance
+the Automake distribution includes a non-standard rule for the
+@code{cvs-dist} target, which the Automake maintainer uses to make
+distributions from his source control system.
@cindex GNU make extensions
specified on the left. Automake will translate the operator into
an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
-Automake tries to keep comments grouped with any adjoining targets or
+Automake tries to keep comments grouped with any adjoining rules or
variable definitions.
@cindex Make targets, overriding
+@cindex Make rules, overriding
+@cindex Overriding make rules
@cindex Overriding make targets
-A target defined in @file{Makefile.am} generally overrides any such
-target of a similar name that would be automatically generated by
+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
best to avoid making use of it, as sometimes the generated rules are
very particular.
@cindex Variables, overriding
@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 create. This feature is more often
-useful than the ability to override a target definition. Be warned that
-many of the variables generated by @code{automake} are considered to be for
-internal use only, and their names might change in future releases.
+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
+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
+names might change in future releases.
@cindex Recursive operation of Automake
@cindex Automake, recursive operation
instance, @code{CFLAGS} is one such variable.
Sometimes package developers are tempted to set user variables such as
-@code{CFLAGS} because it appears to make their job easier -- they don't
-have to introduce a second variable into every target.
-
-However, the package itself should never set a user variable,
-particularly not to include switches which are required for proper
-compilation of the package. Since these variables are documented as
-being for the package builder, that person rightfully expects to be able
-to override any of these variables at build time.
+@code{CFLAGS} because it appears to make their job easier. However,
+the package itself should never set a user variable, particularly not
+to include switches which are required for proper compilation of the
+package. Since these variables are documented as being for the
+package builder, that person rightfully expects to be able to override
+any of these variables at build time.
To get around this problem, automake introduces an automake-specific
shadow variable for each user flag variable. (Shadow variables are not
@vindex SUBDIRS
The @code{SUBDIRS} variable holds a list of subdirectories in which
-building of various sorts can occur. Many targets (e.g. @code{all}) in
-the generated @file{Makefile} will run both locally and in all specified
-subdirectories. Note that the directories listed in @code{SUBDIRS} are
-not required to contain @file{Makefile.am}s; only @file{Makefile}s
-(after configuration). This allows inclusion of libraries from packages
-which do not use Automake (such as @code{gettext}).
+building of various sorts can occur. The rules for many targets
+(e.g. @code{all}) in the generated @file{Makefile} will run commands
+both locally and in all specified subdirectories. Note that the
+directories listed in @code{SUBDIRS} are not required to contain
+@file{Makefile.am}s; only @file{Makefile}s (after configuration).
+This allows inclusion of libraries from packages which do not use
+Automake (such as @code{gettext}).
In packages that use subdirectories, the top-level @file{Makefile.am} is
often very short. For instance, here is the @file{Makefile.am} from the
of arbitrary depth this way.
By default, Automake generates @file{Makefiles} which work depth-first
-(@samp{postfix}). 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
-directories. All @samp{clean} targets are run in reverse order of build
-targets.
+(@samp{postfix}). 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 directories. All @samp{clean} rules are run in reverse
+order of build rules.
@section Conditional subdirectories
@cindex Subdirectories, building conditionally
@subsection How @code{DIST_SUBDIRS} is used
@cindex @code{DIST_SUBDIRS}, explained
-As shown in the above examples, @code{DIST_SUBDIRS} is used by targets
+As shown in the above examples, @code{DIST_SUBDIRS} is used in rules
that need to recurse in all directories, even those which have been
conditionally left out of the build.
Precisely, @code{DIST_SUBDIRS} is used by @code{make dist}, @code{make
distclean}, and @code{make maintainer-clean}. All other recursive
-targets use @code{SUBDIRS}.
+rules use @code{SUBDIRS}.
Automake will define @code{DIST_SUBDIRS} automatically from the
possibles values of @code{SUBDIRS} in all conditions.
@file{.lo} files and how libtool constructs them: this is libtool's
concern, and the last thing one wants is to learn about libtool's
guts. However the existence of these files matters, because they are
-used as targets and dependencies in @file{Makefile}s when building
-libtool libraries. There are situations where you may have to refer
-to these, for instance when expressing dependencies for building
-source files conditionally (@pxref{Conditional Libtool Sources}).
+used as targets and dependencies in @file{Makefile}s rules when
+building libtool libraries. There are situations where you may have
+to refer to these, for instance when expressing dependencies for
+building source files conditionally (@pxref{Conditional Libtool
+Sources}).
@cindex libltdl, introduction
Sometimes maintainers like to write an explicit link rule for their
program. Without executable extension support, this is easy---you
-simply write a target with the same name as the program. However, when
-executable extension support is enabled, you must instead add the
+simply write a rule whose target is the name of the program. However,
+when executable extension support is enabled, you must instead add the
@samp{$(EXEEXT)} suffix.
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} 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 target
-named @code{foo} in @file{Makefile.am} will override an
-automake-generated target of the form @code{foo$(EXEEXT)}. Without the
-@code{no-exeext} option, this use will give an error.
+who know their package will never run on a platform that has
+executable extensions. For those maintainers, the @code{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
+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.
@node Other objects
@unnumberedsubsec Recording dependencies manually
Usually people are happy enough with @code{BUILT_SOURCES} because they
-never run targets such as @code{make foo} before @code{make all}, as in
+never run rules such as @code{make foo} before @code{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}.
foo} on a clean tree is important to you.
You won't add explicit dependencies if you are leery of overriding
-an Automake target by mistake.
+an Automake rule by mistake.
Building files from @file{./configure} is not always possible, neither
is converting @file{.h} files into @file{.c} files.
@code{TEXINFO_TEX} is preferable, however, because that allows the
@code{dvi}, @code{ps}, and @code{pdf} targets to still work.
+@cindex Rule, install-info
+@cindex Rule, noinstall-info
@cindex Target, install-info
@cindex Target, noinstall-info
-@cindex install-info target
-@cindex noinstall-info target
+@cindex install-info rule
+@cindex noinstall-info rule
@opindex no-installinfo
@trindex install-info
-Automake generates an @code{install-info} target; some people apparently
+Automake generates an @code{install-info} rule; some people apparently
use this. By default, info pages are installed by @samp{make install}.
This can be prevented via the @code{no-installinfo} option.
In this case, @file{rename.man} will be renamed to @file{rename.1} when
installed, but the other files will keep their names.
+@cindex Rule, install-man
+@cindex Rule, noinstall-man
@cindex Target, install-man
@cindex Target, noinstall-man
-@cindex install-man target
-@cindex noinstall-man target
+@cindex install-man rule
+@cindex noinstall-man rule
@c Use @samp{make install} per documentation: (texi)code.
By default, man pages are installed by @samp{make install}. However,
@section The two parts of install
Automake generates separate @code{install-data} and @code{install-exec}
-targets, in case the installer is installing on multiple machines which
+rules, in case the installer is installing on multiple machines which
share directory structure---these targets allow the machine-independent
parts to be installed only once. @code{install-exec} installs
platform-dependent files, and @code{install-data} installs
@section Extending installation
It is possible to extend this mechanism by defining an
-@code{install-exec-local} or @code{install-data-local} target. If these
-targets exist, they will be run at @samp{make install} time. These
+@code{install-exec-local} or @code{install-data-local} rule. If these
+rules exist, they will be run at @samp{make install} time. These
rules can do almost anything; care is required.
@trindex install-exec-local
@trindex install-data-local
@section Rules for the user
-Automake also generates an @code{uninstall} target, an
-@code{installdirs} target, and an @code{install-strip} target.
+Automake also generates rules for targets @code{uninstall},
+@code{installdirs}, and @code{install-strip}.
@trindex uninstall
@trindex installdirs
@trindex install-strip
@vindex MAINTAINERCLEANFILES
As the GNU Standards aren't always explicit as to which files should be
-removed by which target, we've adopted a heuristic which we believe was
+removed by which rule, we've adopted a heuristic which we believe was
first formulated by Fran@,{c}ois Pinard:
@itemize @bullet
@cindex make dist
-The @code{dist} target in the generated @file{Makefile.in} can be used
+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}
@trindex dist-hook
Occasionally it is useful to be able to change the distribution before
-it is packaged up. If the @code{dist-hook} target exists, it is run
+it is packaged up. If the @code{dist-hook} rule exists, it is run
after the distribution directory is filled, but before the actual tar
(or shar) file is created. One way to use this is for distributing
files in subdirectories for which a new @file{Makefile.am} is overkill:
@vindex distdir
@vindex top_distdir
-Two variables that come handy when writing @code{dist-hook} targets are
+Two variables that come handy when writing @code{dist-hook} rules are
@code{$(distdir)} and @code{$(top_distdir)}.
-@code{$(distdir)} points to the directory where the @code{dist} target
+@code{$(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 =
$(PACKAGE)-$(VERSION)}. When used from subdirectory named
@cindex make distuninstallcheck
@vindex distuninstallcheck_listfiles
-Automake also generates a @code{distcheck} target which can be of help
+Automake also generates a @code{distcheck} rule which can be of help
to ensure that a given distribution will actually work.
@code{distcheck} makes a distribution, then tries to do a @code{VPATH}
build, run the test suite, and finally make another tarfile to ensure the
@file{Makefile.am}, or on the command line when invoking @code{make}.
@vindex DISTCHECK_CONFIGURE_FLAGS
-If the target @code{distcheck-hook} is defined in your
+If the @code{distcheck-hook} rule is defined in your
@file{Makefile.am}, then it will be invoked by @code{distcheck} after
-the new distribution has been unpacked, but before the unpacked copy is
-configured and built. Your @code{distcheck-hook} can do almost
+the new distribution has been unpacked, but before the unpacked copy
+is configured and built. Your @code{distcheck-hook} can do almost
anything, though as always caution is advised. Generally this hook is
used to check for potential distribution errors not caught by the
standard mechanism.
Speaking about potential distribution errors, @code{distcheck} will also
-ensure that the @code{distclean} target actually removes all built
+ensure that the @code{distclean} rule actually removes all built
files. This is done by running @code{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
The @code{distcleancheck} behavior should be OK for most packages,
otherwise you have the possibility to override the definition of
-either the @code{distcleancheck} target, or the
+either the @code{distcleancheck} rule, or the
@code{$(distcleancheck_listfiles)} variable. For instance to disable
@code{distcleancheck} completely, add the following rule to your
top-level @file{Makefile.am}:
a FAQ entry about this (@pxref{distcleancheck}), make sure you read it
before playing with @code{distcleancheck_listfiles}.
-@code{distcheck} also checks that the @code{uninstall} target works
+@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
to see if any files are left over. This check will make sure that you
-correctly coded your @code{uninstall}-related targets.
+correctly coded your @code{uninstall}-related rules.
-By default, the checking is done by the @code{distuninstallcheck} target,
+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
a shell command to run that prints the list of files to stdout).
@section The types of distributions
-Automake generates targets to provide archives of the project for
-distributions in various formats. These targets are:
+Automake generates rules to provide archives of the project for
+distributions in various formats. Their targets are:
@table @asis
@item @code{dist-bzip2}
@trindex dist-tarZ
@end table
-The targets @code{dist} and its synonym @code{dist-all} will create
-archives in all the enabled formats, @ref{Options}. By default, only
-the @code{dist-gzip} target is hooked to @code{dist}.
+The rule @code{dist} (and its historical synonym @code{dist-all}) will
+create archives in all the enabled formats, @ref{Options}. By
+default, only the @code{dist-gzip} target is hooked to @code{dist}.
@node Tests
for them in @code{srcdir} (which is both an environment variable and a
make variable) so they work when building in a separate directory
(@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
-Manual}), and in particular for the @code{distcheck} target
+Manual}), and in particular for the @code{distcheck} rule
(@pxref{Dist}).
@cindex Exit status 77, special interpretation
@section Install Tests
-The @code{installcheck} target is available to the user as a way to run
+The @code{installcheck} rule is available to the user as a way to run
any tests after the package has been installed. You can add tests to
-this by writing an @code{installcheck-local} target.
+this by writing an @code{installcheck-local} rule.
@node Options
@item @code{no-dist}
@cindex Option, no-dist
-Don't emit any code related to @code{dist} target. This is useful
+Don't emit any code related to @code{dist} rule. This is useful
when a package has its own method for making distributions.
@item @code{no-dist-gzip}
@item @code{no-exeext}
@cindex Option, no-exeext
-If your @file{Makefile.am} defines a target @samp{foo}, it will override
-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 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.
+If your @file{Makefile.am} defines a rule for target @samp{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
+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, 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
+rules will still be available. This option is disallowed at
@samp{GNU} strictness and above.
@trindex info
@trindex install-info
@item @code{no-installman}
@cindex Option, 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
+installed by default. However, an @code{install-man} rule will still
be available for optional installation. This option is disallowed at
@samp{GNU} strictness and above.
@trindex install-man
@item @code{std-options}
@cindex Options, std-options
@cindex make installcheck
-Make the @code{installcheck} target check that installed scripts and
+Make the @code{installcheck} rule check that installed scripts and
programs support the @code{--help} and @code{--version} options.
This also provides a basic check that the program's
run-time dependencies are satisfied after installation.
GNU Emacs under some circumstances.
If any C, C++ or Fortran 77 source code or headers are present, then
-@code{tags} and @code{TAGS} targets will be generated for the directory.
+@code{tags} and @code{TAGS} rules will be generated for the directory.
@trindex tags
At the topmost directory of a multi-directory package, a @code{tags}
-target file will be generated which, when run, will generate a
+file will be generated which, when run, will generate a
@file{TAGS} file that includes by reference all @file{TAGS} files from
subdirectories.
-The @code{tags} target will also be generated if the variable
+The @code{tags} file 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
If you add filenames to @samp{ETAGS_ARGS}, you will probably also
want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
-are added directly to the dependencies for the @code{tags} target.
+are added directly to the dependencies for the @code{tags} rule.
@vindex TAGS_DEPENDENCIES
-Automake also generates a @code{ctags} target which can be used to
+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});
@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} target which will run
+Automake will also generate an @code{ID} rule which will run
@code{mkid} on the source. This is only supported on a
directory-by-directory basis.
@trindex id
Automake also supports the @uref{http://www.gnu.org/software/global/,
-GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
+GNU Global Tags program}. The @code{GTAGS} rule runs Global Tags
automatically and puts the result in the top build directory. The
variable @code{GTAGS_ARGS} holds arguments which are passed to
@code{gtags}.
checking; it is advisable to be familiar with the precise requirements
of the GNU standards. Also, @samp{--gnu} can require certain
non-standard GNU programs to exist for use by various maintainer-only
-targets; for instance in the future @code{pathchk} might be required for
+rules; for instance in the future @code{pathchk} might be required for
@samp{make dist}.
@cindex --gnits, complete description
required.
@item
-The @code{check} target doesn't depend on @code{all}.
+The @code{check} rule doesn't depend on @code{all}.
@end itemize
GNU maintainers are advised to use @samp{gnu} strictness in preference
@cindex -hook targets
@cindex hook targets
-Some targets also have a way to run another target, called a @dfn{hook},
+Some rule also have a way to run another rule, called a @dfn{hook},
after their work is done. The hook is named after the principal target,
with @samp{-hook} appended. The targets allowing hooks are
@code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
@heading What is in the API
Automake's programming interface is not easy to define. Basically it
-should include at least all @strong{documented} variables and targets
+should include at least all @strong{documented} variables and rules
that a @samp{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{}
One way to get CVS and @code{make} working peacefully is to never
store generated files in CVS, i.e., do not CVS-control files which are
-@code{Makefile} targets (or @emph{derived} files in Make terminology).
+@code{Makefile} rules (or @emph{derived} files in Make terminology).
This way developers are not annoyed by changes to generated files. It
does not matter if they all have different versions (assuming they are
git://sourceware.org / automake.git / commitdiff