7.1.2 Program and Library Variables

Here are variables that can be used to declare how a program or library is to be built. In the list below, we refer to the program or library as program. In your Makefile.am you would replace this with the canonicalized name of your program (see Other Automake variables). This list refers to programs, but in general the same rules apply for both static and dynamic libraries; the documentation below notes situations where programs and libraries differ.

program_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 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_foo_SOURCES = nodist.c
dist_foo_SOURCES = dist-me.c

The output file (on Unix systems, the .o file) will be put into the subdirectory named after the source file. For instance file.c will compiled to file.o, while sub/dir/file.c will be compiled to sub/dir/file.o.

EXTRA_program_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.) 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_program_SOURCES would list extra sources that may need to be built, but should not be distributed.

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

libfoo_a_AR = $(CXX) -ar -o

program_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 Libraries).

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

program_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 Linking).

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

foo_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 program_DEPENDENCIES (see below) is correctly defined by default.

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

program_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 Libtool Flags.

program_DEPENDENCIES

EXTRA_program_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 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 Conditional Sources and Conditional Libtool Sources.

The EXTRA_*_DEPENDENCIES variable may be useful for cases where you merely want to augment the automake-generated _DEPENDENCIES variable rather than replacing it.

program_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 and libraries to link against as arguments. Note that the name of the underlying program is not passed to _LINK; typically one uses ‘$@’:

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

If a _LINK variable is not supplied, it may still be generated and used by Automake due to the use of per-target link flags such as _CFLAGS, _LDFLAGS or _LIBTOOLFLAGS, in cases where they apply.

program_CCASFLAGS

program_CFLAGS

program_CPPFLAGS

program_CXXFLAGS

program_FFLAGS

program_GCJFLAGS

program_LFLAGS

program_OBJCFLAGS

program_OBJCXXFLAGS

program_RFLAGS

program_UPCFLAGS

program_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’, ‘_OBJCXXFLAGS’, ‘_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, foo-sample.o. (See also Renamed Objects).

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 foo compilations to also use the value of AM_CFLAGS, you would need to write:

foo_CFLAGS = … your flags … $(AM_CFLAGS)

See Flag Variables Ordering for more discussion about the interaction between all these variables.

program_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 change the naming of intermediate object files. For instance, in the following example,

bin_PROGRAMS = foo
foo_CPPFLAGS = -DSOMEFLAG
foo_SHORTNAME = f
foo_SOURCES = sample.c …

the object file would be named f-sample.o rather than foo-sample.o.

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

Why are object files sometimes renamed?

This happens when per-target compilation flags are used. Object files need to be renamed just in case they would clash with object files compiled from the same sources, but with different flags. Consider the following example.

bin_PROGRAMS = true false
true_SOURCES = generic.c
true_CPPFLAGS = -DEXIT_CODE=0
false_SOURCES = generic.c
false_CPPFLAGS = -DEXIT_CODE=1

Obviously the two programs are built from the same source, but it would be bad if they shared the same object, because generic.o cannot be built with both ‘-DEXIT_CODE=0’ and ‘-DEXIT_CODE=1’. Therefore automake outputs rules to build two different objects: true-generic.o and false-generic.o.

automake doesn’t actually look whether source files are shared to decide if it must rename objects. It will just rename all objects of a target as soon as it sees per-target compilation flags used.

It’s OK to share object files when per-target compilation flags are not used. For instance, true and false will both use version.o in the following example.

AM_CPPFLAGS = -DVERSION=1.0
bin_PROGRAMS = true false
true_SOURCES = true.c version.c
false_SOURCES = false.c version.c

Note that the renaming of objects is also affected by the _SHORTNAME variable (see Program and Library Variables).

Per-Object Flags Emulation

One of my source files needs to be compiled with different flags.  How
do I do?

Automake supports per-program and per-library compilation flags (see Program and Library Variables and Flag Variables Ordering). With this you can define compilation flags that apply to all files compiled for a target. For instance, in

bin_PROGRAMS = foo
foo_SOURCES = foo.c foo.h bar.c bar.h main.c
foo_CFLAGS = -some -flags

foo-foo.o, foo-bar.o, and foo-main.o will all be compiled with ‘-some -flags’. (If you wonder about the names of these object files, see Renamed Objects.) Note that foo_CFLAGS gives the flags to use when compiling all the C sources of the program foo, it has nothing to do with foo.c or foo-foo.o specifically.

What if foo.c needs to be compiled into foo.o using some specific flags, that none of the other files requires? Obviously per-program flags are not directly applicable here. Something like per-object flags are expected, i.e., flags that would be used only when creating foo-foo.o. Automake does not support that, however this is easy to simulate using a library that contains only that object, and compiling this library with per-library flags.

bin_PROGRAMS = foo
foo_SOURCES = bar.c bar.h main.c
foo_CFLAGS = -some -flags
foo_LDADD = libfoo.a
noinst_LIBRARIES = libfoo.a
libfoo_a_SOURCES = foo.c foo.h
libfoo_a_CFLAGS = -some -other -flags

Here foo-bar.o and foo-main.o will all be compiled with ‘-some -flags’, while libfoo_a-foo.o will be compiled using ‘-some -other -flags’. Eventually, all three objects will be linked to form foo.

This trick can also be achieved using Libtool convenience libraries, for instance ‘noinst_LTLIBRARIES = libfoo.la’ (see Libtool Convenience Libraries).

Another tempting idea to implement per-object flags is to override the compile rules automake would output for these files. Automake will not define a rule for a target you have defined, so you could think about defining the ‘foo-foo.o: foo.c’ rule yourself. We recommend against this, because this is error prone. For instance, if you add such a rule to the first example, it will break the day you decide to remove foo_CFLAGS (because foo.c will then be compiled as foo.o instead of foo-foo.o, see Renamed Objects). Also in order to support dependency tracking, the two .o/.obj extensions, and all the other flags variables involved in a compilation, you will end up modifying a copy of the rule previously output by automake for this file. If a new release of Automake generates a different rule, your copy will need to be updated by hand.