   This file documents GNU automake 1.2

   Copyright (C) 1995, 96, 97 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

GNU Automake
************

   This file documents the GNU Automake package for creating GNU
Standards-compliant Makefiles from template files.  This edition
documents version 1.2.

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 Makefile Conventions (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 files 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 The Autoconf Manual (autoconf)),
and enforces certain restrictions on the
`configure.in' contents.

   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
<automake-bugs@gnu.ai.mit.edu>.

General ideas
*************

   There are a few basic ideas that will help understand how Automake
works.

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 instances a
`bin_PROGRAMS' macro definition will cause targets for compiling and
linking to be generated.

   The macro definitions and targets in the `Makefile.am' are copied
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 GNU make extensions are not recognized by Automake.  Using
such extensions in a `Makefile.am' will lead to errors or confusing
behavior.

   Automake tries to group comments with adjoining targets (or variable
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 variable defined in `Makefile.am' will override any
definition of the variable 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 variables generated by
`automake' are considered to be for internal use only, and their names
might change in future releases.

   When examining a variable definition, Automake will recursively
examine variables referenced in the definition.  E.g., 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 `##' 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

Depth
=====

   `automake' supports three kinds of directory hierarchy: "flat",
"shallow", and "deep".

   A "flat" package is one in which all the files are in a single
directory.  The `Makefile.am' for such a package by definition lacks a
`SUBDIRS' macro.  An example of such a package is `termutils'.

   A "deep" package is one in which all the source lies in
subdirectories; the top level directory contains mainly configuration
information.  GNU cpio is a good example of such a package, as is GNU
`tar'.  The top level `Makefile.am' for a deep package will contain a
`SUBDIRS' macro, but no other macros to define objects which are built.

   A "shallow" package is one in which the primary source resides in
the top-level directory, while various parts (typically libraries)
reside in subdirectories.  Automake is one such package (as is GNU
`make', which does not currently use `automake').

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.

   For more information on the precise implications of the strictness
level, see Gnits.

The Uniform Naming Scheme
=========================

   Automake 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.  These variables are called "primary"
variables.  For instance, the primary variable `PROGRAMS' holds a list
of programs which are to be compiled and linked.

   A different set of variables is used to decide where the built
objects should be installed.  These variables are named after the
primary variables, but have a prefix indicating which standard
directory should be used as the installation directory.  The standard
directory names are given in the GNU standards (see Directory Variables (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 `$(datadir)/@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 to 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 = @PROGRAMS@

   Defining a primary variable without a prefix (eg `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 (eg `zar') is valid if a variable of the
same name with `dir' appended is defined (eg `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 not be installed at all.

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

   Possible primary names are `PROGRAMS', `LIBRARIES', `LISP',
`SCRIPTS', `DATA', `HEADERS', `MANS', and `TEXINFOS'.

How derived variables are named
===============================

   Sometimes a Makefile variable name is derived from some text the user
supplies.  For instance program names are rewritten into Makefile macro
names.  Automake canonicalizes this text, so that it does not have to
follow Makefile variable naming rules.  All characters in the name
except for letters, numbers, and the underscore are turned into
underscores when making macro references.  E.g., if your program is
named `sniff-glue', the derived variable name would be
`sniff_glue_SOURCES', not `sniff-glue_SOURCES'.

Some example packages
*********************

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 simplest way to do this is to add
an `AM_INIT_AUTOMAKE' call near the beginning:

     AM_INIT_AUTOMAKE(zardoz, 1.0)

   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... you already have an `aclocal.m4',
because you had to write some hairy macros for your program.  `aclocal'
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'.  `zardoz'
is a user program, so you want to install it where the rest of the user
programs go.  `zardoz' also 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!

A classic program
=================

   `hello' is renowned for its classic simplicity and versatility.
This section shows how Automake could be used with the Hello package.
The examples below are from the latest GNU Hello, but all the
maintainer-only code has been 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.  GNU Hello is a deep
package.

   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 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)\"

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 `ctags_SOURCES' is defined to be empty--that way no
implicit value is substituted.  The implicit value, however, is used to
generate `etags' from `etags.o'.

   `ctags_LDADD' is used to get `ctags.o' into the link line.
`ctags_DEPENDENCIES' is generated by Automake.

   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; supporting that 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

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

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

`--amdir=DIR'
     Look for Automake data files in directory DIR instead of in the
     installation directory.  This is typically used for debugging.

`--build-dir=DIR'
     Tell Automake where the build directory is.  This option is used
     when including dependencies into a `Makefile.in' generated by `make
     dist'; it should not be used otherwise.

