A large part of Automake's functionality is dedicated to making it easy to build programs and libraries.
In a directory containing source that gets built into a program (as
opposed to a library), the `PROGRAMS' primary is used. Programs
can be installed in
pkglibdir, or not at all (`noinst'). They can also be built
make check, in which case the prefix is `check'.
bin_PROGRAMS = hello
In this simple case, the resulting `Makefile.in' will contain code
to generate a program named
Associated with each program are several assisting variables which are named after the program. These variables are all optional, and have reasonable defaults. Each variable, its use, and default is spelled out below; we use the "hello" example throughout.
hello_SOURCES is used to specify which source files
get built into an executable:
hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
This causes each mentioned `.c' file to be compiled into the corresponding `.o'. Then all are linked to produce `hello'.
If `hello_SOURCES' is not specified, then it defaults to the single file `hello.c'; that is, the default is to compile a single C file whose base name is the name of the program itself. (This is a terrible default but we are stuck with it for historical reasons.)
Multiple programs can be built in a single directory. Multiple programs can share a single source file, which must be listed in each `_SOURCES' definition.
Header files listed in a `_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 `configure' in a `_SOURCES' variable; this file should not be distributed. Lex (`.l') and Yacc (`.y') files can also be listed; see section Yacc and Lex support.
You can't put a configure substitution (e.g., `@FOO@') into a `_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 `EXTRA_' variable. For instance, if
`hello-linux.c' were conditionally included in
`Makefile.am' would contain:
EXTRA_hello_SOURCES = hello-linux.c
In this case, `hello-linux.o' would be added, via a
`configure' substitution, to
hello_LDADD in order to cause
it to be built and linked in.
An often simpler way to compile source files conditionally is to use Automake conditionals. For instance, you could use this construct to conditionally use `hello-linux.c' or `hello-generic.c' as the basis for your program `hello':
if LINUX hello_SOURCES = hello-linux.c else hello_SOURCES = hello-generic.c endif
When using conditionals like this you don't need to use the `EXTRA_' variable, because Automake will examine the contents of each variable to construct the complete list of source files.
Sometimes it is useful to determine the programs that are to be built at
configure time. For instance, GNU
cpio only builds
rmt under special circumstances.
In this case, you must notify Automake of all the programs that can
possibly be built, but at the same time cause the generated
`Makefile.in' to use the programs specified by
This is done by having
configure substitute values into each
`_PROGRAMS' definition, while listing all optionally built programs
Of course you can use Automake conditionals to determine the programs to be built.
Sometimes, multiple programs are built in one directory but do not share
the same link-time requirements. In this case, you can use the
`prog_LDADD' variable (where prog is the name of the
program as it appears in some `_PROGRAMS' variable, and usually
written in lowercase) to override the global
LDADD. If this
variable exists for a given program, then that program is not linked
For instance, in GNU cpio,
linked against the library `libcpio.a'. However,
built in the same directory, and has no such link requirement. Also,
rmt are only built on certain architectures. Here
is what cpio's `src/Makefile.am' looks like (abridged):
bin_PROGRAMS = cpio pax @MT@ libexec_PROGRAMS = @RMT@ EXTRA_PROGRAMS = mt rmt LDADD = ../lib/libcpio.a @INTLLIBS@ rmt_LDADD = cpio_SOURCES = ... pax_SOURCES = ... mt_SOURCES = ... rmt_SOURCES = ...
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 `prog_DEPENDENCIES' variable. Each program depends on the contents of such a variable, but no further interpretation is done.
If `prog_DEPENDENCIES' is not supplied, it is computed by Automake. The automatically-assigned value is the contents of `prog_LDADD', with most configure substitutions, `-l', `-L', `-dlopen' and `-dlpreopen' options removed. The configure substitutions that are left in are only `@LIBOBJS@' and `@ALLOCA@'; these are left because it is known that they will not cause an invalid value for `prog_DEPENDENCIES' to be generated.
Building a library is much like building a program. In this case, the
name of the primary is `LIBRARIES'. Libraries can be installed in
See section Building a Shared Library, for information on how to build shared libraries using Libtool and the `LTLIBRARIES' primary.
Each `_LIBRARIES' variable is a list of the libraries to be built. For instance to create a library named `libcpio.a', but not install it, you would write:
noinst_LIBRARIES = libcpio.a
The sources that go into a library are determined exactly as they are for programs, via the `_SOURCES' variables. Note that the library name is canonicalized (see section How derived variables are named), so the `_SOURCES' variable corresponding to `liblob.a' is `liblob_a_SOURCES', not `liblob.a_SOURCES'.
libcpio_a_LIBADD = @LIBOBJS@ @ALLOCA@
In addition, sources for extra objects that will not exist until
configure-time must be added to the
(see section Built sources).
Building shared libraries is a relatively complex matter. For this reason, GNU Libtool (see section `Introduction' in The Libtool Manual) was created to help build shared libraries in a platform-independent way.
Automake uses Libtool to build libraries declared with the `LTLIBRARIES' primary. Each `_LTLIBRARIES' variable is a list of shared libraries to build. For instance, to create a library named `libgettext.a' and its corresponding shared libraries, and install them in `libdir', write:
lib_LTLIBRARIES = libgettext.la
Note that shared libraries must be installed, so
check_LTLIBRARIES is not allowed. However,
noinst_LTLIBRARIES is allowed. This feature should be used for
libtool "convenience libraries".
For each library, the `library_LIBADD' variable contains the names of extra libtool objects (`.lo' files) to add to the shared library. The `library_LDFLAGS' variable contains any additional libtool flags, such as `-version-info' or `-static'.
Where an ordinary library might include
@LIBOBJS@, a libtool
library must use
@LTLIBOBJS@. This is required because the
object files that libtool operates on do not necessarily end in
`.o'. The libtool manual contains more details on this topic.
For libraries installed in some directory, Automake will automatically
supply the appropriate `-rpath' option. However, for libraries
determined at configure time (and thus mentioned in
EXTRA_LTLIBRARIES), Automake does not know the eventual
installation directory; for such libraries you must add the
`-rpath' option to the appropriate `_LDFLAGS' variable by
Ordinarily, Automake requires that a shared library's name start with
`lib'. However, if you are building a dynamically loadable module
then you might wish to use a "nonstandard" name. In this case, put
-module into the `_LDFLAGS' variable.
See section `The Libtool Manual' in The Libtool Manual, for more information.
Associated with each program are a collection of variables which can be used to modify how that program is built. There is a similar list of such variables for each library. The canonical name of the program (or library) is used as a base for naming these variables.
In the list below, we use the name "maude" to refer to the program or library. In your `Makefile.am' you would replace this with the canonical name of your program. This list also refers to "maude" as a program, but in general the same rules apply for both static and dynamic libraries; the documentation below notes situations where programs and libraries differ.
nodist_maude_SOURCES = nodist.c dist_maude_SOURCES = dist-me.cBy default the output file (on Unix systems, the `.o' file) will be put into the current build directory. However, if the option
subdir-objectsis in effect in the current directory then the `.o' file will be put into the subdirectory named after the source file. For instance, with
subdir-objectsenabled, `sub/dir/file.c' will be compiled to `sub/dir/file.o'. Some people prefer this mode of operation. You can specify
AUTOMAKE_OPTIONS(see section Changing Automake's Behavior).
$(AR) crufollowed by the name of the library and then the objects being put into the library. You can override this by setting the `_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 macro set like so:
libmaude_a_AR = $(CXX) -ar -o
configure. Note that `_LIBADD' is not used for shared libraries; there you must use `_LDADD'.
configure. `_LDADD' is inappropriate for passing program-specific linker flags (except for `-l', `-L', `-dlopen' and `-dlpreopen'). Use the `_LDFLAGS' variable for this purpose. For instance, if your `configure.in' uses
AC_PATH_XTRA, you could link your program against the X libraries like so:
maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
maude_LINK = $(CCLD) -magic -o $@
maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
Automake explicitly recognizes the use of
@ALLOCA@, and uses this information, plus the list of
LIBOBJS files derived from `configure.in' to automatically
include the appropriate source files in the distribution (see section What Goes in a Distribution).
These source files are also automatically handled in the
dependency-tracking scheme; see See section Automatic dependency tracking.
@ALLOCA@ are specially recognized in any
`_LDADD' or `_LIBADD' variable.
Occasionally it is useful to know which `Makefile' variables Automake uses for compilations; for instance you might need to do your own compilation in some special cases.
There are some additional variables which Automake itself defines:
AM_CONFIG_HEADER). You can disable the default `-I' options using the `nostdinc' option.
CFLAGS); it takes as "arguments" the names of the object files and libraries to link in.
Automake has somewhat idiosyncratic support for Yacc and Lex.
Automake assumes that the `.c' file generated by
lex) should be named using the basename of the input file. That
is, for a yacc source file `foo.y', Automake will cause the
intermediate file to be named `foo.c' (as opposed to
`y.tab.c', which is more traditional).
The extension of a yacc source file is used to determine the extension of the resulting `C' or `C++' file. Files with the extension `.y' will be turned into `.c' files; likewise, `.yy' will become `.cc'; `.y++', `c++'; and `.yxx', `.cxx'.
Likewise, lex source files can be used to generate `C' or `C++'; the extensions `.l', `.ll', `.l++', and `.lxx' are recognized.
You should never explicitly mention the intermediate (`C' or `C++') file in any `SOURCES' variable; only list the source file.
The intermediate files generated by
lex) will be
included in any distribution that is made. That way the user doesn't
need to have
yacc source file is seen, then your `configure.in' must
define the variable `YACC'. This is most easily done by invoking
the macro `AC_PROG_YACC' (see section `Particular Program Checks' in The Autoconf Manual).
yacc is invoked, it is passed `YFLAGS' and
`AM_YFLAGS'. The former is a user variable and the latter is
intended for the `Makefile.am' author.
Similarly, if a
lex source file is seen, then your
`configure.in' must define the variable `LEX'. You can use
`AC_PROG_LEX' to do this (see section `Particular Program Checks' in The Autoconf Manual). Automake's
support also requires that you use the `AC_DECL_YYTEXT'
macro--automake needs to know the value of `LEX_OUTPUT_ROOT'.
This is all handled for you if you use the
(see section Autoconf macros supplied with Automake).
yacc is invoked, it is passed `LFLAGS' and
`AM_LFLAGS'. The former is a user variable and the latter is
intended for the `Makefile.am' author.
Automake makes it possible to include multiple
lex) source files in a single program. Automake uses a small
ylwrap to run
lex) in a
subdirectory. This is necessary because yacc's output filename is
fixed, and a parallel make could conceivably invoke more than one
yacc simultaneously. The
ylwrap program is
distributed with Automake. It should appear in the directory specified
by `AC_CONFIG_AUX_DIR' (see section `Finding `configure' Input' in The Autoconf Manual), or the current directory if that macro
is not used in `configure.in'.
yacc, simply managing locking is insufficient. The output of
yacc always uses the same symbol names internally, so it isn't
possible to link two
yacc parsers into the same executable.
We recommend using the following renaming hack used in
#define yymaxdepth c_maxdepth #define yyparse c_parse #define yylex c_lex #define yyerror c_error #define yylval c_lval #define yychar c_char #define yydebug c_debug #define yypact c_pact #define yyr1 c_r1 #define yyr2 c_r2 #define yydef c_def #define yychk c_chk #define yypgo c_pgo #define yyact c_act #define yyexca c_exca #define yyerrflag c_errflag #define yynerrs c_nerrs #define yyps c_ps #define yypv c_pv #define yys c_s #define yy_yys c_yys #define yystate c_state #define yytmp c_tmp #define yyv c_v #define yy_yyv c_yyv #define yyval c_val #define yylloc c_lloc #define yyreds c_reds #define yytoks c_toks #define yylhs c_yylhs #define yylen c_yylen #define yydefred c_yydefred #define yydgoto c_yydgoto #define yysindex c_yysindex #define yyrindex c_yyrindex #define yygindex c_yygindex #define yytable c_yytable #define yycheck c_yycheck #define yyname c_yyname #define yyrule c_yyrule
For each define, replace the `c_' prefix with whatever you like.
These defines work for
byacc, and traditional
yaccs. 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.
Automake includes full support for C++.
Any package including C++ code must define the output variable
`CXX' in `configure.in'; the simplest way to do this is to use
AC_PROG_CXX macro (see section `Particular Program Checks' in The Autoconf Manual).
A few additional variables are defined when a C++ source file is seen:
Automake includes some support for assembly code.
AS 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 `-c' and `-o'. The value of
ASFLAGS is passed to the compilation.
You are required to set
`configure.in'. The autoconf macro
AM_PROG_AS will do this
for you. Unless they are already set, it simply sets
AS to the C
ASFLAGS to the C compiler flags.
Automake includes full support for Fortran 77.
Any package including Fortran 77 code must define the output variable
`F77' in `configure.in'; the simplest way to do this is to use
AC_PROG_F77 macro (see section `Particular Program Checks' in The Autoconf Manual). See section Fortran 77 and Autoconf.
A few additional variables are defined when a Fortran 77 source file is seen:
Automake can handle preprocessing Fortran 77 and Ratfor source files in addition to compiling them(4). Automake also contains some support for creating programs and shared libraries that are a mixture of Fortran 77 and other languages (see section Mixing Fortran 77 With C and C++).
These issues are covered in the following sections.
`N.f' is made automatically from `N.F' or `N.r'. This rule runs just the preprocessor to convert a preprocessable Fortran 77 or Ratfor source file into a strict Fortran 77 source file. The precise command used is as follows:
$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)
$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)
`N.o' is made automatically from `N.f', `N.F' or `N.r' by running the Fortran 77 compiler. The precise command used is as follows:
$(F77) -c $(AM_FFLAGS) $(FFLAGS)
$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)
$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)
Automake currently provides limited support for creating programs and shared libraries that are a mixture of Fortran 77 and C and/or C++. However, there are many other issues related to mixing Fortran 77 with other languages that are not (currently) handled by Automake, but that are handled by other packages(5).
Automake can help in two ways:
AC_F77_LIBRARY_LDFLAGSAutoconf macro supplied with newer versions of Autoconf (Autoconf version 2.13 and later). See section `Fortran 77 Compiler Characteristics' in The Autoconf.
If Automake detects that a program or shared library (as mentioned in
_LTLIBRARIES primary) contains source
code that is a mixture of Fortran 77 and C and/or C++, then it requires
that the macro
AC_F77_LIBRARY_LDFLAGS be called in
`configure.in', and that either
appear in the appropriate
_LDADD (for programs) or
(for shared libraries) variables. It is the responsibility of the
person writing the `Makefile.am' to make sure that
@FLIBS@ appears in the appropriate
For example, consider the following `Makefile.am':
bin_PROGRAMS = foo foo_SOURCES = main.cc foo.f foo_LDADD = libfoo.la @FLIBS@ pkglib_LTLIBRARIES = libfoo.la libfoo_la_SOURCES = bar.f baz.c zardoz.cc libfoo_la_LIBADD = $(FLIBS)
In this case, Automake will insist that
is mentioned in `configure.in'. Also, if
been mentioned in
Automake would have issued a warning.
The following diagram demonstrates under what conditions a particular linker is chosen by Automake.
For example, if Fortran 77, C and C++ source code were to be compiled
into a program, then the C++ linker will be used. In this case, if the
C or Fortran 77 linkers required any special libraries that weren't
included by the C++ linker, then they must be manually added to an
_LIBADD variable by the user writing the
\ Linker source \ code \ C C++ Fortran ----------------- +---------+---------+---------+ | | | | C | x | | | | | | | +---------+---------+---------+ | | | | C++ | | x | | | | | | +---------+---------+---------+ | | | | Fortran | | | x | | | | | +---------+---------+---------+ | | | | C + C++ | | x | | | | | | +---------+---------+---------+ | | | | C + Fortran | | | x | | | | | +---------+---------+---------+ | | | | C++ + Fortran | | x | | | | | | +---------+---------+---------+ | | | | C + C++ + Fortran | | x | | | | | | +---------+---------+---------+
The current Automake support for Fortran 77 requires a recent enough version Autoconf that also includes support for Fortran 77. Full Fortran 77 support was added to Autoconf 2.13, so you will want to use that version of Autoconf or later.
Automake includes support for compiled Java, using
gcj, the Java
front end to the GNU Compiler Collection.
Any package including Java code to be compiled must define the output
variable `GCJ' in `configure.in'; the variable `GCJFLAGS'
must also be defined somehow (either in `configure.in' or
`Makefile.am'). The simplest way to do this is to use the
By default, programs including Java source files are linked with
As always, the contents of `AM_GCJFLAGS' are passed to every
gcj (in its role as an ahead-of-time
compiler -- when invoking it to create `.class' files,
`AM_JAVACFLAGS' is used instead). If it is necessary to pass
gcj from `Makefile.am', this macro, and not the
user macro `GCJFLAGS', should be used.
gcj can be used to compile `.java', `.class',
`.zip', or `.jar' files.
Automake currently only includes full support for C, C++ (see section C++ Support), Fortran 77 (see section Fortran 77 Support), and Java (see section Java Support). There is only rudimentary support for other languages, support for which will be improved based on user demand.
Some limited support for adding your own languages is available via the suffix rule handling; see section Handling new file extensions.
Although the GNU standards allow the use of ANSI C, this can have the effect of limiting portability of a package to some older compilers (notably the SunOS C compiler).
Automake allows you to work around this problem on such machines by de-ANSI-fying each source file before the actual compilation takes place.
If the `Makefile.am' variable
(see section Changing Automake's Behavior) contains the option
ansi2knr then code to
handle de-ANSI-fication is inserted into the generated
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
ansi2knr program is used to convert the source
files into K&R C, which is then compiled.
ansi2knr program is simple-minded. It assumes the source
code will be formatted in a particular way; see the
page for details.
Support for de-ANSI-fication requires the source files `ansi2knr.c'
and `ansi2knr.1' to be in the same package as the ANSI C source;
these files are distributed with Automake. Also, the package
`configure.in' must call the macro
(see section Autoconf macros supplied with Automake).
Automake also handles finding the
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
option. For instance, suppose the package has ANSI C code in the
`src' and `lib' subdirs. The files `ansi2knr.c' and
`ansi2knr.1' appear in `lib'. Then this could appear in
AUTOMAKE_OPTIONS = ../lib/ansi2knr
If no directory prefix is given, the files are assumed to be in the current directory.
Files mentioned in
LIBOBJS which need de-ANSI-fication will not
be automatically handled. That's because
configure will generate
an object name like `regex.o', while
make will be looking
for `regex_.o' (when de-ANSI-fying). Eventually this problem will
be fixed via
autoconf magic, but for now you must put this code
into your `configure.in', just before the
# This is necessary so that .o files in LIBOBJS are also built via # the ANSI2KNR-filtering rules. LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
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
ansi2knr for the build machine.
As a developer it is often painful to continually update the `Makefile.in' whenever the include-file dependencies change in a project. Automake supplies a way to automatically track dependency changes.
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
depcomp understands how to coax many different C
and C++ compilers into generating dependency information in the format
automake -a will install
depcomp into your
source tree for you. If
depcomp can't figure out how to properly
invoke your compiler, dependency tracking will simply be disabled for
Experience with earlier versions of Automake (6) taught us that it is not reliable to generate dependencies only on the maintainer's system, as configurations vary too much. So instead Automake implements dependency tracking at build time.
Automatic dependency tracking can be suppressed by putting
no-dependencies in the variable
AUTOMAKE_OPTIONS. Or, you
automake with the
-i option. Dependency
tracking is enabled by default.
The person building your package also can choose to disable dependency
tracking by configuring with
On some platforms, such as Windows, executables are expected to have an extension such as `.exe'. On these platforms, some compilers (GCC among them) will automatically generate `foo.exe' when asked to generate `foo'.
Automake provides mostly-transparent support for this. Unfortunately the support isn't completely transparent; if you want your package to support these platforms then you must assist.
One thing you must be aware of is that, internally, Automake rewrites something like this:
bin_PROGRAMS = liver
bin_PROGRAMS = liver$(EXEEXT)
The targets Automake generates are likewise given the `$(EXEEXT)'
However, Automake cannot apply this rewriting to
substitutions. This means that if you are conditionally building a
program using such a substitution, then your `configure.in' must
take care to add `$(EXEEXT)' when constructing the output variable.
With Autoconf 2.13 and earlier, you must explicitly use
to get this support. With Autoconf 2.50,
AC_EXEEXT is run
automatically if you configure a compiler (say, through
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 `$(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
(see section Changing Automake's Behavior) will disable this feature. This works in a fairly
ugly way; if
no-exeext is seen, then the presence of a target
foo in `Makefile.am' will override an
automake-generated target of the form
foo$(EXEEXT). Without the
no-exeext option, this use will give an error.