8. Building Programs and Libraries

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

8.1 Building a program

In order to build a program, you need to tell Automake which sources are part of it, and which libraries it should be linked with.

This section also covers conditional compilation of sources or programs. Most of the comments about these also apply to libraries (see section Building a library) and libtool libraries (see section Building a Shared Library).

8.1.1 Defining program sources

In a directory containing source that gets built into a program (as opposed to a library or a script), the PROGRAMS primary is used. Programs can be installed in bindir, sbindir, libexecdir, pkglibdir, pkglibexecdir, or not at all (noinst_). They can also be built only for `make check', in which case the prefix is `check_'.

For instance:

bin_PROGRAMS = hello

In this simple case, the resulting `Makefile.in' will contain code to generate a program named hello.

Associated with each program are several assisting variables that 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.

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 hello_SOURCES is not specified, then it defaults to the single file `hello.c' (see section Default _SOURCES).

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 Yacc and Lex support.

8.1.2 Linking the program

If you need to link against libraries that are not found by configure, you can use LDADD to do so. This variable is used to specify additional objects or libraries to link with; it is inappropriate for specifying specific linker flags, you should use AM_LDFLAGS for this purpose.

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 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', `-L', `-dlopen' and `-dlpreopen'). So, use the prog_LDFLAGS variable for this purpose.

It is also occasionally useful to have a program depend on some other target that 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.

Since these dependencies are associated to the link rule used to create the programs they should normally list files used by the link command. That is `*.$(OBJEXT)', `*.a', or `*.la' files. In rare cases you may need to add other kinds of files such as linker scripts, but listing a source file in _DEPENDENCIES is wrong. If some source file needs to be built before all the components of a program are built, consider using the BUILT_SOURCES variable instead (see section Built Sources).

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.

Conditional compilation of sources shows a situation where _DEPENDENCIES may be used.

We recommend that you avoid using `-l' options in LDADD or prog_LDADD when referring to libraries built by your package. Instead, write the file name of the library explicitly as in the above cpio example. Use `-l' only to list third-party libraries. If you follow this rule, the default value of prog_DEPENDENCIES will list all your local libraries and omit the other ones.

8.1.3 Conditional compilation of sources

You can't put a configure substitution (e.g., `@FOO@' or `$(FOO)' where FOO is defined via AC_SUBST) 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.

Fortunately there are two other ways to achieve the same result. One is to use configure substitutions in _LDADD variables, the other is to use an Automake conditional.

Conditional Compilation using _LDADD Substitutions

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 that are only conditionally built should be listed in the appropriate EXTRA_ variable. For instance, if `hello-linux.c' or `hello-generic.c' were conditionally included in hello, the `Makefile.am' would contain:

bin_PROGRAMS = hello
hello_SOURCES = hello-common.c
EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
hello_LDADD = $(HELLO_SYSTEM)
hello_DEPENDENCIES = $(HELLO_SYSTEM)

You can then setup the `$(HELLO_SYSTEM)' substitution from `configure.ac':

…
case $host in
  *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
  *)       HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
esac
AC_SUBST([HELLO_SYSTEM])
…

In this case, the variable HELLO_SYSTEM should be replaced by either `hello-linux.o' or `hello-generic.o', and added to both hello_DEPENDENCIES and hello_LDADD in order to be built and linked in.

Conditional Compilation using Automake Conditionals

An often simpler way to compile source files conditionally is to use Automake conditionals. For instance, you could use this `Makefile.am' construct to build the same `hello' example:

bin_PROGRAMS = hello
if LINUX
hello_SOURCES = hello-linux.c hello-common.c
else
hello_SOURCES = hello-generic.c hello-common.c
endif

In this case, `configure.ac' should setup the LINUX conditional using AM_CONDITIONAL (see section Conditionals).

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.

If your program uses a lot of files, you will probably prefer a conditional `+='.

bin_PROGRAMS = hello
hello_SOURCES = hello-common.c
if LINUX
hello_SOURCES += hello-linux.c
else
hello_SOURCES += hello-generic.c
endif

8.1.4 Conditional compilation of programs

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. The means to achieve conditional compilation of programs are the same you can use to compile source files conditionally: substitutions or conditionals.

Conditional Programs using configure Substitutions

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.

bin_PROGRAMS = cpio pax $(MT)
libexec_PROGRAMS = $(RMT)
EXTRA_PROGRAMS = mt rmt

As explained in Support for executable extensions, Automake will rewrite bin_PROGRAMS, libexec_PROGRAMS, and EXTRA_PROGRAMS, appending `$(EXEEXT)' to each binary. Obviously it cannot rewrite values obtained at run-time through configure substitutions, therefore you should take care of appending `$(EXEEXT)' yourself, as in `AC_SUBST([MT], ['mt${EXEEXT}'])'.

Conditional Programs using Automake Conditionals

You can also use Automake conditionals (see section Conditionals) to select programs to be built. In this case you don't have to worry about `$(EXEEXT)' or EXTRA_PROGRAMS.

bin_PROGRAMS = cpio pax
if WANT_MT
  bin_PROGRAMS += mt
endif
if WANT_RMT
  libexec_PROGRAMS = rmt
endif

8.2 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
libcpio_a_SOURCES = …

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 `libcpio.a' is `libcpio_a_SOURCES', not `libcpio.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)

In addition, sources for extra objects that will not exist until configure-time must be added to the BUILT_SOURCES variable (see section Built Sources).

Building a static library is done by compiling all object files, then by invoking `$(AR) $(ARFLAGS)' followed by the name of the library and the list of objects, and finally by calling `$(RANLIB)' on that library. You should call AC_PROG_RANLIB from your `configure.ac' to define RANLIB (Automake will complain otherwise). AR and ARFLAGS default to ar and cru respectively; you can override these two variables my setting them in your `Makefile.am', by AC_SUBSTing them from your `configure.ac', or by defining a per-library maude_AR variable (see section Program and Library Variables).

Be careful when selecting library components conditionally. Because building an empty library is not portable, you should ensure that any library always contains at least one object.

