automake

This file documents the GNU Automake package. Automake is a program which creates GNU standards-compliant Makefiles from template files. This edition documents version 1.6.1.

1. Introduction		Automake's purpose
2. General ideas
3. Some example packages
4. Creating a `Makefile.in'		Creating a Makefile.in
5. Scanning `configure.in'		Scanning configure.ac or configure.in
6. The top-level `Makefile.am'		The top-level Makefile.am
7. An Alternative Approach to Subdirectories		An alternative approach to subdirectories
8. Rebuilding Makefiles		Automatic rebuilding of Makefile
9. Building Programs and Libraries		Building programs and libraries
10. Other Derived Objects		Other derived objects
11. Other GNU Tools
12. Building documentation
13. What Gets Installed		What gets installed
14. What Gets Cleaned		What gets cleaned
15. What Goes in a Distribution		What goes in a distribution
16. Support for test suites
17. Changing Automake's Behavior		Changing Automake's behavior
18. Miscellaneous Rules		Miscellaneous rules
19. Include		Including extra files in an Automake template.
20. Conditionals
21. The effect of --gnu and --gnits
22. The effect of --cygnus
23. When Automake Isn't Enough		Extending Automake
24. Distributing `Makefile.in's		Distributing the Makefile.in
25. Automake API versioning		About compatibility between Automake versions
Macro and Variable Index
General Index

1. Introduction

Automake is a tool for automatically generating `Makefile.in's from files called `Makefile.am'. Each `Makefile.am' is basically a series of make macro definitions (with rules being thrown in occasionally). The generated `Makefile.in's are compliant with the GNU Makefile standards.

The GNU Makefile Standards Document (see section `Makefile Conventions' in The GNU Coding Standards) is long, complicated, and subject to change. The goal of Automake is to remove the burden of Makefile maintenance from the back of the individual GNU maintainer (and put it on the back of the Automake maintainer).

The typical Automake input file is simply a series of macro definitions. Each such file is processed to create a `Makefile.in'. There should generally be one `Makefile.am' per directory of a project.

