   This file documents GNU automake 1.7.3

   Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 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.

Public macros
-------------

`AM_CONFIG_HEADER'
     Automake will generate rules to automatically regenerate the config
     header.  This obsolete macro is a synonym of `AC_CONFIG_HEADERS'
     today (see Optional).

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

     This macro is a relic from the time Autoconf didn't offer such a
     feature.  `AM_PROG_CC_STDC''s logic has now been merged into
     Autoconf's `AC_PROG_CC' macro, therefore you should use the latter
     instead.  Chances are you are already using `AC_PROG_CC', so you
     can simply remove the `AM_PROG_CC_STDC' call and turn all
     occurrences of `$am_cv_prog_cc_stdc' into `$ac_cv_prog_cc_stdc'.
     `AM_PROG_CC_STDC' will be marked as obsolete (in the Autoconf
     sense) in Automake 1.8.

`AM_PROG_LEX'
     Like `AC_PROG_LEX' (see Particular Program Checks (autoconf)),
     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
     (ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz) 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'.

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

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 Prerequisite Macros (autoconf),
and Macro Definitions (autoconf).

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

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

Recursing subdirectories
========================

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

   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

   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 directories mentioned in `SUBDIRS' must be direct children of
the current directory.  For instance, you cannot put `src/subdir' into
`SUBDIRS'.  Instead you should put `SUBDIRS = subdir' into
`src/Makefile.am'.  Automake can be used to construct packages of
arbitrary depth this way.

   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.

Conditional subdirectories
==========================

   It is possible to define the `SUBDIRS' variable conditionally if,
like in the case of GNU `Inetutils', you want to only build a subset of
the entire package.

   To illustrate how this works, let's assume we have two directories
`src/' and `opt/'.  `src/' should always be built, but we want to
decide in `./configure' whether `opt/' will be built or not.  (For this
example we will assume that `opt/' should be built when the variable
`$want_opt' was set to `yes'.)

   Running `make' should thus recurse into `src/' always, and then
maybe in `opt/'.

   However `make dist' should always recurse into both `src/' and
`opt/'.  Because `opt/' should be distributed even if it is not needed
in the current configuration. This means `opt/Makefile' should be
created unconditionally.  (1)

   There are two ways to setup a project like this.  You can use
Automake conditionals (see Conditionals) or use Autoconf `AC_SUBST'
variables (see Setting Output Variables (autoconf)).
Using Automake conditionals is the preferred solution.

Conditional subdirectories with `AM_CONDITIONAL'
------------------------------------------------

   `configure' should output the `Makefile' for each directory and
define a condition into which `opt/' should be built.

     ...
     AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
     AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
     ...

   Then `SUBDIRS' can be defined in the top-level `Makefile.am' as
follows.

     if COND_OPT
       MAYBE_OPT = opt
     endif
     SUBDIRS = src $(MAYBE_OPT)

   As you can see, running `make' will rightly recurse into `src/' and
maybe `opt/'.

   As you can't see, running `make dist' will recurse into both `src/'
and `opt/' directories because `make dist', unlike `make all', doesn't
use the `SUBDIRS' variable.  It uses the `DIST_SUBDIRS' variable.

   In this case Automake will define `DIST_SUBDIRS = src opt'
automatically because it knows that `MAYBE_OPT' can contain `opt' in
some condition.

Conditional subdirectories with `AC_SUBST'
------------------------------------------

   Another idea is to define `MAYBE_OPT' from `./configure' using
`AC_SUBST':

     ...
     if test "$want_opt" = yes; then
       MAYBE_OPT=opt
     else
       MAYBE_OPT=
     fi
     AC_SUBST([MAYBE_OPT])
     AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
     ...

   In this case the top-level `Makefile.am' should look as follows.

     SUBDIRS = src $(MAYBE_OPT)
     DIST_SUBDIRS = src opt

   The drawback is that since Automake cannot guess what the possible
