VPATH builds have other interesting uses. One is to build the same
sources with multiple configurations. For instance:
+@c Keep in sync with amhello-cflags.test.
@example
~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
~ % @kbd{cd amhello-1.0}
Here is how we could build @code{amhello-1.0} for
@code{i586-mingw32msvc} on a GNU/Linux PC.
+@c Keep in sync with amhello-cross-compile.test.
@smallexample
~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
checking for a BSD-compatible install... /usr/bin/install -c
For instance here is how we could create a binary package containing a
snapshot of all the files to be installed.
+@c Keep in sync with amhello-binpkg.test.
@example
~/amhello-1.0 % @kbd{./configure --prefix /usr}
@dots{}
variables referenced in the definition. For example, if Automake is
looking at the content of @code{foo_SOURCES} in this snippet
+@c Keep in sync with interp.test.
@example
xs = a.c b.c
foo_SOURCES = c.c $(xs)
For instance, the following snippet will install @file{file.xml} into
@samp{$(datadir)/xml}.
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
@example
xmldir = $(datadir)/xml
xml_DATA = file.xml
unlikely case these checks are undesirable, and you really know what
you're doing). For example, Automake would error out on this input:
+@c Should be tested in primary-prefix-invalid-couples.test.
@example
# Forbidden directory combinations, automake will error out on this.
pkglib_PROGRAMS = foo
@noindent
but it will succeed with this:
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
@example
# Work around forbidden directory combinations. Do not use this
# without a very good reason!
@noindent
may also be written as
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
@example
data_DATA = file1 @dots{} file@var{N}
data2dir = $(datadir)
@code{false} in real life, you would probably use per-program
compilation flags, like so:
+@c Keep in sync with specflg7.test and specflg8.test.
@example
bin_PROGRAMS = false true
@command{automake} will not be able to fulfill this setup, and you will
have to complete the missing bits by hand. For instance, on
+@c Keep in sync with output11.test.
@example
file=input
@dots{}
Similarly
+@c Keep in sync with output11.test.
@example
file=output
file2=out:in
A macro file's name should end in @file{.m4}. Such files should be
installed in @file{$(datadir)/aclocal}. This is as simple as writing:
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
@example
aclocaldir = $(datadir)/aclocal
aclocal_DATA = mymacro.m4 myothermacro.m4
@cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
@cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
-@c The test case for the setup described here is
-@c test/subdircond2.test
-@c Try to keep it in sync.
+@c Keep in sync with subcond2.test.
@file{configure} should output the @file{Makefile} for each directory
and define a condition into which @file{opt/} should be built.
@cindex @code{SUBDIRS} and @code{AC_SUBST}
@cindex @code{AC_SUBST} and @code{SUBDIRS}
-@c The test case for the setup described here is
-@c test/subdircond3.test
-@c Try to keep it in sync.
+@c Keep in sync with subcond3.test.
Another possibility is to define @code{MAYBE_OPT} from
@file{./configure} using @code{AC_SUBST}:
directory (@pxref{Uniform}). For instance, the last example could be
rewritten as follows:
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
@example
imagesdir = $(pkgdatadir)/images
soundsdir = $(pkgdatadir)/sounds
select programs to be built. In this case you don't have to worry
about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
+@c Keep in sync with exeext.test.
@example
bin_PROGRAMS = cpio pax
if WANT_MT
@code{@var{library}_LIBADD} variable. This should be used for objects
determined by @command{configure}. Again from @code{cpio}:
+@c Keep in sync with pr401c.test.
@example
libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
@end example
the link rule for these two libraries. Therefore the @option{-rpath}
argument must be explicitly supplied.
+@c Keep in sync with ltcond.test.
@example
EXTRA_LTLIBRARIES = libfoo.la libbar.la
lib_LTLIBRARIES = $(WANTEDLIBS)
it's clear that both libraries will end up in @samp{$(libdir)} if they
are installed.
+@c Keep in sync with ltcond.test.
@example
lib_LTLIBRARIES =
if WANT_LIBFOO
@file{hello-linux.c} or @file{hello-generic.c} with the following
@file{Makefile.am}.
+@c Keep in sync with ltcond2.test.
@example
lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello-common.c
Or we could simply use an Automake conditional as follows.
+@c Keep in sync with ltcond2.test.
@example
lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello-common.c
Here is a sample setup merging libtool convenience libraries from
subdirectories into one main @file{libtop.la} library.
+@c Keep in sync with ltconv.test.
@example
# -- Top-level Makefile.am --
SUBDIRS = sub1 sub2 @dots{}
@code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
options using the @option{nostdinc} option.
+When a file to be included is generated during the build and not part
+of a distribution tarball, its location is under @code{$(builddir)},
+not under @code{$(srcdir)}. This matters especially for packages that
+use header files placed in sub-directories and want to allow builds
+outside the source tree (@pxref{VPATH Builds}). In that case we
+recommend to use a pair of @option{-I} options, such as, e.g.,
+@samp{-Isome/subdir -I$(srcdir)/some/subdir} or
+@samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
+Note that the reference to the build tree should come before the
+reference to the source tree, so that accidentally leftover generated
+files in the source directory are ignored.
+
@code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
per-library) @code{_CPPFLAGS} variable if it is defined.
@cindex Java support
@cindex Support for Java
-Automake includes support for compiled Java, using @command{gcj}, the Java
-front end to the GNU Compiler Collection.
+Automake includes support for natively compiled Java, using @command{gcj},
+the Java front end to the GNU Compiler Collection (preliminary support
+for compiling Java to bytecode using the @command{javac} compiler is
+also present; @pxref{Java}).
Any package including Java code to be compiled must define the output
variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
@example
lisp_DATA = file1.el file2.el
@end example
@cindex @code{JAVA} primary, defined
@cindex Primary variable, @code{JAVA}
-Automake provides some minimal support for Java compilation with the
-@code{JAVA} primary.
+Automake provides some minimal support for Java bytecode compilation with
+the @code{JAVA} primary (in addition to the support for compiling Java to
+native machine code; @pxref{Java Support}).
Any @file{.java} files listed in a @code{_JAVA} variable will be
compiled with @code{JAVAC} at build time. By default, @file{.java}
Here is a typical setup for distributing @file{.java} files and
installing the @file{.class} files resulting from their compilation.
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
@example
javadir = $(datadir)/java
dist_java_JAVA = a.java b.java @dots{}
that will determine some Python-related directory variables (see
below). If you have called @code{AM_PATH_PYTHON} from
@file{configure.ac}, then you may use the variables
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
@code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
files in your @file{Makefile.am}, depending on where you want your files
installed (see the definitions of @code{pythondir} and
should be installed. An extension module written in C could be declared
as follows to Automake:
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
@example
pyexec_LTLIBRARIES = quaternion.la
quaternion_la_SOURCES = quaternion.c support.c support.h
@samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
files.
+@c Keep in sync with txinfo21.test.
For instance, the following setting can be used to obtain one single
@file{.html} file per manual, without node separators.
@example
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., @code{myexecbin_PROGRAMS}) is installed by
-@code{install-exec}. All other user-defined prefixes are installed by
-@code{install-data}.
+Any variable using a user-defined directory prefix with
+@samp{exec} in the name (e.g.,
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
+other user-defined prefixes are installed by @code{install-data}.
@node Extending Installation
@section Extending Installation
or as the target of a @file{Makefile.am} rule); this list is printed by
@samp{automake --help}. Note that some files in this list are actually
distributed only if other certain conditions hold (for example,
-@c The following example is covered by autodist-config-headers.test.
+@c Keep in sync with autodist-config-headers.test.
the @file{config.h.top} and @file{config.h.bot} files are automatically
distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
in @file{configure.ac}). Also, files that are read by @command{configure}
been cleaned because they are also part of the distribution, add the
following definition instead:
+@c Keep in sync with distcleancheck.test.
@example
distcleancheck_listfiles = \
find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
@c FIXME: should we offer a link to the relevant discussions on the
@c bug-autoconf list?
+@c Keep in sync with tests-environment-backcompat.test.
@example
AM_TESTS_ENVIRONMENT = \
## Some environment initializations are kept in a separate shell file
tests without a registered extension, the variables @code{LOG_COMPILER},
@code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
+@c Keep in sync with parallel-tests-log-compiler-example.test.
@example
TESTS = foo.pl bar.py baz
TEST_EXTENSIONS = .pl .py
easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
for example,
+@c Keep in sync with parallel-tests-log-override-2.test.
@example
env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
@end example
the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
@file{.cpp} files.
+@c Keep in sync with suffix7.test.
@example
SUFFIXES = .idl C.cpp
.idlC.cpp:
adding a @samp{yes} argument to the @code{AM_SILENT_RULES} call in
@file{configure.ac}. We advise against this approach, though.
+@c Keep in sync with silent-configsite.test
Users who prefer to have silent rules enabled by default can edit their
@file{config.site} file to make the variable @code{enable_silent_rules}
default to @samp{yes}. This should still allow disabling silent rules
For instance, here is how you could install a versioned copy of a
program using @samp{$(LN_S)}:
+@c Keep in sync with insthook.test
@example
install-exec-hook:
cd $(DESTDIR)$(bindir) && \
When writing @code{install-exec-hook} or @code{install-data-hook},
please bear in mind that the exec/data distinction is based on the
installation directory, not on the primary used (@pxref{The Two Parts of
-Install}). So a @code{foo_SCRIPTS} will be installed by
+Install}).
+@c Keep in sync with primary-prefix-couples-documented-valid.test.
+So a @code{foo_SCRIPTS} will be installed by
@code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
@code{install-exec}. You should define your hooks consequently.