Go to the first, previous, next, last section, table of contents.
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 bindir, sbindir, libexecdir,
pkglibdir, or not at all (`noinst').
For instance:
bin_PROGRAMS = hello
In this simple case, the resulting `Makefile.in' will contain code
to generate a program named hello. The variable
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 `prog_SOURCES' is needed, but not specified, then it defaults to the single file `prog.c'.
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 an `_SOURCES' variable; this file should not be distributed. Lex (`.l') and Yacc (`.y') files can also be listed; see section Yacc and Lex support.
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 hello, the
`Makefile.am' would contain:
EXTRA_hello_SOURCES = hello-linux.c
Similarly, sometimes it is useful to determine the programs that are to
be built at configure time. For instance, GNU cpio only builds
mt and 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 configure.
This is done by having configure substitute values into each
`_PROGRAMS' definition, while listing all optionally built programs
in EXTRA_PROGRAMS.
If you need to link against libraries that are not found by
configure, you can use LDADD to do so. This variable
actually can be used to add any options to the linker command line.
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
using LDADD.
For instance, in GNU cpio, pax, cpio and mt are
linked against the library `libcpio.a'. However, rmt is
built in the same directory, and has no such link requirement. Also,
mt and 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 = ...
`prog_LDADD' is inappropriate for passing program-specific linker flags (except for `-l' and `-L'). So, use the `prog_LDFLAGS' variable for this purpose.
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', and `-L' 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
libdir or pkglibdir.
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'.
Extra objects can be added to a library using the
`library_LIBADD' variable. This should be used for objects
determined by configure. Again from cpio:
libcpio_a_LIBADD = @LIBOBJS@ @ALLOCA@
Automake explicitly recognizes the use of @LIBOBJS@ and
@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.
@LIBOBJS@ and @ALLOCA@ are specially recognized in any
`_LDADD' or `_LIBADD' variable.
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
hand.
See section `The Libtool Manual' in The Libtool Manual, for more information.
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.
Some variables are inherited from Autoconf; these are CC,
CFLAGS, CPPFLAGS, DEFS, LDFLAGS, and
LIBS.
There are some additional variables which Automake itself defines:
INCLUDES
AC_CONFIG_HEADER or
AM_CONFIG_HEADER).
INCLUDES can actually be used for other cpp options
besides `-I'. For instance, it is sometimes used to pass arbitrary
`-D' options to the compiler.
COMPILE
LINK
Automake has somewhat idiosyncratic support for Yacc and Lex.
Automake assumes that the `.c' file generated by yacc (or
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 yacc (or lex) will be
included in any distribution that is made. That way the user doesn't
need to have yacc or lex.
If a 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).
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 lex
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 AM_PROG_LEX macro
(see section Autoconf macros supplied with Automake).
Automake makes it possible to include multiple yacc (or
lex) source files in a single program. Automake uses a small
program called ylwrap to run yacc (or lex) in a
subdirectory. This is necessary because yacc's output filename is
fixed, and a parallel make could conceivably invoke more than one
instance of 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'.
For 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 gdb:
#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 bison, 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
the 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:
CXX
CXXFLAGS
CXXCOMPILE
CXXLINK
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
the 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:
F77
FFLAGS
RFLAGS
F77COMPILE
FLINK
Automake can handle preprocessing Fortran 77 and Ratfor source files in addition to compiling them(1). 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(2).
Automake can help in two ways:
FLIBS by the AC_F77_LIBRARY_LDFLAGS Autoconf 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
some _PROGRAMS or _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 $(FLIBS) or @FLIBS@
appear in the appropriate _LDADD (for programs) or _LIBADD
(for shared libraries) variables. It is the responsibility of the
person writing the `Makefile.am' to make sure that $(FLIBS)
or @FLIBS@ appears in the appropriate _LDADD or
_LIBADD variable.
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 AC_F77_LIBRARY_LDFLAGS
is mentioned in `configure.in'. Also, if @FLIBS@ hadn't
been mentioned in foo_LDADD and libfoo_la_LIBADD, then
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
_LDADD or _LIBADD variable by the user writing the
`Makefile.am'.
\ 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 currently only includes full support for C, C++ (see section C++ Support)and Fortran 77 (see section Fortran 77 Support). There is only rudimentary support for other languages, support for which will be improved based on user demand.
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 SunOS).
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 AUTOMAKE_OPTIONS
(see section Changing Automake's Behavior) contains the option ansi2knr then code to
handle de-ANSI-fication is inserted into the generated
`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 ansi2knr program is used to convert the source
files into K&R C, which is then compiled.
The ansi2knr program is simple-minded. It assumes the source
code will be formatted in a particular way; see the ansi2knr man
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 AM_C_PROTOTYPES
(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 ansi2knr
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
`src/Makefile.am':
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 AC_OUTPUT call:
# 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/'`
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, and distribute the dependencies in the generated `Makefile.in'.
Currently this support requires the use of GNU make and
gcc. It might become possible in the future to supply a
different dependency generating program, if there is enough demand. In
the meantime, this mode is enabled by default if any C program or
library is defined in the current directory, so you may get a `Must
be a separator' error from non-GNU make.
When you decide to make a distribution, the dist target will
re-run automake with `--include-deps' and other options.
See section Creating a `Makefile.in', and section Changing Automake's Behavior. This will cause the
previously generated dependencies to be inserted into the generated
`Makefile.in', and thus into the distribution. This step also
turns off inclusion of the dependency generation code, so that those who
download your distribution but don't use GNU make and gcc
will not get errors.
When added to the `Makefile.in', the dependencies have all system-specific dependencies automatically removed. This can be done by listing the files in `OMIT_DEPENDENCIES'. For instance all references to system header files are removed by Automake. Sometimes it is useful to specify that a certain header file should be removed. For instance if your `configure.in' uses `AM_WITH_REGEX', then any dependency on `rx.h' or `regex.h' should be removed, because the correct one cannot be known until the user configures the package.
As it turns out, Automake is actually smart enough to handle the particular case of the regular expression header. It will also automatically omit `libintl.h' if `AM_GNU_GETTEXT' is used.
Automatic dependency tracking can be suppressed by putting
no-dependencies in the variable AUTOMAKE_OPTIONS.
If you unpack a distribution made by make dist, and you want to
turn on the dependency-tracking code again, simply re-run
automake.
The actual dependency files are put under the build directory, in a subdirectory named `.deps'. These dependencies are machine specific. It is safe to delete them if you like; they will be automatically recreated during the next build.
Go to the first, previous, next, last section, table of contents.