To use a static library when building a program, add it to LDADD for this program. In the following example, the program `cpio' is statically linked with the library `libcpio.a'.

noinst_LIBRARIES = libcpio.a
libcpio_a_SOURCES = …

bin_PROGRAMS = cpio
cpio_SOURCES = cpio.c …
cpio_LDADD = libcpio.a

8.3 Building a Shared Library

Building shared libraries portably is a relatively complex matter. For this reason, GNU Libtool (see (libtool)Top section `Introduction' in The Libtool Manual) was created to help build shared libraries in a platform-independent way.

8.3.1 The Libtool Concept

Libtool abstracts shared and static libraries into a unified concept henceforth called libtool libraries. Libtool libraries are files using the `.la' suffix, and can designate a static library, a shared library, or maybe both. Their exact nature cannot be determined until `./configure' is run: not all platforms support all kinds of libraries, and users can explicitly select which libraries should be built. (However the package's maintainers can tune the default, see (libtool)AC_PROG_LIBTOOL section `The AC_PROG_LIBTOOL macro' in The Libtool Manual.)

Because object files for shared and static libraries must be compiled differently, libtool is also used during compilation. Object files built by libtool are called libtool objects: these are files using the `.lo' suffix. Libtool libraries are built from these libtool objects.

You should not assume anything about the structure of `.la' or `.lo' files and how libtool constructs them: this is libtool's concern, and the last thing one wants is to learn about libtool's guts. However the existence of these files matters, because they are used as targets and dependencies in `Makefile's rules when building libtool libraries. There are situations where you may have to refer to these, for instance when expressing dependencies for building source files conditionally (see section Libtool Libraries with Conditional Sources).

People considering writing a plug-in system, with dynamically loaded modules, should look into `libltdl': libtool's dlopening library (see (libtool)Using libltdl section `Using libltdl' in The Libtool Manual). This offers a portable dlopening facility to load libtool libraries dynamically, and can also achieve static linking where unavoidable.

Before we discuss how to use libtool with Automake in details, it should be noted that the libtool manual also has a section about how to use Automake with libtool (see (libtool)Using Automake section `Using Automake with Libtool' in The Libtool Manual).

8.3.2 Building Libtool Libraries

Automake uses libtool to build libraries declared with the LTLIBRARIES primary. Each _LTLIBRARIES variable is a list of libtool libraries to build. For instance, to create a libtool library named `libgettext.la', and install it in libdir, write:

lib_LTLIBRARIES = libgettext.la
libgettext_la_SOURCES = gettext.c gettext.h …

Automake predefines the variable pkglibdir, so you can use pkglib_LTLIBRARIES to install libraries in `$(libdir)/@PACKAGE@/'.

If `gettext.h' is a public header file that needs to be installed in order for people to use the library, it should be declared using a _HEADERS variable, not in libgettext_la_SOURCES. Headers listed in the latter should be internal headers that are not part of the public interface.

lib_LTLIBRARIES = libgettext.la
libgettext_la_SOURCES = gettext.c …
include_HEADERS = gettext.h …

A package can build and install such a library along with other programs that use it. This dependency should be specified using LDADD. The following example builds a program named `hello' that is linked with `libgettext.la'.

lib_LTLIBRARIES = libgettext.la
libgettext_la_SOURCES = gettext.c …

bin_PROGRAMS = hello
hello_SOURCES = hello.c …
hello_LDADD = libgettext.la

Whether `hello' is statically or dynamically linked with `libgettext.la' is not yet known: this will depend on the configuration of libtool and the capabilities of the host.

8.3.3 Building Libtool Libraries Conditionally

Like conditional programs (see section Conditional compilation of programs), there are two main ways to build conditional libraries: using Automake conditionals or using Autoconf AC_SUBSTitutions.

The important implementation detail you have to be aware of is that the place where a library will be installed matters to libtool: it needs to be indicated at link-time using the `-rpath' option.

For libraries whose destination directory is known when Automake runs, Automake will automatically supply the appropriate `-rpath' option to libtool. This is the case for libraries listed explicitly in some installable _LTLIBRARIES variables such as lib_LTLIBRARIES.

However, for libraries determined at configure time (and thus mentioned in EXTRA_LTLIBRARIES), Automake does not know the final installation directory. For such libraries you must add the `-rpath' option to the appropriate _LDFLAGS variable by hand.

The examples below illustrate the differences between these two methods.

Here is an example where WANTEDLIBS is an AC_SUBSTed variable set at `./configure'-time to either `libfoo.la', `libbar.la', both, or none. Although `$(WANTEDLIBS)' appears in the lib_LTLIBRARIES, Automake cannot guess it relates to `libfoo.la' or `libbar.la' at the time it creates the link rule for these two libraries. Therefore the `-rpath' argument must be explicitly supplied.

EXTRA_LTLIBRARIES = libfoo.la libbar.la
lib_LTLIBRARIES = $(WANTEDLIBS)
libfoo_la_SOURCES = foo.c …
libfoo_la_LDFLAGS = -rpath '$(libdir)'
libbar_la_SOURCES = bar.c …
libbar_la_LDFLAGS = -rpath '$(libdir)'

Here is how the same `Makefile.am' would look using Automake conditionals named WANT_LIBFOO and WANT_LIBBAR. Now Automake is able to compute the `-rpath' setting itself, because it's clear that both libraries will end up in `$(libdir)' if they are installed.

lib_LTLIBRARIES =
if WANT_LIBFOO
lib_LTLIBRARIES += libfoo.la
endif
if WANT_LIBBAR
lib_LTLIBRARIES += libbar.la
endif
libfoo_la_SOURCES = foo.c …
libbar_la_SOURCES = bar.c …

8.3.4 Libtool Libraries with Conditional Sources

Conditional compilation of sources in a library can be achieved in the same way as conditional compilation of sources in a program (see section Conditional compilation of sources). The only difference is that _LIBADD should be used instead of _LDADD and that it should mention libtool objects (`.lo' files).

So, to mimic the `hello' example from Conditional compilation of sources, we could build a `libhello.la' library using either `hello-linux.c' or `hello-generic.c' with the following `Makefile.am'.

lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello-common.c
EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
libhello_la_LIBADD = $(HELLO_SYSTEM)
libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)

And make sure configure defines HELLO_SYSTEM as either `hello-linux.lo' or `hello-generic.lo'.

Or we could simply use an Automake conditional as follows.

lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello-common.c
if LINUX
libhello_la_SOURCES += hello-linux.c
else
libhello_la_SOURCES += hello-generic.c
endif

8.3.5 Libtool Convenience Libraries

Sometimes you want to build libtool libraries that should not be installed. These are called libtool convenience libraries and are typically used to encapsulate many sublibraries, later gathered into one big installed library.

Libtool convenience libraries are declared by directory-less variables such as noinst_LTLIBRARIES, check_LTLIBRARIES, or even EXTRA_LTLIBRARIES. Unlike installed libtool libraries they do not need an `-rpath' flag at link time (actually this is the only difference).

Convenience libraries listed in noinst_LTLIBRARIES are always built. Those listed in check_LTLIBRARIES are built only upon `make check'. Finally, libraries listed in EXTRA_LTLIBRARIES are never built explicitly: Automake outputs rules to build them, but if the library does not appear as a Makefile dependency anywhere it won't be built (this is why EXTRA_LTLIBRARIES is used for conditional compilation).

Here is a sample setup merging libtool convenience libraries from subdirectories into one main `libtop.la' library.

# -- Top-level Makefile.am --
SUBDIRS = sub1 sub2 …
lib_LTLIBRARIES = libtop.la
libtop_la_SOURCES =
libtop_la_LIBADD = \
  sub1/libsub1.la \
  sub2/libsub2.la \
  …

# -- sub1/Makefile.am --
noinst_LTLIBRARIES = libsub1.la
libsub1_la_SOURCES = …

# -- sub2/Makefile.am --
# showing nested convenience libraries
SUBDIRS = sub2.1 sub2.2 …
noinst_LTLIBRARIES = libsub2.la
libsub2_la_SOURCES =
libsub2_la_LIBADD = \
  sub21/libsub21.la \
  sub22/libsub22.la \
  …

When using such setup, beware that automake will assume `libtop.la' is to be linked with the C linker. This is because libtop_la_SOURCES is empty, so automake picks C as default language. If libtop_la_SOURCES was not empty, automake would select the linker as explained in How the Linker is Chosen.

If one of the sublibraries contains non-C source, it is important that the appropriate linker be chosen. One way to achieve this is to pretend that there is such a non-C file among the sources of the library, thus forcing automake to select the appropriate linker. Here is the top-level `Makefile' of our example updated to force C++ linking.

SUBDIRS = sub1 sub2 …
lib_LTLIBRARIES = libtop.la
libtop_la_SOURCES =
# Dummy C++ source to cause C++ linking.
nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
libtop_la_LIBADD = \
  sub1/libsub1.la \
  sub2/libsub2.la \
  …

`EXTRA_*_SOURCES' variables are used to keep track of source files that might be compiled (this is mostly useful when doing conditional compilation using AC_SUBST, see section Libtool Libraries with Conditional Sources), and the nodist_ prefix means the listed sources are not to be distributed (see section Program and Library Variables). In effect the file `dummy.cxx' does not need to exist in the source tree. Of course if you have some real source file to list in libtop_la_SOURCES there is no point in cheating with nodist_EXTRA_libtop_la_SOURCES.

8.3.6 Libtool Modules

These are libtool libraries meant to be dlopened. They are indicated to libtool by passing `-module' at link-time.

pkglib_LTLIBRARIES = mymodule.la
mymodule_la_SOURCES = doit.c
mymodule_la_LDFLAGS = -module

Ordinarily, Automake requires that a library's name start with lib. However, when building a dynamically loadable module you might wish to use a "nonstandard" name. Automake will not complain about such nonstandard names if it knows the library being built is a libtool module, i.e., if `-module' explicitly appears in the library's _LDFLAGS variable (or in the common AM_LDFLAGS variable when no per-library _LDFLAGS variable is defined).

As always, AC_SUBST variables are black boxes to Automake since their values are not yet known when automake is run. Therefore if `-module' is set via such a variable, Automake cannot notice it and will proceed as if the library was an ordinary libtool library, with strict naming.

If mymodule_la_SOURCES is not specified, then it defaults to the single file `mymodule.c' (see section Default _SOURCES).

8.3.7 _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS

As shown in previous sections, the `library_LIBADD' variable should be used to list extra libtool objects (`.lo' files) or libtool libraries (`.la') to add to library.