values of `MAYBE_OPT' are, it is necessary to define `DIST_SUBDIRS'.

How `DIST_SUBDIRS' is used
--------------------------

   As shown in the above examples, `DIST_SUBDIRS' is used by targets
that need to recurse in all directories, even those which have been
conditionally left out of the build.

   Precisely, `DIST_SUBDIRS' is used by `make dist', `make distclean',
and `make maintainer-clean'.  All other recursive targets use `SUBDIRS'.

   Automake will define `DIST_SUBDIRS' automatically from the possibles
values of `SUBDIRS' in all conditions.

   If `SUBDIRS' contains `AC_SUBST' variables, `DIST_SUBDIRS' will not
be defined correctly because Automake doesn't know the possible values
of these variables.  In this case `DIST_SUBDIRS' needs to be defined
manually.

   ---------- Footnotes ----------

   (1) Don't try seeking a solution where `opt/Makefile' is created
conditionally, this is a lot trickier than the solutions presented here.

An Alternative Approach to Subdirectories
*****************************************

   If you've ever read Peter Miller's excellent paper, Recursive Make
Considered Harmful
(http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html), 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 (1) 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 conjunction with
either `dist_' or `nodist_' (see Dist).  For instance:

     nobase_dist_pkgdata_DATA = images/vortex.pgm

   ---------- Footnotes ----------

   (1) We believe.  This work is new and there are probably warts.
See Introduction, for information on reporting bugs.

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 variable is only useful
in the top-level `Makefile.am'.

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

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

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

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

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

Defining program sources
------------------------

   In a directory containing source that gets built into a program (as
opposed to a library or a script), the `PROGRAMS' primary is used.
Programs can be installed in `bindir', `sbindir', `libexecdir',
`pkglibdir', 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 Yacc and Lex.

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.

Conditional compilation of sources
----------------------------------

   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.

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

Conditional compilation using `_LDADD' substitutions
....................................................

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

     bin_PROGRAMS = hello
     hello_SOURCES = hello-common.c
     EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
     hello_LDADD = @HELLO_SYSTEM@
     hello_DEPENDENCIES = @HELLO_SYSTEM@

You can then setup the `@HELLO_SYSTEM@' substitution from
`configure.in':

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

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

Conditional compilation using Automake conditionals
...................................................

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

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

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

   When using conditionals like this you don't need to use the `EXTRA_'
variable, because Automake will examine the contents of each variable
to construct the complete list of source files.

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

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

Conditional compilation of programs
-----------------------------------

   Sometimes it is useful to determine the programs that are to be built
at configure time.  For instance, GNU `cpio' only builds `mt' and `rmt'
under special circumstances.  The means to achieve conditional
compilation of programs are the same you can use to compile source
files conditionally: substitutions or conditionals.

Conditional programs using `configure' substitutions
....................................................

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

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

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

Conditional programs using Automake conditionals
................................................

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

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

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)

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

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

   Building shared libraries is a relatively complex matter.  For this
reason, GNU Libtool (see Introduction (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 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 Using Automake with Libtool (libtool), for more
information.

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

`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.  (1)  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 variable set like so:
          libmaude_a_AR = $(CXX) -ar -o