Automake does constrain a project in certain ways; for instance it assumes that the project uses Autoconf (see section `Introduction' in The Autoconf Manual), and enforces certain restrictions on the `configure.in' contents(1).

Automake requires perl in order to generate the `Makefile.in's. However, the distributions created by Automake are fully GNU standards-compliant, and do not require perl in order to be built.

Mail suggestions and bug reports for Automake to bug-automake@gnu.org.

2. General ideas

The following sections cover a few basic ideas that will help you understand how Automake works.

2.1 General Operation		General operation of Automake
2.2 Strictness		Standards conformance checking
2.3 The Uniform Naming Scheme
2.4 How derived variables are named
2.5 Variables reserved for the user
2.6 Programs automake might require

2.1 General Operation

Automake works by reading a `Makefile.am' and generating a `Makefile.in'. Certain macros and targets defined in the `Makefile.am' instruct Automake to generate more specialized code; for instance, a `bin_PROGRAMS' macro definition will cause targets for compiling and linking programs to be generated.

The macro definitions and targets in the `Makefile.am' are copied verbatim into the generated file. This allows you to add arbitrary code into the generated `Makefile.in'. For instance the Automake distribution includes a non-standard cvs-dist target, which the Automake maintainer uses to make distributions from his source control system.

Note that most GNU make extensions are not recognized by Automake. Using such extensions in a `Makefile.am' will lead to errors or confusing behavior.

A special exception is that the GNU make append operator, `+=', is supported. This operator appends its right hand argument to the macro specified on the left. Automake will translate the operator into an ordinary `=' operator; `+=' will thus work with any make program.

Note that it is only valid to append to a macro in the same conditional context as the macro was originally defined. See Conditional Append, for more information.

Automake tries to group comments with adjoining targets and macro definitions in an intelligent way.

A target defined in `Makefile.am' generally overrides any such target of a similar name that would be automatically generated by automake. Although this is a supported feature, it is generally best to avoid making use of it, as sometimes the generated rules are very particular.

Similarly, a macro defined in `Makefile.am' or AC_SUBST'ed from `configure.in' will override any definition of the macro that automake would ordinarily create. This feature is more often useful than the ability to override a target definition. Be warned that many of the macros generated by automake are considered to be for internal use only, and their names might change in future releases.

When examining a macro definition, Automake will recursively examine macros referenced in the definition. For example, if Automake is looking at the content of foo_SOURCES in this snippet

xs = a.c b.c foo_SOURCES = c.c $(xs)

it would use the files `a.c', `b.c', and `c.c' as the contents of foo_SOURCES.

Automake also allows a form of comment which is not copied into the output; all lines beginning with `##' (leading spaces allowed) are completely ignored by Automake.

It is customary to make the first line of `Makefile.am' read:

## Process this file with automake to produce Makefile.in

2.2 Strictness

While Automake is intended to be used by maintainers of GNU packages, it does make some effort to accommodate those who wish to use it, but do not want to use all the GNU conventions.

To this end, Automake supports three levels of strictness---the strictness indicating how stringently Automake should check standards conformance.

The valid strictness levels are:

`foreign'

Automake will check for only those things which are absolutely required for proper operations. For instance, whereas GNU standards dictate the existence of a `NEWS' file, it will not be required in this mode. The name comes from the fact that Automake is intended to be used for GNU programs; these relaxed rules are not the standard mode of operation.

`gnu'

Automake will check--as much as possible--for compliance to the GNU standards for packages. This is the default.

`gnits'

Automake will check for compliance to the as-yet-unwritten Gnits standards. These are based on the GNU standards, but are even more detailed. Unless you are a Gnits standards contributor, it is recommended that you avoid this option until such time as the Gnits standard is actually published (which may never happen).

For more information on the precise implications of the strictness level, see 21. The effect of --gnu and --gnits.

Automake also has a special "cygnus" mode which is similar to strictness but handled differently. This mode is useful for packages which are put into a "Cygnus" style tree (e.g., the GCC tree). For more information on this mode, see 22. The effect of --cygnus.

2.3 The Uniform Naming Scheme

Automake macros (from here on referred to as variables) generally follow a uniform naming scheme that makes it easy to decide how programs (and other derived objects) are built, and how they are installed. This scheme also supports configure time determination of what should be built.

At make time, certain variables are used to determine which objects are to be built. The variable names are made of several pieces which are concatenated together.

The piece which tells automake what is being built is commonly called the primary. For instance, the primary PROGRAMS holds a list of programs which are to be compiled and linked.

A different set of names is used to decide where the built objects should be installed. These names are prefixes to the primary which indicate which standard directory should be used as the installation directory. The standard directory names are given in the GNU standards (see section `Directory Variables' in The GNU Coding Standards). Automake extends this list with pkglibdir, pkgincludedir, and pkgdatadir; these are the same as the non-`pkg' versions, but with `@PACKAGE@' appended. For instance, pkglibdir is defined as $(libdir)/@PACKAGE@.

For each primary, there is one additional variable named by prepending `EXTRA_' to the primary name. This variable is used to list objects which may or may not be built, depending on what configure decides. This variable is required because Automake must statically know the entire list of objects that may be built in order to generate a `Makefile.in' that will work in all cases.

For instance, cpio decides at configure time which programs are built. Some of the programs are installed in bindir, and some are installed in sbindir:

EXTRA_PROGRAMS = mt rmt bin_PROGRAMS = cpio pax sbin_PROGRAMS = @MORE_PROGRAMS@

Defining a primary without a prefix as a variable, e.g., PROGRAMS, is an error.

Note that the common `dir' suffix is left off when constructing the variable names; thus one writes `bin_PROGRAMS' and not `bindir_PROGRAMS'.

Not every sort of object can be installed in every directory. Automake will flag those attempts it finds in error. Automake will also diagnose obvious misspellings in directory names.

Sometimes the standard directories--even as augmented by Automake--- are not enough. In particular it is sometimes useful, for clarity, to install objects in a subdirectory of some predefined directory. To this end, Automake allows you to extend the list of possible installation directories. A given prefix (e.g. `zar') is valid if a variable of the same name with `dir' appended is defined (e.g. zardir).

For instance, until HTML support is part of Automake, you could use this to install raw HTML documentation:

htmldir = $(prefix)/html html_DATA = automake.html

The special prefix `noinst' indicates that the objects in question should be built but not installed at all. This is usually used for objects required to build the rest of your package, for instance static libraries (see section 9.2 Building a library), or helper scripts.

The special prefix `check' indicates that the objects in question should not be built until the make check command is run. Those objects are not installed either.

The current primary names are `PROGRAMS', `LIBRARIES', `LISP', `PYTHON', `JAVA', `SCRIPTS', `DATA', `HEADERS', `MANS', and `TEXINFOS'.

Some primaries also allow additional prefixes which control other aspects of automake's behavior. The currently defined prefixes are `dist_', `nodist_', and `nobase_'. These prefixes are explained later (see section 9.4 Program and Library Variables).

2.4 How derived variables are named

Sometimes a Makefile variable name is derived from some text the maintainer supplies. For instance, a program name listed in `_PROGRAMS' is rewritten into the name of a `_SOURCES' variable. In cases like this, Automake canonicalizes the text, so that program names and the like do not have to follow Makefile macro naming rules. All characters in the name except for letters, numbers, the strudel (@), and the underscore are turned into underscores when making macro references.

For example, if your program is named sniff-glue, the derived variable name would be sniff_glue_SOURCES, not sniff-glue_SOURCES. Similarly the sources for a library named libmumble++.a should be listed in the libmumble___a_SOURCES variable.

The strudel is an addition, to make the use of Autoconf substitutions in macro names less obfuscating.

2.5 Variables reserved for the user

Some Makefile variables are reserved by the GNU Coding Standards for the use of the "user" -- the person building the package. For instance, CFLAGS is one such variable.

Sometimes package developers are tempted to set user variables such as CFLAGS because it appears to make their job easier -- they don't have to introduce a second variable into every target.

However, the package itself should never set a user variable, particularly not to include switches which are required for proper compilation of the package. Since these variables are documented as being for the package builder, that person rightfully expects to be able to override any of these variables at build time.

To get around this problem, automake introduces an automake-specific shadow variable for each user flag variable. (Shadow variables are not introduced for variables like CC, where they would make no sense.) The shadow variable is named by prepending `AM_' to the user variable's name. For instance, the shadow variable for YFLAGS is AM_YFLAGS.

2.6 Programs automake might require

Automake sometimes requires helper programs so that the generated `Makefile' can do its work properly. There are a fairly large number of them, and we list them here.

ansi2knr.c

ansi2knr.1

These two files are used by the automatic de-ANSI-fication support (see section 9.13 Automatic de-ANSI-fication).

compile

This is a wrapper for compilers which don't accept both `-c' and `-o' at the same time. It is only used when absolutely required. Such compilers are rare.

config.guess

config.sub

These programs compute the canonical triplets for the given build, host, or target architecture. These programs are updated regulary to support new architectures and fix probes broken by changes in new kernel versions. You are encouraged to fetch the latest versions of these files from ftp://ftp.gnu.org/gnu/config/ before making a release.

depcomp

This program understands how to run a compiler so that it will generate not only the desired output but also dependency information which is then used by the automatic dependency tracking feature.

elisp-comp

This program is used to byte-compile Emacs Lisp code.

install-sh

This is a replacement for the install program which works on platforms where install is unavailable or unusable.

mdate-sh

This script is used to generate a `version.texi' file. It examines a file and prints some date information about it.

missing

This wraps a number of programs which are typically only required by maintainers. If the program in question doesn't exist, missing prints an informative warning and attempts to fix things so that the build can continue.

mkinstalldirs

This works around the fact that mkdir -p is not portable.

py-compile

This is used to byte-compile Python scripts.

texinfo.tex

Not a program, this file is required for make dvi to work when Texinfo sources are in the package.

ylwrap

This program wraps lex and yacc and ensures that, for instance, multiple yacc instances can be invoked in a single directory in parallel.

3. Some example packages

3.1 A simple example, start to finish
3.2 A classic program
3.3 Building etags and ctags

3.1 A simple example, start to finish

Let's suppose you just finished writing zardoz, a program to make your head float from vortex to vortex. You've been using Autoconf to provide a portability framework, but your `Makefile.in's have been ad-hoc. You want to make them bulletproof, so you turn to Automake.

The first step is to update your `configure.in' to include the commands that automake needs. The way to do this is to add an AM_INIT_AUTOMAKE call just after AC_INIT:

AC_INIT(zardoz, 1.0) AM_INIT_AUTOMAKE ...

Since your program doesn't have any complicating factors (e.g., it doesn't use gettext, it doesn't want to build a shared library), you're done with this part. That was easy!

Now you must regenerate `configure'. But to do that, you'll need to tell autoconf how to find the new macro you've used. The easiest way to do this is to use the aclocal program to generate your `aclocal.m4' for you. But wait... maybe you already have an `aclocal.m4', because you had to write some hairy macros for your program. The aclocal program lets you put your own macros into `acinclude.m4', so simply rename and then run:

mv aclocal.m4 acinclude.m4 aclocal autoconf

Now it is time to write your `Makefile.am' for zardoz. Since zardoz is a user program, you want to install it where the rest of the user programs go: bindir. Additionally, zardoz has some Texinfo documentation. Your `configure.in' script uses AC_REPLACE_FUNCS, so you need to link against `@LIBOBJS@'. So here's what you'd write:

bin_PROGRAMS = zardoz zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c zardoz_LDADD = @LIBOBJS@ info_TEXINFOS = zardoz.texi

Now you can run automake --add-missing to generate your `Makefile.in' and grab any auxiliary files you might need, and you're done!

3.2 A classic program

GNU hello is renowned for its classic simplicity and versatility. This section shows how Automake could be used with the GNU Hello package. The examples below are from the latest beta version of GNU Hello, but with all of the maintainer-only code stripped out, as well as all copyright comments.

Of course, GNU Hello is somewhat more featureful than your traditional two-liner. GNU Hello is internationalized, does option processing, and has a manual and a test suite.

Here is the `configure.in' from GNU Hello:

dnl Process this file with autoconf to produce a configure script. AC_INIT(src/hello.c) AM_INIT_AUTOMAKE(hello, 1.3.11) AM_CONFIG_HEADER(config.h) dnl Set of available languages. ALL_LINGUAS="de fr es ko nl no pl pt sl sv" dnl Checks for programs. AC_PROG_CC AC_ISC_POSIX dnl Checks for libraries. dnl Checks for header files. AC_STDC_HEADERS AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h) dnl Checks for library functions. AC_FUNC_ALLOCA dnl Check for st_blksize in struct stat AC_ST_BLKSIZE dnl internationalization macros AM_GNU_GETTEXT AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \ src/Makefile tests/Makefile tests/hello], [chmod +x tests/hello])

The `AM_' macros are provided by Automake (or the Gettext library); the rest are standard Autoconf macros.

The top-level `Makefile.am':

EXTRA_DIST = BUGS ChangeLog.O SUBDIRS = doc intl po src tests

As you can see, all the work here is really done in subdirectories.

The `po' and `intl' directories are automatically generated using gettextize; they will not be discussed here.

In `doc/Makefile.am' we see:

info_TEXINFOS = hello.texi hello_TEXINFOS = gpl.texi

This is sufficient to build, install, and distribute the GNU Hello manual.

Here is `tests/Makefile.am':

TESTS = hello EXTRA_DIST = hello.in testdata

The script `hello' is generated by configure, and is the only test case. make check will run this test.

Last we have `src/Makefile.am', where all the real work is done:

bin_PROGRAMS = hello hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h hello_LDADD = @INTLLIBS@ @ALLOCA@ localedir = $(datadir)/locale INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"

3.3 Building etags and ctags

Here is another, trickier example. It shows how to generate two programs (ctags and etags) from the same source file (`etags.c'). The difficult part is that each compilation of `etags.c' requires different cpp flags.

bin_PROGRAMS = etags ctags ctags_SOURCES = ctags_LDADD = ctags.o etags.o: etags.c $(COMPILE) -DETAGS_REGEXPS -c etags.c ctags.o: etags.c $(COMPILE) -DCTAGS -o ctags.o -c etags.c

Note that there is no etags_SOURCES definition. Automake will implicitly assume that there is a source file named `etags.c', and define rules to compile `etags.o' and link `etags'. The etags.o: etags.c rule supplied by the above `Makefile.am', will override the Automake generated rule to build `etags.o'.

ctags_SOURCES is defined to be empty--that way no implicit value is substituted. Because we have not listed the source of `ctags', we have to tell Automake how to link the program. This is the purpose of the ctags_LDADD line. A ctags_DEPENDENCIES variable, holding the dependencies of the `ctags' target will be automatically generated by Automake from the contant of ctags_LDADD.

The above rules won't work if your compiler doesn't accept both `-c' and `-o'. The simplest fix for this is to introduce a bogus dependency (to avoid problems with a parallel make):

etags.o: etags.c ctags.o $(COMPILE) -DETAGS_REGEXPS -c etags.c ctags.o: etags.c $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o

Also, these explicit rules do not work if the de-ANSI-fication feature is used (see section 9.13 Automatic de-ANSI-fication). Supporting de-ANSI-fication requires a little more work:

etags._o: etags._c ctags.o $(COMPILE) -DETAGS_REGEXPS -c etags.c ctags._o: etags._c $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o

As it turns out, there is also a much easier way to do this same task. Some of the above techniques are useful enough that we've kept the example in the manual. However if you were to build etags and ctags in real life, you would probably use per-program compilation flags, like so:

bin_PROGRAMS = ctags etags ctags_SOURCES = etags.c ctags_CFLAGS = -DCTAGS etags_SOURCES = etags.c etags_CFLAGS = -DETAGS_REGEXPS

In this case Automake will cause `etags.c' to be compiled twice, with different flags. De-ANSI-fication will work automatically. In this instance, the names of the object files would be chosen by automake; they would be `ctags-etags.o' and `etags-etags.o'. (The name of the object files rarely matters.)

4. Creating a `Makefile.in'

To create all the `Makefile.in's for a package, run the automake program in the top level directory, with no arguments. automake will automatically find each appropriate `Makefile.am' (by scanning `configure.in'; see section 5. Scanning `configure.in') and generate the corresponding `Makefile.in'. Note that automake has a rather simplistic view of what constitutes a package; it assumes that a package has only one `configure.in', at the top. If your package has multiple `configure.in's, then you must run automake in each directory holding a `configure.in'. (Alteratively, you may rely on Autoconf's autoreconf, which is able to recurse your package tree and run automake where appropriate.)

You can optionally give automake an argument; `.am' is appended to the argument and the result is used as the name of the input file. This feature is generally only used to automatically rebuild an out-of-date `Makefile.in'. Note that automake must always be run from the topmost directory of a project, even if being used to regenerate the `Makefile.in' in some subdirectory. This is necessary because automake must scan `configure.in', and because automake uses the knowledge that a `Makefile.in' is in a subdirectory to change its behavior in some cases.

automake accepts the following options:

`-a'

`--add-missing'

Automake requires certain common files to exist in certain situations; for instance `config.guess' is required if `configure.in' runs AC_CANONICAL_HOST. Automake is distributed with several of these files (see section 2.6 Programs automake might require); this option will cause the missing ones to be automatically added to the package, whenever possible. In general if Automake tells you a file is missing, try using this option. By default Automake tries to make a symbolic link pointing to its own copy of the missing file; this can be changed with --copy.

`--libdir=dir'

Look for Automake data files in directory dir instead of in the installation directory. This is typically used for debugging.

`-c'

`--copy'

When used with --add-missing, causes installed files to be copied. The default is to make a symbolic link.

`--cygnus'

Causes the generated `Makefile.in's to follow Cygnus rules, instead of GNU or Gnits rules. For more information, see 22. The effect of --cygnus.

`-f'

`--force-missing'

When used with --add-missing, causes standard files to be reinstalled even if they already exist in the source tree. This involves removing the file from the source tree before creating the new symlink (or, with --copy, copying the new file).

`--foreign'

Set the global strictness to `foreign'. For more information, see 2.2 Strictness.

`--gnits'

Set the global strictness to `gnits'. For more information, see 21. The effect of --gnu and --gnits.

`--gnu'

Set the global strictness to `gnu'. For more information, see 21. The effect of --gnu and --gnits. This is the default strictness.

`--help'

Print a summary of the command line options and exit.

`-i'

`--ignore-deps'

This disables the dependency tracking feature in generated `Makefile's; see 9.14 Automatic dependency tracking.

`--include-deps'

This enables the dependency tracking feature. This feature is enabled by default. This option is provided for historical reasons only and probably should not be used.

`--no-force'

Ordinarily automake creates all `Makefile.in's mentioned in `configure.in'. This option causes it to only update those `Makefile.in's which are out of date with respect to one of their dependents.

`-o dir'

`--output-dir=dir'

Put the generated `Makefile.in' in the directory dir. Ordinarily each `Makefile.in' is created in the directory of the corresponding `Makefile.am'. This option is deprecated and will be removed in a future release.

`-v'

`--verbose'

Cause Automake to print information about which files are being read or created.

`--version'

Print the version number of Automake and exit.

`--Werror'

`--Wno-error'

`--Werror' will cause all warnings issued by automake to become errors. Errors affect the exit status of automake, while warnings do not. `--Wno-error', the default, causes warnings to be treated as warnings only.

5. Scanning `configure.in'

Automake scans the package's `configure.in' to determine certain information about the package. Some autoconf macros are required and some variables must be defined in `configure.in'. Automake will also use information from `configure.in' to further tailor its output.

Automake also supplies some Autoconf macros to make the maintenance easier. These macros can automatically be put into your `aclocal.m4' using the aclocal program.

5.1 Configuration requirements
5.2 Other things Automake recognizes
5.3 Auto-generating aclocal.m4
5.4 Autoconf macros supplied with Automake
5.5 Writing your own aclocal macros

5.1 Configuration requirements

The one real requirement of Automake is that your `configure.in' call AM_INIT_AUTOMAKE. This macro does several things which are required for proper Automake operation (see section 5.4 Autoconf macros supplied with Automake).

Here are the other macros which Automake requires but which are not run by AM_INIT_AUTOMAKE:

AC_CONFIG_FILES

AC_OUTPUT

Automake uses these to determine which files to create (see section `Creating Output Files' in The Autoconf Manual). A listed file is considered to be an Automake generated `Makefile' if there exists a file with the same name and the `.am' extension appended. Typically, AC_CONFIG_FILES([foo/Makefile]) will cause Automake to generate `foo/Makefile.in' if `foo/Makefile.am' exists.

Other listed files are treated differently. Currently the only difference is that an Automake `Makefile' is removed by make distclean, while other files are removed by make clean.

5.2 Other things Automake recognizes

Automake will also recognize the use of certain macros and tailor the generated `Makefile.in' appropriately. Currently recognized macros and their effects are:

AC_CONFIG_HEADER

Automake requires the use of AM_CONFIG_HEADER (see section 5.4 Autoconf macros supplied with Automake), which is similar to AC_CONFIG_HEADER (see section `Configuration Header Files' in The Autoconf Manual), but does some useful Automake-specific work.

AC_CONFIG_AUX_DIR

Automake will look for various helper scripts, such as `mkinstalldirs', in the directory named in this macro invocation. If not seen, the scripts are looked for in their `standard' locations (either the top source directory, or in the source directory corresponding to the current `Makefile.am', whichever is appropriate). See section `Finding `configure' Input' in The Autoconf Manual. FIXME: give complete list of things looked for in this directory

AC_PATH_XTRA

Automake will insert definitions for the variables defined by AC_PATH_XTRA into each `Makefile.in' that builds a C program or library. See section `System Services' in The Autoconf Manual.

AC_CANONICAL_HOST

Automake will ensure that `config.guess' and `config.sub' exist. Also, the `Makefile' variables `host_alias' and `host_triplet' are introduced. See section `Getting the Canonical System Type' in The Autoconf Manual.

AC_CANONICAL_SYSTEM

This is similar to AC_CANONICAL_HOST, but also defines the `Makefile' variables `build_alias' and `target_alias'. See section `Getting the Canonical System Type' in The Autoconf Manual.

AC_FUNC_ALLOCA

AC_FUNC_ERROR_AT_LINE

AC_FUNC_FNMATCH

AC_FUNC_GETLOADAVG

AC_FUNC_MEMCMP

AC_FUNC_MKTIME

AC_FUNC_OBSTACK

AC_FUNC_STRTOD

AC_REPLACE_FUNCS

AC_REPLACE_GNU_GETOPT

AC_STRUCT_ST_BLOCKS

AM_WITH_REGEX

Automake will ensure that the appropriate dependencies are generated for the objects corresponding to these macros. Also, Automake will verify that the appropriate source files are part of the distribution. Note that Automake does not come with any of the C sources required to use these macros, so automake -a will not install the sources. See section 9.2 Building a library, for more information. Also, see section `Particular Function Checks' in The Autoconf Manual.

AC_LIBOBJ

LIBOBJS

AC_LIBSOURCE

AC_LIBSOURCES

Automake will detect statements which put `.o' files into LIBOBJS, or pass `.o' files to AC_LIBOBJ, and will treat these additional files as if they were discovered via AC_REPLACE_FUNCS. Similarly, Automake will also distribute file listed in AC_LIBSOURCE and AC_LIBSOURCES.

Note that assignments to LIBOBJS is a construct which is being phased out; they will be ignored in a future release of Automake. You should call the AC_LIBOBJ macro instead. See section `Generic Function Checks' in The Autoconf Manual.

AC_PROG_RANLIB

This is required if any libraries are built in the package. See section `Particular Program Checks' in The Autoconf Manual.

AC_PROG_CXX

This is required if any C++ source is included. See section `Particular Program Checks' in The Autoconf Manual.

AC_PROG_F77

This is required if any Fortran 77 source is included. This macro is distributed with Autoconf version 2.13 and later. See section `Particular Program Checks' in The Autoconf Manual.

AC_F77_LIBRARY_LDFLAGS

This is required for programs and shared libraries that are a mixture of languages that include Fortran 77 (see section 9.10.3 Mixing Fortran 77 With C and C++). See section Autoconf macros supplied with Automake.

AC_PROG_LIBTOOL

Automake will turn on processing for libtool (see section `Introduction' in The Libtool Manual).

AC_PROG_YACC

If a Yacc source file is seen, then you must either use this macro or define the variable `YACC' in `configure.in'. The former is preferred (see section `Particular Program Checks' in The Autoconf Manual).

AC_PROG_LEX

If a Lex source file is seen, then this macro must be used. See section `Particular Program Checks' in The Autoconf Manual.

AM_C_PROTOTYPES

This is required when using automatic de-ANSI-fication; see 9.13 Automatic de-ANSI-fication.

AM_GNU_GETTEXT

This macro is required for packages which use GNU gettext (see section 11.2 Gettext). It is distributed with gettext. If Automake sees this macro it ensures that the package meets some of gettext's requirements.

AM_MAINTAINER_MODE

This macro adds a `--enable-maintainer-mode' option to configure. If this is used, automake will cause `maintainer-only' rules to be turned off by default in the generated `Makefile.in's. This macro is disallowed in `Gnits' mode (see section 21. The effect of --gnu and --gnits). This macro defines the `MAINTAINER_MODE' conditional, which you can use in your own `Makefile.am'.

AC_SUBST

AC_CHECK_TOOL

AC_CHECK_PROG

AC_CHECK_PROGS

AC_PATH_PROG

AC_PATH_PROGS

For each of these macros, the first argument is automatically defined as a variable in each generated `Makefile.in'. See section `Setting Output Variables' in The Autoconf Manual, and section `Generic Program Checks' in The Autoconf Manual.

5.3 Auto-generating aclocal.m4

Automake includes a number of Autoconf macros which can be used in your package; some of them are actually required by Automake in certain situations. These macros must be defined in your `aclocal.m4'; otherwise they will not be seen by autoconf.

The aclocal program will automatically generate `aclocal.m4' files based on the contents of `configure.in'. This provides a convenient way to get Automake-provided macros, without having to search around. Also, the aclocal mechanism allows other packages to supply their own macros.

At startup, aclocal scans all the `.m4' files it can find, looking for macro definitions. Then it scans `configure.in'. Any mention of one of the macros found in the first step causes that macro, and any macros it in turn requires, to be put into `aclocal.m4'.

The contents of `acinclude.m4', if it exists, are also automatically included in `aclocal.m4'. This is useful for incorporating local macros into `configure'.

aclocal tries to be smart about looking for new AC_DEFUNs in the files it scans. It also tries to copy the full text of the scanned file into `aclocal.m4', including both `#' and `dnl' comments. If you want to make a comment which will be completely ignored by aclocal, use `##' as the comment leader.

aclocal accepts the following options:

--acdir=dir

Look for the macro files in dir instead of the installation directory. This is typically used for debugging.

--help

Print a summary of the command line options and exit.

-I dir

Add the directory dir to the list of directories searched for `.m4' files.

--output=file

Cause the output to be put into file instead of `aclocal.m4'.

--print-ac-dir

Prints the name of the directory which aclocal will search to find third-party `.m4' files. When this option is given, normal processing is suppressed. This option can be used by a package to determine where to install a macro file.

--verbose

Print the names of the files it examines.

--version

Print the version number of Automake and exit.

5.4 Autoconf macros supplied with Automake

Automake ships with several Autoconf macros that you can use from your `configure.in'. When you use one of them it will be included by aclocal in `aclocal.m4'.

5.4.1 Public macros		Macros that you can use.
5.4.2 Private macros		Macros that you should not use.

5.4.1 Public macros

AM_CONFIG_HEADER

Automake will generate rules to automatically regenerate the config header.

AM_ENABLE_MULTILIB

This is used when a "multilib" library is being built. The first optional argument is the name of the `Makefile' being generated; it defaults to `Makefile'. The second option argument is used to find the top source directory; it defaults to the empty string (generally this should not be used unless you are familiar with the internals). See section 18.3 Support for Multilibs.

AM_C_PROTOTYPES

Check to see if function prototypes are understood by the compiler. If so, define `PROTOTYPES' and set the output variables `U' and `ANSI2KNR' to the empty string. Otherwise, set `U' to `_' and `ANSI2KNR' to `./ansi2knr'. Automake uses these values to implement automatic de-ANSI-fication.

AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL

If the use of TIOCGWINSZ requires `<sys/ioctl.h>', then define GWINSZ_IN_SYS_IOCTL. Otherwise TIOCGWINSZ can be found in `<termios.h>'.

AM_INIT_AUTOMAKE([OPTIONS])

AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])

Runs many macros required for proper operation of the generated Makefiles.

This macro has two forms, the second of which has two required arguments: the package and the version number. This latter form is obsolete because the package and version can be obtained from Autoconf's AC_INIT macro (which itself has an old and a new form).

If your `configure.in' has:

AC_INIT(src/foo.c) AM_INIT_AUTOMAKE(mumble, 1.5)

you can modernize it as follow:

AC_INIT(mumble, 1.5) AC_CONFIG_SRCDIR(src/foo.c) AM_INIT_AUTOMAKE

Note that if you're upgrading your `configure.in' from an earlier version of Automake, it is not always correct to simply move the package and version arguments from AM_INIT_AUTOMAKE directly to AC_INIT, as in the example above. The first argument of AC_INIT is the name of your package (e.g. `GNU Automake'), not the tarball name (e.g. `automake') you used to pass to AM_INIT_AUTOMAKE. Autoconf's rule to derive a tarball name from the package name should work for most but not all packages. Especially, if your tarball name is not all lower case, you will have to use the four-argument form of AC_INIT (supported in Autoconf versions greater than 2.52g).

When AM_INIT_AUTOMAKE is called with a single argument, it is interpreted as a space-separated list of Automake options which should be applied to every `Makefile.am' in the tree. The effect is as if each option were listed in AUTOMAKE_OPTIONS.

By default this macro AC_DEFINE's `PACKAGE' and `VERSION'. This can be avoided by passing the `no-define' option, as in:

AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])

or by passing a third non-empty argument to the obsolete form.

AM_PATH_LISPDIR

Searches for the program emacs, and, if found, sets the output variable lispdir to the full path to Emacs' site-lisp directory.

Note that this test assumes the emacs found to be a version that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other emacsen can cause this test to hang (some, like old versions of MicroEmacs, start up in interactive mode, requiring `C-x C-c' to exit, which is hardly obvious for a non-emacs user). In most cases, however, you should be able to use `C-c' to kill the test. In order to avoid problems, you can set EMACS to "no" in the environment, or use the `--with-lispdir' option to configure to explictly set the correct path (if you're sure you have an emacs that supports Emacs Lisp.

AM_PROG_AS

Use this macro when you have assembly code in your project. This will choose the assembler for you (by default the C compiler) and set CCAS, and will also set CCASFLAGS if required.

AM_PROG_CC_C_O

This is like AC_PROG_CC_C_O, but it generates its results in the manner required by automake. You must use this instead of AC_PROG_CC_C_O when you need this functionality.

AM_PROG_CC_STDC

If the C compiler is not in ANSI C mode by default, try to add an option to output variable CC to make it so. This macro tries various options that select ANSI C on some system or another. It considers the compiler to be in ANSI C mode if it handles function prototypes correctly.

If you use this macro, you should check after calling it whether the C compiler has been set to accept ANSI C; if not, the shell variable am_cv_prog_cc_stdc is set to `no'. If you wrote your source code in ANSI C, you can make an un-ANSIfied copy of it by using the ansi2knr option (see section 9.13 Automatic de-ANSI-fication).

AM_PROG_LEX

Like AC_PROG_LEX (see section `Particular Program Checks' in The Autoconf Manual), but uses the missing script on systems that do not have lex. `HP-UX 10' is one such system.

AM_PROG_GCJ

This macro finds the gcj program or causes an error. It sets `GCJ' and `GCJFLAGS'. gcj is the Java front-end to the GNU Compiler Collection.

AM_SYS_POSIX_TERMIOS

Check to see if POSIX termios headers and functions are available on the system. If so, set the shell variable am_cv_sys_posix_termios to `yes'. If not, set the variable to `no'.

AM_WITH_DMALLOC

Add support for the dmalloc package. If the user configures with `--with-dmalloc', then define WITH_DMALLOC and add `-ldmalloc' to LIBS.

AM_WITH_REGEX

Adds `--with-regex' to the configure command line. If specified (the default), then the `regex' regular expression library is used, `regex.o' is put into `LIBOBJS', and `WITH_REGEX' is defined. If `--without-regex' is given, then the `rx' regular expression library is used, and `rx.o' is put into `LIBOBJS'.

5.4.2 Private macros

The following macros are private macros you should not call directly. They are called by the other public macros when appropriate. Do not rely on them, as they might be changed in a future version. Consider them as implementation details; or better, do not consider them at all: skip this section!

_AM_DEPENDENCIES

AM_SET_DEPDIR

AM_DEP_TRACK

AM_OUTPUT_DEPENDENCY_COMMANDS

These macros are used to implement automake's automatic dependency tracking scheme. They are called automatically by automake when required, and there should be no need to invoke them manually.

AM_MAKE_INCLUDE

This macro is used to discover how the user's make handles include statements. This macro is automatically invoked when needed; there should be no need to invoke it manually.

AM_PROG_INSTALL_STRIP

This is used to find a version of install which can be used to strip a program at installation time. This macro is automatically included when required.

AM_SANITY_CHECK

This checks to make sure that a file created in the build directory is newer than a file in the source directory. This can fail on systems where the clock is set incorrectly. This macro is automatically run from AM_INIT_AUTOMAKE.

5.5 Writing your own aclocal macros

The aclocal program doesn't have any built-in knowledge of any macros, so it is easy to extend it with your own macros.

This is mostly used for libraries which want to supply their own Autoconf macros for use by other programs. For instance the gettext library supplies a macro AM_GNU_GETTEXT which should be used by any package using gettext. When the library is installed, it installs this macro so that aclocal will find it.

A file of macros should be a series of AC_DEFUN's. The aclocal programs also understands AC_REQUIRE, so it is safe to put each macro in a separate file. See section `Prerequisite Macros' in The Autoconf Manual, and section `Macro Definitions' in The Autoconf Manual.

A macro file's name should end in `.m4'. Such files should be installed in `aclocal --print-ac-dir` (which usually happens to be `$(datadir)/aclocal').

6. The top-level `Makefile.am'

In packages with subdirectories, the top level `Makefile.am' must tell Automake which subdirectories are to be built. This is done via the SUBDIRS variable.

The SUBDIRS macro holds a list of subdirectories in which building of various sorts can occur. Many targets (e.g. all) in the generated `Makefile' will run both locally and in all specified subdirectories. Note that the directories listed in SUBDIRS are not required to contain `Makefile.am's; only `Makefile's (after configuration). This allows inclusion of libraries from packages which do not use Automake (such as gettext). The directories mentioned in SUBDIRS must be direct children of the current directory. For instance, you cannot put `src/subdir' into SUBDIRS.

In packages that use subdirectories, the top-level `Makefile.am' is often very short. For instance, here is the `Makefile.am' from the GNU Hello distribution:

EXTRA_DIST = BUGS ChangeLog.O README-alpha SUBDIRS = doc intl po src tests

It is possible to override the SUBDIRS variable if, like in the case of GNU Inetutils, you want to only build a subset of the entire package. In your `Makefile.am' include:

SUBDIRS = @MY_SUBDIRS@

Then in your `configure.in' you can specify:

MY_SUBDIRS="src doc lib po" AC_SUBST(MY_SUBDIRS)

(Note that we don't use the variable name SUBDIRS in our `configure.in'; that would cause Automake to believe that every `Makefile.in' should recurse into the listed subdirectories.)

The upshot of this is that Automake is tricked into building the package to take the subdirs, but doesn't actually bind that list until configure is run.

Although the SUBDIRS macro can contain configure substitutions (e.g. `@DIRS@'); Automake itself does not actually examine the contents of this variable.

If SUBDIRS is defined, then your `configure.in' must include AC_PROG_MAKE_SET. When Automake invokes make in a subdirectory, it uses the value of the MAKE variable. It passes the value of the variable AM_MAKEFLAGS to the make invocation; this can be set in `Makefile.am' if there are flags you must always pass to make.

The use of SUBDIRS is not restricted to just the top-level `Makefile.am'. Automake can be used to construct packages of arbitrary depth.

By default, Automake generates `Makefiles' which work depth-first (`postfix'). However, it is possible to change this ordering. You can do this by putting `.' into SUBDIRS. For instance, putting `.' first will cause a `prefix' ordering of directories. All `clean' targets are run in reverse order of build targets.

Sometimes, such as when running make dist, you want all possible subdirectories to be examined. In this case Automake will use DIST_SUBDIRS, instead of SUBDIRS, to determine where to recurse. This variable will also be used when the user runs distclean or maintainer-clean. It should be set to the full list of subdirectories in the project. If this macro is not set, Automake will attempt to set it for you.

7. An Alternative Approach to Subdirectories

If you've ever read Peter Miller's excellent paper, Recursive Make Considered Harmful, the preceding section on the use of subdirectories will probably come as unwelcome advice. For those who haven't read the paper, Miller's main thesis is that recursive make invocations are both slow and error-prone.

Automake provides sufficient cross-directory support (2) to enable you to write a single `Makefile.am' for a complex multi-directory package.

By default an installable file specified in a subdirectory will have its directory name stripped before installation. For instance, in this example, the header file will be installed as `$(includedir)/stdio.h':

include_HEADERS = inc/stdio.h

However, the `nobase_' prefix can be used to circumvent this path stripping. In this example, the header file will be installed as `$(includedir)/sys/types.h':

nobase_include_HEADERS = sys/types.h

`nobase_' should be specified first when used in conjonction with either `dist_' or `nodist_' (see section 15. What Goes in a Distribution). For instance:

nobase_dist_pkgdata_DATA = images/vortex.pgm

8. Rebuilding Makefiles

Automake generates rules to automatically rebuild `Makefile's, `configure', and other derived files like `Makefile.in'.

If you are using AM_MAINTAINER_MODE in `configure.in', then these automatic rebuilding rules are only enabled in maintainer mode.

Sometimes you need to run aclocal with an argument like -I to tell it where to find `.m4' files. Since sometimes make will automatically run aclocal, you need a way to specify these arguments. You can do this by defining ACLOCAL_AMFLAGS; this holds arguments which are passed verbatim to aclocal. This macro is only useful in the top-level `Makefile.am'.

9. Building Programs and Libraries

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

9.1 Building a program
9.2 Building a library
9.3 Building a Shared Library		Building a Libtool library
9.4 Program and Library Variables		Variables controlling program and library builds
9.5 Special handling for LIBOBJS and ALLOCA
9.6 Variables used when building a program
9.7 Yacc and Lex support
9.8 C++ Support
9.9 Assembly Support
9.10 Fortran 77 Support
9.11 Java Support
9.12 Support for Other Languages
9.13 Automatic de-ANSI-fication
9.14 Automatic dependency tracking
9.15 Support for executable extensions

9.1 Building a program

9.1.1 Introductory blathering

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, 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 which 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'; that is, the default is to compile a single C file whose base name is the name of the program itself. (This is a terrible default but we are stuck with it for historical reasons.)

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

9.1.2 Conditional compilations

You can't put a configure substitution (e.g., `@FOO@') 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.

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

In this case, `hello-linux.o' would be added, via a `configure' substitution, to hello_LDADD in order to cause it to be built and linked in.

An often simpler way to compile source files conditionally is to use Automake conditionals. For instance, you could use this construct to conditionally use `hello-linux.c' or `hello-generic.c' as the basis for your program `hello':

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

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.

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.

Of course you can use Automake conditionals to determine the programs to be built.

9.1.3 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 the global LDADD. If this variable exists for a given program, then that program is not linked using LDADD.

For instance, in GNU cpio, pax, cpio and mt are linked against the library `libcpio.a'. However, rmt is built in the same directory, and has no such link requirement. Also, mt and rmt are only built on certain architectures. Here is what cpio's `src/Makefile.am' looks like (abridged):

bin_PROGRAMS = cpio pax @MT@ libexec_PROGRAMS = @RMT@ EXTRA_PROGRAMS = mt rmt LDADD = ../lib/libcpio.a @INTLLIBS@ rmt_LDADD = cpio_SOURCES = ... pax_SOURCES = ... mt_SOURCES = ... rmt_SOURCES = ...

`prog_LDADD' is inappropriate for passing program-specific linker flags (except for `-l', `-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 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', `-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.

9.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 9.3 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 2.4 How derived variables are named), so the `_SOURCES' variable corresponding to `liblob.a' is `liblob_a_SOURCES', not `liblob.a_SOURCES'.

Extra objects can be added to a library using the `library_LIBADD' variable. This should be used for objects determined by configure. Again from cpio:

libcpio_a_LIBADD = @LIBOBJS@ @ALLOCA@

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

9.3 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 in order to work properly, 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 @LIBOBJS@, a libtool library must use @LTLIBOBJS@. This is required because the object files that libtool operates on do not necessarily end in `.o'. The libtool manual contains more details on this topic.

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

Ordinarily, Automake requires that a shared library's name start with `lib'. However, if you are building a dynamically loadable module then you might wish to use a "nonstandard" name. In this case, put -module into the `_LDFLAGS' variable.

See section `The Libtool Manual' in The Libtool Manual, for more information.

9.4 Program and Library Variables

Associated with each program are a collection of variables which 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 which 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 9.12 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 17. 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. (3) 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, e.g., `nodist_EXTRA_maude_SOURCES'.

`maude_AR'

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

libmaude_a_AR = $(CXX) -ar -o

`maude_LIBADD'

Extra objects can be added to a static library using the `_LIBADD' variable. This should be used for objects determined by configure. Note that `_LIBADD' is not used for shared libraries; there you must use `_LDADD'.

`maude_LDADD'

Extra objects can be added to a shared library or a program by listing them in the `_LDADD' variable. This should be used for objects determined by configure.

`_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.in' 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)

`maude_LDFLAGS'

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

`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 which 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_CFLAGS'

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. The flags are `_CFLAGS', `_CXXFLAGS', `_OBJCFLAGS', `_YFLAGS', `_CCASFLAGS', `_FFLAGS', `_RFLAGS', and `_GCJFLAGS'.

When using a per-program 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'.

In compilations with per-program flags, the ordin