A large part of Automake's functionality is dedicated to making it easy to build C 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'. In the example above, the definition of
hello_SOURCES is actually redundant.
Multiple programs can be built in a single directory. Multiple programs can share a single source file. The source file 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 `The Libtool Manual' 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 `noinst_LTLIBRARIES' and `check_LTLIBRARIES' are not allowed.
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
automake
already provides some `-I' options automatically. In particular it
generates `-I$(srcdir)' and a `-I' pointing to the directory
holding `config.h' (if you've used 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'.
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. Automake's lex support also requires that you use the `AC_DECL_YYTEXT' macro--automake needs to know the value of `LEX_OUTPUT_ROOT'.
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. ylwrap is distributed with automake.
It should appear in the directory specified by `AC_CONFIG_AUX_DIR',
or the current directory if that macro is not used in
`configure.in'.
For yacc, simply managing locking is insufficient. yacc
output also 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
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++, and rudimentary support for other languages. Support for other languages will be improved based on demand.
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.
A few additional variables are defined when a C++ source file is seen:
CXX
CXXFLAGS
CXXCOMPILE
CXXLINK
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
(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.
De-ANSI-fication support 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.
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.
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.
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.