`--cygnus'
     Causes the generated `Makefile.in's to follow Cygnus rules, instead
     of GNU or Gnits rules.  See Cygnus for more information.

`--foreign'
     Set the global strictness to `foreign'.  See Strictness for
     more information.

`--gnits'
     Set the global strictness to `gnits'.  See Gnits for more
     information.

`--gnu'
     Set the global strictness to `gnu'.  See Gnits for more
     information.  This is the default strictness.

`--help'
     Print a summary of the command line options and exit.

`-i'
`--include-deps'
     Include all automatically generated dependency information (see
     Dependencies.) in the generated `Makefile.in'.  This is
     generally done when making a distribution; see Dist.

`--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 used when making
     distributions.

`--srcdir-name=DIR'
     Tell Automake the name of the source directory associated with the
     current build.  This option is used when including dependencies
     into a `Makefile.in' generated by `make dist'; it should not be
     used otherwise.

`-v'
`--verbose'
     Cause Automake to print information about which files are being
     read or created.

`--version'
     Print the version number of Automake and exit.

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.

Configuration requirements
==========================

   The simplest way to meet the basic Automake requirements is to use
the macro `AM_INIT_AUTOMAKE' (FIXME: xref).  But if you prefer, you can
do the required steps by hand:

   * Define the variables `PACKAGE' and `VERSION' with `AC_SUBST'.
     `PACKAGE' should be the name of the package as it appears when
     bundled for distribution.  For instance, Automake defines `PACKAGE'
     to be `automake'.  `VERSION' should be the version number of the
     release that is being developed.  We recommend that you make
     `configure.in' the only place in your package where the version
     number is defined; this makes releases simpler.

     Automake doesn't do any interpretation of `PACKAGE' or `VERSION',
     except in `Gnits' mode (FIXME xref).

   * Use the macro `AC_ARG_PROGRAM' if a program or script is installed.

   * Use `AC_PROG_MAKE_SET' if the package is not flat.

   * Use `AM_SANITY_CHECK' to make sure the build environment is sane.

   * Use `AM_PROG_INSTALL' if any scripts (see Scripts.) are
     installed by the package.  Otherwise, use `AC_PROG_INSTALL'.

   * Use `AM_MISSING_PROG' to see whether the programs `aclocal',
     `autoconf', `automake', `autoheader', and `makeinfo' are in the
     build environment.  Here is how this is done:
          missing_dir=`cd $ac_aux_dir && pwd`
          AM_MISSING_PROG(ACLOCAL, aclocal, $missing_dir)
          AM_MISSING_PROG(AUTOCONF, autoconf, $missing_dir)
          AM_MISSING_PROG(AUTOMAKE, automake, $missing_dir)
          AM_MISSING_PROG(AUTOHEADER, autoheader, $missing_dir)
          AM_MISSING_PROG(MAKEINFO, makeinfo, $missing_dir)

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

`AC_OUTPUT'
     Automake uses this to determine which files to create.  Listed
     files named `Makefile' are treated as `Makefile's.  Other listed
     files are treated differently.  Currently the only difference is
     that a `Makefile' is removed by `make distclean', while other files
     are removed by `make clean'.

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', which is similar
     to `AC_CONFIG_HEADER' 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).  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.

`AC_CANONICAL_HOST'
`AC_CHECK_TOOL'
     Automake will ensure that `config.guess' and `config.sub' exist.
     Also, the `Makefile' variables `host_alias' and `host_triplet' are
     introduced.

`AC_CANONICAL_SYSTEM'
     This is similar to `AC_CANONICAL_HOST', but also defines the
     `Makefile' variables `build_alias' and `target_alias'.

`AC_FUNC_ALLOCA'
`AC_FUNC_GETLOADAVG'
`AC_FUNC_MEMCMP'
`AC_STRUCT_ST_BLOCKS'
`AC_FUNC_FNMATCH'
`AM_FUNC_STRTOD'
`AC_REPLACE_FUNCS'
`AC_REPLACE_GNU_GETOPT'
`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 A Library for more information.

`LIBOBJS'
     Automake will detect statements which put `.o' files into
     `LIBOBJS', and will treat these additional files as if they were
     discovered via `AC_REPLACE_FUNCS'.

`AC_PROG_RANLIB'
     This is required if any libraries are built in the package.

`AC_PROG_CXX'
     This is required if any C++ source is included.

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

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

`AC_DECL_YYTEXT'
     This macro is required if there is Lex source in the package.