The `library_LDFLAGS' variable is the place to list additional libtool linking flags, such as `-version-info', `-static', and a lot more. See (libtool)Link mode section `Link mode' in The Libtool Manual.

The libtool command has two kinds of options: mode-specific options and generic options. Mode-specific options such as the aforementioned linking flags should be lumped with the other flags passed to the tool invoked by libtool (hence the use of `library_LDFLAGS' for libtool linking flags). Generic options include `--tag=TAG' and `--silent' (see (libtool)Invoking libtool section `Invoking libtool' in The Libtool Manual for more options) should appear before the mode selection on the command line; in `Makefile.am's they should be listed in the `library_LIBTOOLFLAGS' variable.

If `library_LIBTOOLFLAGS' is not defined, then the variable AM_LIBTOOLFLAGS is used instead.

These flags are passed to libtool after the `--tag=TAG' option computed by Automake (if any), so `library_LIBTOOLFLAGS' (or AM_LIBTOOLFLAGS) is a good place to override or supplement the `--tag=TAG' setting.

The libtool rules also use a LIBTOOLFLAGS variable that should not be set in `Makefile.am': this is a user variable (see section Flag Variables Ordering. It allows users to run `make LIBTOOLFLAGS=--silent', for instance. Note that the verbosity of libtool can also be influenced with the Automake `silent-rules' option (see section Changing Automake's Behavior).

8.3.8 LTLIBOBJS and LTALLOCA

Where an ordinary library might include `$(LIBOBJS)' or `$(ALLOCA)' (see section Special handling for LIBOBJS and ALLOCA), a libtool library must use `$(LTLIBOBJS)' or `$(LTALLOCA)'. This is required because the object files that libtool operates on do not necessarily end in `.o'.

Nowadays, the computation of LTLIBOBJS from LIBOBJS is performed automatically by Autoconf (see (autoconf)AC_LIBOBJ vs LIBOBJS section `AC_LIBOBJ vs. LIBOBJS' in The Autoconf Manual).

8.3.9 Common Issues Related to Libtool's Use

8.3.9.1 Error: `required file `./ltmain.sh' not found'

Libtool comes with a tool called libtoolize that will install libtool's supporting files into a package. Running this command will install `ltmain.sh'. You should execute it before aclocal and automake.

People upgrading old packages to newer autotools are likely to face this issue because older Automake versions used to call libtoolize. Therefore old build scripts do not call libtoolize.

Since Automake 1.6, it has been decided that running libtoolize was none of Automake's business. Instead, that functionality has been moved into the autoreconf command (see (autoconf)autoreconf Invocation section `Using autoreconf' in The Autoconf Manual). If you do not want to remember what to run and when, just learn the autoreconf command. Hopefully, replacing existing `bootstrap.sh' or `autogen.sh' scripts by a call to autoreconf should also free you from any similar incompatible change in the future.

8.3.9.2 Objects `created with both libtool and without'

Sometimes, the same source file is used both to build a libtool library and to build another non-libtool target (be it a program or another library).

Let's consider the following `Makefile.am'.

bin_PROGRAMS = prog
prog_SOURCES = prog.c foo.c …

lib_LTLIBRARIES = libfoo.la
libfoo_la_SOURCES = foo.c …

(In this trivial case the issue could be avoided by linking `libfoo.la' with `prog' instead of listing `foo.c' in prog_SOURCES. But let's assume we really want to keep `prog' and `libfoo.la' separate.)

Technically, it means that we should build `foo.$(OBJEXT)' for `prog', and `foo.lo' for `libfoo.la'. The problem is that in the course of creating `foo.lo', libtool may erase (or replace) `foo.$(OBJEXT)', and this cannot be avoided.

Therefore, when Automake detects this situation it will complain with a message such as

object `foo.$(OBJEXT)' created both with libtool and without

A workaround for this issue is to ensure that these two objects get different basenames. As explained in Why are object files sometimes renamed?, this happens automatically when per-targets flags are used.

bin_PROGRAMS = prog
prog_SOURCES = prog.c foo.c …
prog_CFLAGS = $(AM_CFLAGS)

lib_LTLIBRARIES = libfoo.la
libfoo_la_SOURCES = foo.c …

Adding `prog_CFLAGS = $(AM_CFLAGS)' is almost a no-op, because when the prog_CFLAGS is defined, it is used instead of AM_CFLAGS. However as a side effect it will cause `prog.c' and `foo.c' to be compiled as `prog-prog.$(OBJEXT)' and `prog-foo.$(OBJEXT)', which solves the issue.

8.4 Program and Library Variables

Associated with each program is a collection of variables that 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.

maude_SOURCES

This variable, if it exists, lists all the source files that are compiled to build the program. These files are added to the distribution by default. When building the program, Automake will cause each source file to be compiled to a single `.o' file (or `.lo' when using libtool). Normally these object files are named after the source file, but other factors can change this. If a file in the _SOURCES variable has an unrecognized extension, Automake will do one of two things with it. If a suffix rule exists for turning files with the unrecognized extension into `.o' files, then automake will treat this file as it will any other source file (see section Support for Other Languages). Otherwise, the file will be ignored as though it were a header file.

The prefixes dist_ and nodist_ can be used to control whether files listed in a _SOURCES variable are distributed. dist_ is redundant, as sources are distributed by default, but it can be specified for clarity if desired.

It is possible to have both dist_ and nodist_ variants of a given _SOURCES variable at once; this lets you easily distribute some files and not others, for instance:

nodist_maude_SOURCES = nodist.c dist_maude_SOURCES = dist-me.c

By default the output file (on Unix systems, the `.o' file) will be put into the current build directory. However, if the option `subdir-objects' is 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-objects' enabled, `sub/dir/file.c' will be compiled to `sub/dir/file.o'. Some people prefer this mode of operation. You can specify `subdir-objects' in AUTOMAKE_OPTIONS (see section Changing Automake's Behavior).

EXTRA_maude_SOURCES

Automake needs to know the list of files you intend to compile statically. For one thing, this is the only way Automake has of knowing what sort of language support a given `Makefile.in' requires. (4) This means that, for example, you can't put a configure substitution like `@my_sources@' into a `_SOURCES' variable. If you intend to conditionally compile source files and use `configure' to substitute the appropriate object names into, e.g., _LDADD (see below), then you should list the corresponding source files in the EXTRA_ variable.

This variable also supports dist_ and nodist_ prefixes. For instance, nodist_EXTRA_maude_SOURCES would list extra sources that may need to be built, but should not be distributed.

maude_AR

A static library is created by default by invoking `$(AR) $(ARFLAGS)' followed 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 that should go into a library. For instance, the SGI C++ compiler likes this variable set like so:

libmaude_a_AR = $(CXX) -ar -o

maude_LIBADD

Extra objects can be added to a library using the _LIBADD variable. For instance, this should be used for objects determined by configure (see section Building a library).

In the case of libtool libraries, maude_LIBADD can also refer to other libtool libraries.

maude_LDADD

Extra objects (`*.$(OBJEXT)') and libraries (`*.a', `*.la') can be added to a program by listing them in the _LDADD variable. For instance, this should be used for objects determined by configure (see section Linking the program).

_LDADD and _LIBADD are 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.ac' 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)

We recommend that you use `-l' and `-L' only when referring to third-party libraries, and give the explicit file names of any library built by your package. Doing so will ensure that maude_DEPENDENCIES (see below) is correctly defined by default.

maude_LDFLAGS

This variable is used to pass extra flags to the link step of a program or a shared library. It overrides the AM_LDFLAGS variable.

maude_LIBTOOLFLAGS

This variable is used to pass extra options to libtool. It overrides the AM_LIBTOOLFLAGS variable. These options are output before libtool's `--mode=MODE' option, so they should not be mode-specific options (those belong to the compiler or linker flags). See section _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS.

maude_DEPENDENCIES

It is also occasionally useful to have a target (program or library) depend on some other file that is not actually part of that target. This can be done using the _DEPENDENCIES variable. Each target depends on the contents of such a variable, but no further interpretation is done.

Since these dependencies are associated to the link rule used to create the programs they should normally list files used by the link command. That is `*.$(OBJEXT)', `*.a', or `*.la' files for programs; `*.lo' and `*.la' files for Libtool libraries; and `*.$(OBJEXT)' files for static libraries. In rare cases you may need to add other kinds of files such as linker scripts, but listing a source file in _DEPENDENCIES is wrong. If some source file needs to be built before all the components of a program are built, consider using the BUILT_SOURCES variable (see section Built Sources).

If _DEPENDENCIES is not supplied, it is computed by Automake. The automatically-assigned value is the contents of _LDADD or _LIBADD, 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 _DEPENDENCIES to be generated.

_DEPENDENCIES is more likely used to perform conditional compilation using an AC_SUBST variable that contains a list of objects. See section Conditional compilation of sources, and Libtool Libraries with Conditional Sources.

maude_LINK

You can override the linker on a per-program basis. By default the linker is chosen according to the languages used by the program. For instance, a program that includes C++ source code would use the C++ compiler to link. The _LINK variable must hold the name of a command that can be passed all the `.o' file names as arguments. Note that the name of the underlying program is not passed to _LINK; typically one uses `$@':

maude_LINK = $(CCLD) -magic -o $@

maude_CCASFLAGS

maude_CFLAGS

maude_CPPFLAGS

maude_CXXFLAGS

maude_FFLAGS

maude_GCJFLAGS

maude_LFLAGS

maude_OBJCFLAGS

maude_RFLAGS

maude_UPCFLAGS

maude_YFLAGS

Automake allows you to set compilation flags on a per-program (or per-library) basis. A single source file can be included in several programs, and it will potentially be compiled with different flags for each program. This works for any language directly supported by Automake. These per-target compilation flags are `_CCASFLAGS', `_CFLAGS', `_CPPFLAGS', `_CXXFLAGS', `_FFLAGS', `_GCJFLAGS', `_LFLAGS', `_OBJCFLAGS', `_RFLAGS', `_UPCFLAGS', and `_YFLAGS'.

When using a per-target compilation flag, Automake will choose a different name for the intermediate object files. Ordinarily a file like `sample.c' will be compiled to produce `sample.o'. However, if the program's _CFLAGS variable is set, then the object file will be named, for instance, `maude-sample.o'. (See also Why are object files sometimes renamed?.) The use of per-target compilation flags with C sources requires that the macro AM_PROG_CC_C_O be called from `configure.ac'.

In compilations with per-target flags, the ordinary `AM_' form of the flags variable is not automatically included in the compilation (however, the user form of the variable is included). So for instance, if you want the hypothetical `maude' compilations to also use the value of AM_CFLAGS, you would need to write:

maude_CFLAGS = … your flags … $(AM_CFLAGS)

See section Flag Variables Ordering, for more discussion about the interaction between user variables, `AM_' shadow variables, and per-target variables.

maude_SHORTNAME

On some platforms the allowable file names are very short. In order to support these systems and per-target compilation flags at the same time, Automake allows you to set a "short name" that will influence how intermediate object files are named. For instance, in the following example,

bin_PROGRAMS = maude maude_CPPFLAGS = -DSOMEFLAG maude_SHORTNAME = m maude_SOURCES = sample.c …

the object file would be named `m-sample.o' rather than `maude-sample.o'.

This facility is rarely needed in practice, and we recommend avoiding it until you find it is required.

8.5 Default _SOURCES

_SOURCES variables are used to specify source files of programs (see section Building a program), libraries (see section Building a library), and Libtool libraries (see section Building a Shared Library).

When no such variable is specified for a target, Automake will define one itself. The default is to compile a single C file whose base name is the name of the target itself, with any extension replaced by AM_DEFAULT_SOURCE_EXT, which defaults to `.c'.

For example if you have the following somewhere in your `Makefile.am' with no corresponding libfoo_a_SOURCES:

lib_LIBRARIES = libfoo.a sub/libc++.a

`libfoo.a' will be built using a default source file named `libfoo.c', and `sub/libc++.a' will be built from `sub/libc++.c'. (In older versions `sub/libc++.a' would be built from `sub_libc___a.c', i.e., the default source was the canonized name of the target, with `.c' appended. We believe the new behavior is more sensible, but for backward compatibility automake will use the old name if a file or a rule with that name exists and AM_DEFAULT_SOURCE_EXT is not used.)

Default sources are mainly useful in test suites, when building many test programs each from a single source. For instance, in

check_PROGRAMS = test1 test2 test3
AM_DEFAULT_SOURCE_EXT = .cpp

`test1', `test2', and `test3' will be built from `test1.cpp', `test2.cpp', and `test3.cpp'. Without the last line, they will be built from `test1.c', `test2.c', and `test3.c'.

Another case where this is convenient is building many Libtool modules (`moduleN.la'), each defined in its own file (`moduleN.c').

AM_LDFLAGS = -module
lib_LTLIBRARIES = module1.la module2.la module3.la

Finally, there is one situation where this default source computation needs to be avoided: when a target should not be built from sources. We already saw such an example in Building true and false; this happens when all the constituents of a target have already been compiled and just need to be combined using a _LDADD variable. Then it is necessary to define an empty _SOURCES variable, so that automake does not compute a default.

bin_PROGRAMS = target
target_SOURCES =
target_LDADD = libmain.a libmisc.a

8.6 Special handling for LIBOBJS and ALLOCA

The `$(LIBOBJS)' and `$(ALLOCA)' variables list object files that should be compiled into the project to provide an implementation for functions that are missing or broken on the host system. They are substituted by `configure'.

These variables are defined by Autoconf macros such as AC_LIBOBJ, AC_REPLACE_FUNCS (see (autoconf)Generic Functions section `Generic Function Checks' in The Autoconf Manual), or AC_FUNC_ALLOCA (see (autoconf)Particular Functions section `Particular Function Checks' in The Autoconf Manual). Many other Autoconf macros call AC_LIBOBJ or AC_REPLACE_FUNCS to populate `$(LIBOBJS)'.

Using these variables is very similar to doing conditional compilation using AC_SUBST variables, as described in Conditional compilation of sources. That is, when building a program, `$(LIBOBJS)' and `$(ALLOCA)' should be added to the associated `*_LDADD' variable, or to the `*_LIBADD' variable when building a library. However there is no need to list the corresponding sources in `EXTRA_*_SOURCES' nor to define `*_DEPENDENCIES'. Automake automatically adds `$(LIBOBJS)' and `$(ALLOCA)' to the dependencies, and it will discover the list of corresponding source files automatically (by tracing the invocations of the AC_LIBSOURCE Autoconf macros). However, if you have already defined `*_DEPENDENCIES' explicitly for an unrelated reason, then you have to add these variables manually.

These variables are usually used to build a portability library that is linked with all the programs of the project. We now review a sample setup. First, `configure.ac' contains some checks that affect either LIBOBJS or ALLOCA.

# configure.ac
…
AC_CONFIG_LIBOBJ_DIR([lib])
…
AC_FUNC_MALLOC             dnl May add malloc.$(OBJEXT) to LIBOBJS
AC_FUNC_MEMCMP             dnl May add memcmp.$(OBJEXT) to LIBOBJS
AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
AC_FUNC_ALLOCA             dnl May add alloca.$(OBJEXT) to ALLOCA
…
AC_CONFIG_FILES([
  lib/Makefile
  src/Makefile
])
AC_OUTPUT

The AC_CONFIG_LIBOBJ_DIR tells Autoconf that the source files of these object files are to be found in the `lib/' directory. Automake can also use this information, otherwise it expects the source files are to be in the directory where the `$(LIBOBJS)' and `$(ALLOCA)' variables are used.

The `lib/' directory should therefore contain `malloc.c', `memcmp.c', `strdup.c', `alloca.c'. Here is its `Makefile.am':

# lib/Makefile.am

noinst_LIBRARIES = libcompat.a
libcompat_a_SOURCES =
libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)

The library can have any name, of course, and anyway it is not going to be installed: it just holds the replacement versions of the missing or broken functions so we can later link them in. Many projects also include extra functions, specific to the project, in that library: they are simply added on the _SOURCES line.

There is a small trap here, though: `$(LIBOBJS)' and `$(ALLOCA)' might be empty, and building an empty library is not portable. You should ensure that there is always something to put in `libcompat.a'. Most projects will also add some utility functions in that directory, and list them in libcompat_a_SOURCES, so in practice `libcompat.a' cannot be empty.

Finally here is how this library could be used from the `src/' directory.

# src/Makefile.am

# Link all programs in this directory with libcompat.a
LDADD = ../lib/libcompat.a

bin_PROGRAMS = tool1 tool2 …
tool1_SOURCES = …
tool2_SOURCES = …

When option `subdir-objects' is not used, as in the above example, the variables `$(LIBOBJS)' or `$(ALLOCA)' can only be used in the directory where their sources lie. E.g., here it would be wrong to use `$(LIBOBJS)' or `$(ALLOCA)' in `src/Makefile.am'. However if both `subdir-objects' and AC_CONFIG_LIBOBJ_DIR are used, it is OK to use these variables in other directories. For instance `src/Makefile.am' could be changed as follows.

# src/Makefile.am

AUTOMAKE_OPTIONS = subdir-objects
LDADD = $(LIBOBJS) $(ALLOCA)

bin_PROGRAMS = tool1 tool2 …
tool1_SOURCES = …
tool2_SOURCES = …

Because `$(LIBOBJS)' and `$(ALLOCA)' contain object file names that end with `.$(OBJEXT)', they are not suitable for Libtool libraries (where the expected object extension is `.lo'): LTLIBOBJS and LTALLOCA should be used instead.

LTLIBOBJS is defined automatically by Autoconf and should not be defined by hand (as in the past), however at the time of writing LTALLOCA still needs to be defined from ALLOCA manually. See (autoconf)AC_LIBOBJ vs LIBOBJS section `AC_LIBOBJ vs. LIBOBJS' in The Autoconf Manual.

8.7 Variables used when building a program

Occasionally it is useful to know which `Makefile' variables Automake uses for compilations, and in which order (see section Flag Variables Ordering); 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 that Automake defines on its own:

AM_CPPFLAGS

The contents of this variable are passed to every compilation that invokes the C preprocessor; it is a list of arguments to the preprocessor. For instance, `-I' and `-D' options should be listed here.

Automake already provides some `-I' options automatically, in a separate variable that is also passed to every compilation that invokes the C preprocessor. In particular it generates `-I.', `-I$(srcdir)', and a `-I' pointing to the directory holding `config.h' (if you've used AC_CONFIG_HEADERS or AM_CONFIG_HEADER). You can disable the default `-I' options using the `nostdinc' option.

AM_CPPFLAGS is ignored in preference to a per-executable (or per-library) _CPPFLAGS variable if it is defined.

INCLUDES

This does the same job as AM_CPPFLAGS (or any per-target _CPPFLAGS variable if it is used). It is an older name for the same functionality. This variable is deprecated; we suggest using AM_CPPFLAGS and per-target _CPPFLAGS instead.

AM_CFLAGS

This is the variable the `Makefile.am' author can use to pass in additional C compiler flags. It is more fully documented elsewhere. In some situations, this is not used, in preference to the per-executable (or per-library) _CFLAGS.

COMPILE

This is the command used to actually compile a C source file. The file name is appended to form the complete command line.

AM_LDFLAGS

This is the variable the `Makefile.am' author can use to pass in additional linker flags. In some situations, this is not used, in preference to the per-executable (or per-library) _LDFLAGS.

LINK

This is the command used to actually link a C program. It already includes `-o $@' and the usual variable references (for instance, CFLAGS); it takes as "arguments" the names of the object files and libraries to link in.

8.8 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++'; `.yxx', `.cxx'; and `.ypp', `.cpp'.

Likewise, lex source files can be used to generate C or C++; the extensions `.l', `.ll', `.l++', `.lxx', and `.lpp' 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.ac' must define the variable YACC. This is most easily done by invoking the macro AC_PROG_YACC (see (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual).

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

AM_YFLAGS is usually used to pass the `-d' option to yacc. Automake knows what this means and will automatically adjust its rules to update and distribute the header file built by `yacc -d'. What Automake cannot guess, though, is where this header will be used: it is up to you to ensure the header gets built before it is first used. Typically this is necessary in order for dependency tracking to work when the header is included by another file. The common solution is listing the header file in BUILT_SOURCES (see section Built Sources) as follows.

BUILT_SOURCES = parser.h
AM_YFLAGS = -d
bin_PROGRAMS = foo
foo_SOURCES = … parser.y …

If a lex source file is seen, then your `configure.ac' must define the variable LEX. You can use AC_PROG_LEX to do this (see (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual), but using AM_PROG_LEX macro (see section Autoconf macros supplied with Automake) is recommended.

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

When AM_MAINTAINER_MODE (see section missing and AM_MAINTAINER_MODE) is used, the rebuild rule for distributed Yacc and Lex sources are only used when maintainer-mode is enabled, or when the files have been erased.

When lex or yacc sources are used, automake -i automatically installs an auxiliary program called ylwrap in your package (see section Programs automake might require). This program is used by the build rules to rename the output of these tools, and makes it possible to include multiple yacc (or lex) source files in a single directory. (This is necessary because yacc's output file name is fixed, and a parallel make could conceivably invoke more than one instance of yacc simultaneously.)

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.

8.9 C++ Support

Automake includes full support for C++.

Any package including C++ code must define the output variable CXX in `configure.ac'; the simplest way to do this is to use the AC_PROG_CXX macro (see (autoconf)Particular Programs 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.

AM_CXXFLAGS

The maintainer's variant of CXXFLAGS.

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.

8.10 Objective C Support

Automake includes some support for Objective C.

Any package including Objective C code must define the output variable OBJC in `configure.ac'; the simplest way to do this is to use the AC_PROG_OBJC macro (see (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual).

A few additional variables are defined when an Objective C source file is seen:

OBJC

The name of the Objective C compiler.

OBJCFLAGS

Any flags to pass to the Objective C compiler.

AM_OBJCFLAGS

The maintainer's variant of OBJCFLAGS.

OBJCCOMPILE

The command used to actually compile an Objective C source file. The file name is appended to form the complete command line.

OBJCLINK

The command used to actually link an Objective C program.

8.11 Unified Parallel C Support

Automake includes some support for Unified Parallel C.

Any package including Unified Parallel C code must define the output variable UPC in `configure.ac'; the simplest way to do this is to use the AM_PROG_UPC macro (see section Public Macros).

A few additional variables are defined when a Unified Parallel C source file is seen:

UPC

The name of the Unified Parallel C compiler.

UPCFLAGS

Any flags to pass to the Unified Parallel C compiler.

AM_UPCFLAGS

The maintainer's variant of UPCFLAGS.

UPCCOMPILE

The command used to actually compile a Unified Parallel C source file. The file name is appended to form the complete command line.

UPCLINK

The command used to actually link a Unified Parallel C program.

8.12 Assembly Support

Automake includes some support for assembly code. There are two forms of assembler files: normal (`*.s') and preprocessed by CPP (`*.S' or `*.sx').

The variable CCAS 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 values of CCASFLAGS and AM_CCASFLAGS (or its per-target definition) is passed to the compilation. For preprocessed files, DEFS, DEFAULT_INCLUDES, INCLUDES, CPPFLAGS and AM_CPPFLAGS are also used.

The autoconf macro AM_PROG_AS will define CCAS and CCASFLAGS for you (unless they are already set, it simply sets CCAS to the C compiler and CCASFLAGS to the C compiler flags), but you are free to define these variables by other means.

Only the suffixes `.s', `.S', and `.sx' are recognized by automake as being files containing assembly code.

8.13 Fortran 77 Support

Automake includes full support for Fortran 77.

Any package including Fortran 77 code must define the output variable F77 in `configure.ac'; the simplest way to do this is to use the AC_PROG_F77 macro (see (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual).

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.

AM_FFLAGS

The maintainer's variant of FFLAGS.

RFLAGS

Any flags to pass to the Ratfor compiler.

AM_RFLAGS

The maintainer's variant of RFLAGS.

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(5). 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.

8.13.1 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)

8.13.2 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)

8.13.3 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(6).

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 (autoconf)Fortran Compiler section `Fortran Compiler Characteristics' in The Autoconf Manual.

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.ac', and that either $(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)' 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.ac'. Also, if `$(FLIBS)' hadn't been mentioned in foo_LDADD and libfoo_la_LIBADD, then Automake would have issued a warning.

8.13.3.1 How the Linker is Chosen

When a program or library mixes several languages, Automake choose the linker according to the following priorities. (The names in parentheses are the variables containing the link command.)

1. Native Java (GCJLINK)
2. C++ (CXXLINK)
3. Fortran 77 (F77LINK)
4. Fortran (FCLINK)
5. Objective C (OBJCLINK)
6. Unified Parallel C (UPCLINK)
7. C (LINK)

For example, if Fortran 77, C and C++ source code is 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'.

Automake only looks at the file names listed in `_SOURCES' variables to choose the linker, and defaults to the C linker. Sometimes this is inconvenient because you are linking against a library written in another language and would like to set the linker more appropriately. See section Libtool Convenience Libraries, for a trick with nodist_EXTRA_…_SOURCES.

8.14 Fortran 9x Support

Automake includes support for Fortran 9x.

Any package including Fortran 9x code must define the output variable FC in `configure.ac'; the simplest way to do this is to use the AC_PROG_FC macro (see (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual).

A few additional variables are defined when a Fortran 9x source file is seen:

FC

The name of the Fortran 9x compiler.

FCFLAGS

Any flags to pass to the Fortran 9x compiler.

AM_FCFLAGS

The maintainer's variant of FCFLAGS.

FCCOMPILE

The command used to actually compile a Fortran 9x source file. The file name is appended to form the complete command line.

FCLINK

The command used to actually link a pure Fortran 9x program or shared library.

8.14.1 Compiling Fortran 9x Files

`N.o' is made automatically from `N.f90', `N.f95', `N.f03', or `N.f08' by running the Fortran 9x compiler. The precise command used is as follows:

`.f90'

$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<

`.f95'

$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<

`.f03'

$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<

`.f08'

$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<

8.15 Java Support

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.ac'; the variable GCJFLAGS must also be defined somehow (either in `configure.ac' or `Makefile.am'). The simplest way to do this is to use the AM_PROG_GCJ macro.

By default, programs including Java source files are linked with gcj.

As always, the contents of AM_GCJFLAGS are passed to every compilation invoking 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 options to gcj from `Makefile.am', this variable, and not the user variable GCJFLAGS, should be used.

gcj can be used to compile `.java', `.class', `.zip', or `.jar' files.

When linking, gcj requires that the main class be specified using the `--main=' option. The easiest way to do this is to use the _LDFLAGS variable for the program.

8.16 Vala Support

Automake provides initial support for Vala (http://www.vala-project.org/). This requires valac version 0.7.0 or later, and currently requires the user to use GNU make.

foo_SOURCES = foo.vala bar.vala zardoc.c

Any `.vala' file listed in a _SOURCES variable will be compiled into C code by the Vala compiler. The generated `.c' files are distributed. The end user does not need to have a Vala compiler installed.

Automake ships with an Autoconf macro called AM_PROG_VALAC that will locate the Vala compiler and optionally check its version number.

Macro: AM_PROG_VALAC ([MINIMUM-VERSION])

Try to find a Vala compiler in PATH. If it is found, the variable VALAC is set. Optionally a minimum release number of the compiler can be requested:

AM_PROG_VALAC([0.7.0])

There are a few variables that are used when compiling Vala sources:

VALAC

Path to the Vala compiler.

VALAFLAGS

Additional arguments for the Vala compiler.

AM_VALAFLAGS

The maintainer's variant of VALAFLAGS.

lib_LTLIBRARIES = libfoo.la libfoo_la_SOURCES = foo.vala

Note that currently, you cannot use per-target *_VALAFLAGS (see section Why are object files sometimes renamed?) to produce different C files from one Vala source file.

8.17 Support for Other Languages

Automake currently only includes full support for C, C++ (see section C++ Support), Objective C (see section Objective C Support), Fortran 77 (see section Fortran 77 Support), Fortran 9x (see section Fortran 9x 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).

8.18 Automatic de-ANSI-fication

The features described in this section are obsolete; you should not used any of them in new code, and they may be withdrawn in future Automake releases.

When the C language was standardized in 1989, there was a long transition period where package developers needed to worry about porting to older systems that did not support ANSI C by default. These older systems are no longer in practical use and are no longer supported by their original suppliers, so developers need not worry about this problem any more.

Automake allows you to write packages that are portable to K&R C 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 the obsolete de-ANSI-fication feature 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.ac' 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' subdirectories. 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.

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.

Using LIBOBJS with source de-ANSI-fication used to require hand-crafted code in `configure' to append `$U' to basenames in LIBOBJS. This is no longer true today. Starting with version 2.54, Autoconf takes care of rewriting LIBOBJS and LTLIBOBJS. (see (autoconf)AC_LIBOBJ vs LIBOBJS section `AC_LIBOBJ vs. LIBOBJS' in The Autoconf Manual)

8.19 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 (see section Automatic Dependency Tracking).

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. depcomp understands how to coax many different C and C++ compilers into generating dependency information in the format it requires. `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 your build.

Experience with earlier versions of Automake (see section Dependency Tracking in Automake) 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 passing `no-dependencies' as an argument to AM_INIT_AUTOMAKE (this should be the preferred way). Or, you can invoke 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 `--disable-dependency-tracking'.

8.20 Support for executable extensions

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 mostly doesn't yet mean fully. Until the English dictionary is revised, you will have to assist Automake if your package must support those platforms.

One thing you must be aware of is that, internally, Automake rewrites something like this:

bin_PROGRAMS = liver

to this:

bin_PROGRAMS = liver$(EXEEXT)

The targets Automake generates are likewise given the `$(EXEEXT)' extension.

The variables TESTS and XFAIL_TESTS (see section Simple Tests) are also rewritten if they contain filenames that have been declared as programs in the same `Makefile'. (This is mostly useful when some programs from check_PROGRAMS are listed in TESTS.)

However, Automake cannot apply this rewriting to configure substitutions. This means that if you are conditionally building a program using such a substitution, then your `configure.ac' must take care to add `$(EXEEXT)' when constructing the output variable.

With Autoconf 2.13 and earlier, you must explicitly use AC_EXEEXT to get this support. With Autoconf 2.50, AC_EXEEXT is run automatically if you configure a compiler (say, through AC_PROG_CC).

Sometimes maintainers like to write an explicit link rule for their program. Without executable extension support, this is easy--you simply write a rule whose target is the name of 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 `no-exeext' option (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 rule for a target named foo in `Makefile.am' will override an automake-generated rule for `foo$(EXEEXT)'. Without the `no-exeext' option, this use will give a diagnostic.

This document was generated on July, 20 2009 using texi2html 1.76.