`maude_LIBADD'
     Extra objects can be added to a _library_ using the `_LIBADD'
     variable.  For instance this should be used for objects determined
     by `configure' (see A Library).

`maude_LDADD'
     Extra objects can be added to a _program_ by listing them in the
     `_LDADD' variable.  For instance this should be used for objects
     determined by `configure' (see Linking).

     `_LDADD' and `_LIBADD' are inappropriate for passing
     program-specific linker flags (except for `-l', `-L', `-dlopen'
     and `-dlpreopen').  Use the `_LDFLAGS' variable for this purpose.

     For instance, if your `configure.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_CCASFLAGS'
`maude_CFLAGS'
`maude_CPPFLAGS'
`maude_CXXFLAGS'
`maude_FFLAGS'
`maude_GCJFLAGS'
`maude_LFLAGS'
`maude_OBJCFLAGS'
`maude_RFLAGS'
`maude_YFLAGS'
     Automake allows you to set compilation flags on a per-program (or
     per-library) basis.  A single source file can be included in
     several programs, and it will potentially be compiled with
     different flags for each program.  This works for any language
     directly supported by Automake.  The flags are `_CCASFLAGS',
     `_CFLAGS', `_CPPFLAGS', `_CXXFLAGS', `_FFLAGS', `_GCJFLAGS',
     `_LFLAGS', `_OBJCFLAGS', `_RFLAGS', and `_YFLAGS'.

     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 ordinary `AM_' form of
     the flags variable is _not_ automatically included in the
     compilation (however, the user form of the variable _is_ included).
     So for instance, if you want the hypothetical `maude' compilations
     to also use the value of `AM_CFLAGS', you would need to write:

          maude_CFLAGS = ... your flags ... $(AM_CFLAGS)

`maude_DEPENDENCIES'
     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 `_DEPENDENCIES' variable.  Each program depends
     on the contents of such a variable, but no further interpretation
     is done.

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

`maude_SHORTNAME'
     On some platforms the allowable file names are very short.  In
     order to support these systems and per-program compilation flags
     at the same time, Automake allows you to set a "short name" which
     will influence how intermediate object files are named.  For
     instance, if you set `maude_SHORTNAME' to `m', then in the above
     per-program compilation flag example the object file would be named
     `m-sample.o' rather than `maude-sample.o'.  This facility is
     rarely needed in practice, and we recommend avoiding it until you
     find it is required.

   ---------- Footnotes ----------

   (1) There are other, more obscure reasons reasons for this
limitation as well.

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.

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:

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

     Automake already provides some `-I' options automatically.  In
     particular it generates `-I$(srcdir)', `-I.', and a `-I' pointing
     to the directory holding `config.h' (if you've used
     `AC_CONFIG_HEADERS' or `AM_CONFIG_HEADER').  You can disable the
     default `-I' options using the `nostdinc' option.

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

`INCLUDES'
     This does the same job as `AM_CPPFLAGS'.  It is an older name for
     the same functionality.  This variable is deprecated; we suggest
     using `AM_CPPFLAGS' instead.

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

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

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

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

Yacc and Lex support
====================

   Automake has somewhat idiosyncratic support for Yacc and Lex.

   Automake assumes that the `.c' file generated by `yacc' (or `lex')
should be named using the basename of the input file.  That is, for a
yacc source file `foo.y', Automake will cause the intermediate file to
be named `foo.c' (as opposed to `y.tab.c', which is more traditional).

   The extension of a yacc source file is used to determine the
extension of the resulting `C' or `C++' file.  Files with the extension
`.y' will be turned into `.c' files; likewise, `.yy' will become `.cc';
`.y++', `c++'; and `.yxx', `.cxx'.

   Likewise, lex source files can be used to generate `C' or `C++'; the
extensions `.l', `.ll', `.l++', and `.lxx' are recognized.

   You should never explicitly mention the intermediate (`C' or `C++')
file in any `SOURCES' variable; only list the source file.

   The intermediate files generated by `yacc' (or `lex') will be
included in any distribution that is made.  That way the user doesn't
need to have `yacc' or `lex'.

   If a `yacc' source file is seen, then your `configure.in' must
define the variable `YACC'.  This is most easily done by invoking the
macro `AC_PROG_YACC' (see Particular Program Checks (autoconf)).

   When `yacc' is invoked, it is passed `YFLAGS' and `AM_YFLAGS'.  The
former is a user variable and the latter is intended for the
`Makefile.am' author.

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

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

   If a `lex' source file is seen, then your `configure.in' must define