`AC_PROG_LEX'
     If a Lex source file is seen, then this macro must be used.

`ALL_LINGUAS'
     If Automake sees that this variable is set in `configure.in', it
     will check the `po' directory to ensure that all the named `.po'
     files exist, and that all the `.po' files that exist are named.

`AM_C_PROTOTYPES'
     This is required when using automatic de-ANSI-fication, see
     ANSI.

`AM_GNU_GETTEXT'
     This macro is required for packages which use GNU gettext (see
     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.  FIXME xref.

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

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 is extensible for use by other packages.

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

`--verbose'
     Print the names of the files it examines.

`--version'
     Print the version number of Automake and exit.

Autoconf macros supplied with Automake
======================================

`AM_CONFIG_HEADER'
     Automake will generate rules to automatically regenerate the config
     header.  If you do use this macro, you must create the file
     `stamp-h.in' in your source directory.  It can be empty.

`AM_CYGWIN32'
     Check to see if this `configure' is being run in the `Cygwin32'
     environment.  (FIXME xref).  If so, define output variable
     `EXEEXT' to `.exe'; otherwise define it to the empty string.
     Automake recognizes this macro and uses it to generate
     `Makefile.in's which will automatically work under `Cygwin32'.  In
     the `Cygwin32' environment, `gcc' generates executables whose
     names end in `.exe', even if this was not specified on the command
     line.  Automake adds special code to `Makefile.in' to gracefully
     deal with this.

`AM_FUNC_STRTOD'
     If the `strtod' function is not available, or does not work
     correctly (like the one on SunOS 5.4), add `strtod.o' to output
     variable `LIBOBJS'.

`AM_FUNC_ERROR_AT_LINE'
     If the function `error_at_line' is not found, then add `error.o'
     to `LIBOBJS'.

`AM_FUNC_MKTIME'
     Check for a working `mktime' function.  If not found, add
     `mktime.o' to `LIBOBJS'.

`AM_FUNC_OBSTACK'
     Check for the GNU obstacks code; if not found, add `obstack.o' to
     `LIBOBJS'.

`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'
     Runs many macros that most `configure.in''s need.  This macro has
     two required arguments, the package and the version number.  By
     default this macro `AC_DEFINE''s `PACKAGE' and `VERSION'.  This
     can be avoided by passing in a non-empty third argument.

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

`AM_PROG_CC_STDC'
     If the C compiler in 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 defines
     `__STDC__' to 1 and 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.

`AM_PROG_INSTALL'
     Like `AC_PROG_INSTALL', but also defines `INSTALL_SCRIPT'.

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

`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_TYPE_PTRDIFF_T'
     Define `HAVE_PTRDIFF_T' if the type `ptrdiff_t' is defined in
     `<stddef.h>'.

`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'.  The `dmalloc' package can be found at
     `ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz'

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

Writing your own aclocal macros
===============================

   Aclocal 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.  Aclocal also
understands `AC_REQUIRE', so it is safe to put each macro in a separate
file.

   A macro file's name should end in `.m4'.  Such files should be
