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 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'.

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 @[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 `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 @[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' (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.

C++ Support

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
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.

Fortran 77 Support

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
The name of the Fortran 77 compiler.
FFLAGS
Any flags to pass to the Fortran 77 compiler.
RFLAGS
Any flags to pass to the Ratfor compiler.
F77COMPILE
The command used to actually compile a Fortran 77 source file. The file name is appended to form the complete command line.
FLINK
The command used to actually link a pure Fortran 77 program or shared library.

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.

Preprocessing Fortran 77

`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:

`.F'
$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)
`.r'
$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)

Compiling Fortran 77 Files

`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:

`.f'
$(F77) -c $(AM_FFLAGS) $(FFLAGS)
`.F'
$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)
`.r'
$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)

Mixing Fortran 77 With C and C++

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:

  1. Automatic selection of the linker depending on which combinations of source code.
  2. Automatic selection of the appropriate linker flags (e.g. `-L' and `-l') to pass to the automatically selected linker in order to link in the appropriate Fortran 77 intrinsic and run-time libraries. These extra Fortran 77 linker flags are supplied in the output variable 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 @[email protected] 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 @[email protected] 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 @[email protected]

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 @[email protected] hadn't been mentioned in foo_LDADD and libfoo_la_LIBADD, then Automake would have issued a warning.

How the Linker is Chosen

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    |         |
                        |         |         |         |
                        +---------+---------+---------+

Fortran 77 and Autoconf

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.

Support for Other Languages

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.

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 (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/'`

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. 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.