Go to the first, previous, next, last section, table of contents.


Building Programs and Libraries

A large part of Automake's functionality is dedicated to making it easy to build C programs and libraries.

Building a program

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 @[email protected]
libexec_PROGRAMS = @[email protected]
EXTRA_PROGRAMS = mt rmt

LDADD = ../lib/libcpio.a @[email protected]
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 `@[email protected]' and `@[email protected]'; these are left because it is known that they will not cause an invalid value for `prog_DEPENDENCIES' to be generated.

Building a library

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 = @[email protected] @[email protected]

Special handling for LIBOBJS and ALLOCA

Automake explicitly recognizes the use of @[email protected] and @[email protected], 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.

@[email protected] and @[email protected] are specially recognized in any `_LDADD' or `_LIBADD' variable.

Building a Shared Library

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 @[email protected], a libtool library must use @[email protected]. 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.

Variables used when building a program

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
A list of `-I' options. This can be set in your `Makefile.am' if you have special directories you want to look in. 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
This is the command used to actually compile a C source file. The filename is appended to form the complete command line.
LINK
This is the command used to actually link a C program.

Yacc and Lex support

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.

C++ and other languages

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
The name of the C++ compiler.
CXXFLAGS
Any flags to pass to the C++ compiler.
CXXCOMPILE
The command used to actually compile a C++ source file. The file name is appended to form the complete command line.
CXXLINK
The command used to actually link a C++ program.

Automatic de-ANSI-fication

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.

Automatic dependency tracking

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.