installed in `$(datadir)/aclocal'.

The top-level `Makefile.am'
***************************

   In non-flat packages, 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 (eg `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 a deep package, the top-level `Makefile.am' is often very short.
For instance, here is the `Makefile.am' from the Hello distribution:

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

   `SUBDIRS' can contain configure substitutions (eg `@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'.

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

Building Programs and Libraries
*******************************

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

Building a program
==================

   In a directory containing source that gets built into a program (as
opposed to a library), the `PROGRAMS' primary is used.  Programs can be
installed in `bindir', `sbindir', `libexecdir', `pkglibdir', or not at
all (`noinst').

   For instance:

     bin_PROGRAMS = hello

   In this simple case, the resulting `Makefile.in' will contain code
to generate a program named `hello'.  The variable `hello_SOURCES' is
used to specify which source files get built into an executable:

     hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h

   This causes each mentioned `.c' file to be compiled into the
corresponding `.o'.  Then all are linked to produce `hello'.

   If `prog_SOURCES' is needed, but not specified, then it defaults to
the single file `prog.c'.  In the example above, the definition of
`hello_SOURCES' is actually redundant.

   Multiple programs can be built in a single directory.  Multiple
programs can share a single source file.  The source file must be
listed in each `_SOURCES' definition.

   Header files listed in a `_SOURCES' definition will be included in
the distribution but otherwise ignored.  In case it isn't obvious, you
should not include the header file generated by `configure' in an
`_SOURCES' variable; this file should not be distributed.  Lex (`.l')
and yacc (`.y') files can also be listed; see Yacc and Lex.

   Automake must know all the source files that could possibly go into a
program, even if not all the files are built in every circumstance.
Any files which are only conditionally built should be listed in the
appropriate `EXTRA_' variable.  For instance, if `hello-linux.c' were
conditionally included in `hello', the `Makefile.am' would contain:

     EXTRA_hello_SOURCES = hello-linux.c

   Similarly, sometimes it is useful to determine the programs that are
to be built at configure time.  For instance, GNU `cpio' only builds
`mt' and `rmt' under special circumstances.

   In this case, you must notify `automake' of all the programs that
can possibly be built, but at the same time cause the generated
`Makefile.in' to use the programs specified by `configure'.  This is
done by having `configure' substitute values into each `_PROGRAMS'
definition, while listing all optionally built programs in
`EXTRA_PROGRAMS'.

   If you need to link against libraries that are not found by
`configure', you can use `LDADD' to do so.  This variable actually can
be used to add any options to the linker command line.

   Sometimes, multiple programs are built in one directory but do not
share the same link-time requirements.  In this case, you can use the
`PROG_LDADD' variable (where PROG is the name of the program as it
appears in some `_PROGRAMS' variable, and usually written in lowercase)
to override the global `LDADD'.  (If this variable exists for a given
program, then that program is not linked using `LDADD'.)

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

     bin_PROGRAMS = cpio pax @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' and `-L').  So, use the `prog_LDFLAGS' variable
for this purpose.

   It is also occasionally useful to have a program depend on some other
target which is not actually part of that program.  This can be done
using the `prog_DEPENDENCIES' variable.  Each program depends on the
contents of such a variable, but no further interpretation is done.

   If `prog_DEPENDENCIES' is not supplied, it is computed by Automake.
The automatically-assigned value is the contents of `prog_LDADD', with
most configure substitutions, `-l', and `-L' options removed.  The
configure substitutions that are left in are only `@LIBOBJS@' and
`@ALLOCA@'; these are left because it is known that they will not cause
an invalid value for `prog_DEPENDENCIES' to be generated.

Building a library
==================

   Building a library is much like building a program.  In this case,
the name of the primary is `LIBRARIES'.  Libraries can be installed in
`libdir' or `pkglibdir'.

   See 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 Canonicalization.), 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@

Special handling for LIBOBJS and ALLOCA
=======================================

   Automake explicitly recognizes the use of `@LIBOBJS@' and
`@ALLOCA@', and uses this information, plus the list of `LIBOBJS' files
derived from `configure.in' to automatically include the appropriate
source files in the distribution (see Dist.).  These source files
are also automatically handled in the dependency-tracking scheme, see
Dependencies.

   `@LIBOBJS@' and `@ALLOCA@' are specially recognized in any `_LDADD'
or `_LIBADD' variable.

Building a Shared Library
=========================

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

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

     lib_LTLIBRARIES = libgettext.la

   Note that shared libraries *must* be installed, so
`noinst_LTLIBRARIES' and `check_LTLIBRARIES' are not allowed.

   For each library, the `library_LIBADD' variable contains the names
of extra libtool objects (`.lo' files) to add to the shared library.
The `library_LDFLAGS' variable contains any additional libtool flags,
such as `-version-info' or `-static'.

   Where an ordinary library might include `@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.

   See Using Automake with Libtool (libtool), for more
information.

Variables used when building a program
======================================

   Occasionally it is useful to know which `Makefile' variables
Automake uses for compilations; for instance you might need to do your
own compilation in some special cases.

   Some variables are inherited from Autoconf; these are `CC',
`CFLAGS', `CPPFLAGS', `DEFS', `LDFLAGS', and `LIBS'.

   There are some additional variables which Automake itself defines:

`INCLUDES'
     A list of `-I' options.  This can be set in your `Makefile.am' if
     you have special directories you want to look in.  `automake'
     already provides some `-I' options automatically.  In particular it
     generates `-I$(srcdir)' and a `-I' pointing to the directory
     holding `config.h' (if you've used `AC_CONFIG_HEADER' or
     `AM_CONFIG_HEADER').

     `INCLUDES' can actually be used for other `cpp' options besides
     `-I'.  For instance, it is sometimes used to pass arbitrary `-D'
     options to the compiler.

`COMPILE'
     This is the command used to actually compile a C source file.  The
     filename is appended to form the complete command line.

`LINK'
     This is the command used to actually link a C program.