the variable `LEX'.  You can use `AC_PROG_LEX' to do this (see
Particular Program Checks (autoconf)), but using
`AM_PROG_LEX' macro (see Macros) is recommended.

   When `lex' is invoked, it is passed `LFLAGS' and `AM_LFLAGS'.  The
former is a user variable and the latter is intended for the
`Makefile.am' author.

   Automake makes it possible to include multiple `yacc' (or `lex')
source files in a single program.  When there is more than one distinct
`yacc' (or `lex') source file in a directory, Automake uses a small
program called `ylwrap' to run `yacc' (or `lex') in a subdirectory.
This is necessary because yacc's output filename is fixed, and a
parallel make could conceivably invoke more than one instance of `yacc'
simultaneously.  The `ylwrap' program is distributed with Automake.  It
should appear in the directory specified by `AC_CONFIG_AUX_DIR' (see
Finding `configure' Input (autoconf)), or the current directory
if that macro is not used in `configure.in'.

   For `yacc', simply managing locking is insufficient.  The output of
`yacc' always uses the same symbol names internally, so it isn't
possible to link two `yacc' parsers into the same executable.

   We recommend using the following renaming hack used in `gdb':
     #define	yymaxdepth c_maxdepth
     #define	yyparse	c_parse
     #define	yylex	c_lex
     #define	yyerror	c_error
     #define	yylval	c_lval
     #define	yychar	c_char
     #define	yydebug	c_debug
     #define	yypact	c_pact
     #define	yyr1	c_r1
     #define	yyr2	c_r2
     #define	yydef	c_def
     #define	yychk	c_chk
     #define	yypgo	c_pgo
     #define	yyact	c_act
     #define	yyexca	c_exca
     #define yyerrflag c_errflag
     #define yynerrs	c_nerrs
     #define	yyps	c_ps
     #define	yypv	c_pv
     #define	yys	c_s
     #define	yy_yys	c_yys
     #define	yystate	c_state
     #define	yytmp	c_tmp
     #define	yyv	c_v
     #define	yy_yyv	c_yyv
     #define	yyval	c_val
     #define	yylloc	c_lloc
     #define yyreds	c_reds
     #define yytoks	c_toks
     #define yylhs	c_yylhs
     #define yylen	c_yylen
     #define yydefred c_yydefred
     #define yydgoto	c_yydgoto
     #define yysindex c_yysindex
     #define yyrindex c_yyrindex
     #define yygindex c_yygindex
     #define yytable	 c_yytable
     #define yycheck	 c_yycheck
     #define yyname   c_yyname
     #define yyrule   c_yyrule

   For each define, replace the `c_' prefix with whatever you like.
These defines work for `bison', `byacc', and traditional `yacc's.  If
you find a parser generator that uses a symbol not covered here, please
report the new name so it can be added to the list.

C++ Support
===========

   Automake includes full support for C++.

   Any package including C++ code must define the output variable `CXX'
in `configure.in'; the simplest way to do this is to use the
`AC_PROG_CXX' macro (see Particular Program Checks (autoconf)).

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

`CXX'
     The name of the C++ compiler.

`CXXFLAGS'
     Any flags to pass to the C++ compiler.

`AM_CXXFLAGS'
     The maintainer's variant of `CXXFLAGS'.

`CXXCOMPILE'
     The command used to actually compile a C++ source file.  The file
     name is appended to form the complete command line.

`CXXLINK'
     The command used to actually link a C++ program.

Assembly Support
================

   Automake includes some support for assembly code.

   The variable `CCAS' holds the name of the compiler used to build
assembly code.  This compiler must work a bit like a C compiler; in
particular it must accept `-c' and `-o'.  The value of `CCASFLAGS' is
passed to the compilation.

   You are required to set `CCAS' and `CCASFLAGS' via `configure.in'.
The autoconf macro `AM_PROG_AS' will do this for you.  Unless they are
already set, it simply sets `CCAS' to the C compiler and `CCASFLAGS' to
the C compiler flags.

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