@cindex Constraints of Automake
@cindex Automake constraints
-Automake does constrain a project in certain ways; for instance it
+Automake does constrain a project in certain ways; for instance, it
assumes that the project uses Autoconf (@pxref{Top, , Introduction,
autoconf, The Autoconf Manual}), and enforces certain restrictions on
the @file{configure.ac} contents@footnote{Older Autoconf versions used
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
+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.
@opindex -a
@opindex --add-missing
Automake requires certain common files to exist in certain situations;
-for instance @file{config.guess} is required if @file{configure.ac} runs
+for instance, @file{config.guess} is required if @file{configure.ac} runs
@code{AC_CANONICAL_HOST}. Automake is distributed with several of these
files (@pxref{Auxiliary Programs}); this option will cause the missing
ones to be automatically added to the package, whenever possible. In
@end table
A category can be turned off by prefixing its name with @samp{no-}. For
-instance @option{-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
fine if the @code{AC_CONFIG_FILES} specifications contain only
literals. If part of the specification uses shell variables,
@command{automake} will not be able to fulfil this setup, and you will
-have to complete the missing bits by hand. For instance on
+have to complete the missing bits by hand. For instance, on
@example
file=input
that is compatible with @command{make}'s syntax) and furthermore use
@code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
@file{Makefile}, then @command{automake} will be able to use
-@samp{$@{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:
macros, so it is easy to extend it with your own macros.
This can be used by libraries that want to supply their own Autoconf
-macros for use by other programs. For instance the @command{gettext}
+macros for use by other programs. For instance, the @command{gettext}
library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
any package using @command{gettext}. When the library is installed, it
installs this macro so that @command{aclocal} will find it.
not actually needed. Doing so should alleviate many problems of the
current implementation, however it requires a stricter style from the
macro authors. Hopefully it is easy to revise the existing macros.
-For instance
+For instance,
@example
# bad style
AC_PREREQ(2.57)
However there is no consensus on the distribution of third-party
macros that your package may use. Many libraries install their own
macro in the system-wide @command{aclocal} directory (@pxref{Extending
-aclocal}). For instance Guile ships with a file called
+aclocal}). For instance, Guile ships with a file called
@file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
be used to define setup compiler and linker flags appropriate for
using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
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
+instance, if you have modified your local macros, do not expect
@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 @samp{aclocal -I m4 --install}.
indication of how that feature is misplaced.
The new implementation will probably be done slightly differently.
-For instance it could enforce the @file{m4/}-style layout discussed in
+For instance, it could enforce the @file{m4/}-style layout discussed in
@ref{Local Macros}.
We have no idea when and how this will happen. This has been
In order to prevent recursion in some non-configured directory you
must therefore ensure that this directory does not appear in
-@code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance if you define
+@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
@samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
Of course, directories that are omitted from @code{DIST_SUBDIRS} will
not be distributed unless you make other arrangements for this to
-happen (for instance always running @samp{make dist} in a
+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).
Finally, note that a variable using the @samp{nobase_} prefix can
always be replaced by several variables, one for each destination
-directory (@pxref{Uniform}). For instance the last example could be
+directory (@pxref{Uniform}). For instance, the last example could be
rewritten as follows:
@example
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
+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}
package, and another one in the @file{hand/} subdirectory for the
@code{hand} package.
libraries using libtool and the @code{LTLIBRARIES} primary.
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
+For instance, to create a library named @file{libcpio.a}, but not install
it, you would write:
@example
files in the @code{EXTRA_} variable.
This variable also supports @code{dist_} and @code{nodist_} prefixes.
-For instance @code{nodist_EXTRA_maude_SOURCES} would list extra
+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
@item maude_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
+variable. For instance, this should be used for objects determined by
@command{configure} (@pxref{A Library}).
In the case of libtool libraries, @code{maude_LIBADD} can also refer
@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
-@code{_LDADD} variable. For instance this should be used for objects
+@code{_LDADD} variable. For instance, this should be used for objects
determined by @command{configure} (@pxref{Linking}).
@code{_LDADD} and @code{_LIBADD} are inappropriate for passing
@cindex @code{check_PROGRAMS} example
@vindex check_PROGRAMS
Default sources are mainly useful in test suites, when building many
-tests programs each from a single source. For instance in
+tests programs each from a single source. For instance, in
@example
check_PROGRAMS = test1 test2 test3
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
+contains unprefixed object names, and, for instance,
@file{malloc.$(OBJEXT)} is not buildable in the @file{src/} directory.
(Actually if you try using @samp{$(LIBOBJS)} in @file{src/}, Automake
will require a copy of @file{malloc.c}, @file{memcmp.c},
@section Variables used when building a program
Occasionally it is useful to know which @file{Makefile} variables
-Automake uses for compilations; for instance you might need to do your
+Automake uses for compilations; for instance, you might need to do your
own compilation in some special cases.
Some variables are inherited from Autoconf; these are @code{CC},
Because---as we have just seen---scripts can be built, they are not
distributed by default. Scripts that should be distributed can be
specified using a @code{dist_} prefix as in other primaries. For
-instance the following @file{Makefile.am} declares that
+instance, the following @file{Makefile.am} declares that
@file{my_script} should be distributed and installed in
@samp{$(sbindir)}.
Header files that must be installed are specified by the
@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
+other directory you may have defined (@pxref{Uniform}). For instance,
@example
include_HEADERS = foo.h bar/bar.h
they can be used to decide whether @file{foo.o} should be rebuilt.
It's a different story if @file{foo.h} doesn't exist by the first
-@command{make} run. For instance there might be a rule to build
+@command{make} run. For instance, there might be a rule to build
@file{foo.h}. This time @file{file.o}'s build will fail because the
compiler can't find @file{foo.h}. @command{make} failed to trigger the
rule to build @file{foo.h} first by lack of dependency information.
@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
variable. Moreover, all built sources do not necessarily have to be
-listed in @code{BUILT_SOURCES}. For instance a generated @file{.c} file
+listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
another source), because it's a known dependency of the associated
object.
it is not even being built on-time. One may wonder what the
@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
+for instance, it should be inspected while generating tags
(@pxref{Tags}). In other words, it does not help our present problem,
and the build would fail identically without it.
@samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
files.
-For instance the following setting can be used to obtain one single
+For instance, the following setting can be used to obtain one single
@file{.html} file per manual, without node separators.
@example
AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
@samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
@samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
-For instance @code{data_DATA} files are installed by @code{install-data},
+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
own commands. Simply define a rule for any of the
@code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
-case is deleting a directory, for instance a directory created by the
+case is deleting a directory, for instance, a directory created by the
test suite:
@example
@vindex dist_
@vindex nodist_
Sometimes you need tighter control over what does @emph{not} go into the
-distribution; for instance you might have source files that are
+distribution; for instance, you might have source files that are
generated and that you do not want to distribute. In this case
Automake gives fine-grained control using the @code{dist} and
@code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
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
-@samp{$(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}:
dependencies. These variable should be defined in all
@file{Makefile}s of the tree (because these two rebuild rules are
output in all them), so it is safer and easier to @code{AC_SUBST} them
-from @file{configure.ac}. For instance the following statement will
+from @file{configure.ac}. For instance, the following statement will
cause @file{configure} to be rerun each time @file{version.sh} is
changed.
@example
@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
+test. For instance, @command{false} (from GNU sh-utils) is never
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
-@samp{$(EXEEXT)} for the sake of Win32 or OS/2. For instance suppose we
+@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}:
@opindex subdir-objects
If this option is specified, then objects are placed into the
subdirectory of the build directory corresponding to the subdirectory of
-the source file. For instance if the source file is
+the source file. For instance, if the source file is
@file{subdir/file.cxx}, then the output file would be
@file{subdir/file.o}.
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 @samp{AM_INIT_AUTOMAKE([-Wall])}
+for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
in your @file{configure.ac}.
@end table
suffixes in the @code{SUFFIXES} variable @strong{before} you define your
implicit rule.
-For instance the following definition prevents Automake to misinterpret
+For instance, the following definition prevents Automake to misinterpret
@samp{.idlC.cpp:} as an attempt to transform @file{.idlC} files into
@file{.cpp} files.
checking; it is advisable to be familiar with the precise requirements
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 @command{pathchk} might be required for
+rules; for instance, in the future @command{pathchk} might be required for
@samp{make dist}.
@cindex @option{--gnits}, complete description
@end example
Although cheaper and more portable than symbolic links, hard links
-will not work everywhere (for instance OS/2 does not have
+will not work everywhere (for instance, OS/2 does not have
@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
In most projects all @file{Makefile}s are generated by Automake. In
some cases, however, projects need to embed subdirectories with
-handwritten @file{Makefile}s. For instance one subdirectory could be
+handwritten @file{Makefile}s. For instance, one subdirectory could be
a third-party project with its own build system, not using Automake.
It is possible to list arbitrary directories in @code{SUBDIRS} or
@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
+to introduce the above required targets. For instance, one may want to
keep the third-party sources untouched to ease upgrades to new
versions.
overridden by new versions (@pxref{Invoking Automake}).
It is important to regenerate all these files each time Automake is
-upgraded, even between bug fixes releases. For instance it is not
+upgraded, even between bug fixes releases. For instance, it is not
unusual for a bug fix to involve changes to both the rules generated
in @file{Makefile.in} and the supporting M4 macros copied to
@file{aclocal.m4}.
or Info documentation, are usually distributed on similar grounds.
Automake outputs rules in @file{Makefile}s to rebuild these files. For
-instance @command{make} will run @command{autoconf} to rebuild
+instance, @command{make} will run @command{autoconf} to rebuild
@file{configure} whenever @file{configure.ac} is changed. This makes
development safer by ensuring a @file{configure} is never out-of-date
with respect to @file{configure.ac}.
what is distributed, and you can checkout any prior version entirely.
@item
-Maintainers can see how generated files evolve (for instance you can
+Maintainers can see how generated files evolve (for instance, you can
see what happens to your @file{Makefile.in}s when you upgrade Automake
and make sure they look OK).
Another class of files not discussed here (because they do not cause
timestamp issues) are files that are shipped with a package, but
-maintained elsewhere. For instance tools like @command{gettextize}
+maintained elsewhere. For instance, tools like @command{gettextize}
and @command{autopoint} (from Gettext) or @command{libtoolize} (from
Libtool), will install or update files in your package.
missing tool, @command{missing} will notice it and warn the user.
Besides the warning, when a tool is missing, @command{missing} will
attempt to fix timestamps in a way that allows the build to continue.
-For instance @command{missing} will touch @file{configure} if
+For instance, @command{missing} will touch @file{configure} if
@command{autoconf} is not installed. When all distributed files are
kept under CVS, this feature of @command{missing} allows user
@emph{with no maintainer tools} to build a package off CVS, bypassing
@item
Using wildcards makes easy to distribute files by mistake. For
-instance some code a developer is experimenting with (a test case,
+instance, some code a developer is experimenting with (a test case,
say) but that should not be part of the distribution.
@item
Using wildcards it's easy to omit some files by mistake. For
-instance one developer creates a new file, uses it at many places,
+instance, one developer creates a new file, uses it at many places,
but forget to commit it. Another developer then checkout the
incomplete project and is able to run `make dist' successfully,
even though a file is missing.
It is also not uncommon to override a user variable at
@command{make}-time. Many installers do this with @code{prefix}, but
-this can be useful with compiler flags too. For instance if, while
+this can be useful with compiler flags too. For instance, if, while
debugging a C++ project, you need to disable optimization in one
specific object file, you can run something like
variables in all @file{Makefile}s.
What we recommend is that you define extra flags in separate
-variables. For instance you may write an Autoconf macro that computes
+variables. For instance, you may write an Autoconf macro that computes
a set of warning options for the C compiler, and @code{AC_SUBST} them
in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
determines which compiler and which linker flags should be used to
every target in a @file{Makefile.in}.
Using variables like this gives you full control over the ordering of
-the flags. For instance if there is a flag in $(WARNINGCFLAGS) that
+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
@samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
been forcefully appended to @code{CFLAGS}, there would be no way to
@subsection Other Variables
There are other variables in Automake that follow similar principles
-to allow user options. For instance Texinfo rules (@pxref{Texinfo})
+to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
DejaGnu tests (@pxref{Tests}) use @code{RUNTESTDEFAULTFLAGS} and
@code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
@command{make} itself.
However you should not think that all variables ending with
-@code{FLAGS} follow this convention. For instance
+@code{FLAGS} follow this convention. For instance,
@code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Dist}),
@code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
are two variables that are only useful to the maintainer and have no
Finally you should not think either that the existence of a per-target
variable implies that of an @code{AM_} variable or that of a user
-variable. For instance the @code{mumble_LDADD} per-target variable
+variable. For instance, the @code{mumble_LDADD} per-target variable
overrides the global @code{LDADD} variable (which is not a user
variable), and @code{mumble_LIBADD} exists only as a per-target
variable. @xref{Program and Library Variables}.
are used.
It's OK to share object files when per-target compilation flags are not
-used. For instance @file{true} and @file{false} will both use
+used. For instance, @file{true} and @file{false} will both use
@file{version.o} in the following example.
@example
Automake supports per-program and per-library compilation flags (see
@ref{Program and Library Variables} and @ref{Flag Variables
Ordering}). With this you can define compilation flags that apply to
-all files compiled for a target. For instance in
+all files compiled for a target. For instance, in
@example
bin_PROGRAMS = foo
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 @samp{foo-foo.o: foo.c} rule yourself.
-We recommend against this, because this is error prone. For instance
+We recommend against this, because this is error prone. For instance,
if you add such a rule to the first example, it will break the day you
decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{renamed
The above scheme can be extended to handle more outputs and more
inputs. One of the outputs is selected to serve as a witness to the
successful completion of the command, it depends upon all inputs, and
-all other outputs depend upon it. For instance if @command{foo}
+all other outputs depend upon it. For instance, if @command{foo}
should additionally read @file{data.bar} and also produce
@file{data.w} and @file{data.x}, we would write:
erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
@command{make} may start both recover rules in parallel. If the two
instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
-data.stamp} concurrently the build is likely to fail (for instance the
+data.stamp} concurrently the build is likely to fail (for instance, the
two rules will create @file{data.tmp}, but only one can rename it).
Admittedly, such a weird situation does not arise during ordinary
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})
+instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
computes @samp{$(lispdir)}:
@example
Tracking Evolution}), this version also supplies a 9-page manual.
At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
-exist, so many things had to be done by hand. For instance here is
+exist, so many things had to be done by hand. For instance, here is
what a configure.in (this is the former name of the
@file{configure.ac} we use today) must contain in order to use
Automake 0.20:
Automake did only know about the @file{Makefile.am}s it processed.
@file{configure.in} was Autoconf's world and the link between Autoconf
and Automake had to be done by the @file{Makefile.am} author. For
-instance if @file{config.h} was generated by @file{configure}, it was the
+instance, if @file{config.h} was generated by @file{configure}, it was the
package maintainer's responsibility to define the @code{CONFIG_HEADER}
variable in each @file{Makefile.am}.
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 @samp{make distcheck} was
+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
projects / platform / upstream / automake.git / commitdiff