   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.

Fortran 77 Support
==================

   Automake includes full support for Fortran 77.

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

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

`F77'
     The name of the Fortran 77 compiler.

`FFLAGS'
     Any flags to pass to the Fortran 77 compiler.

`AM_FFLAGS'
     The maintainer's variant of `FFLAGS'.

`RFLAGS'
     Any flags to pass to the Ratfor compiler.

`AM_RFLAGS'
     The maintainer's variant of `RFLAGS'.

`F77COMPILE'
     The command used to actually compile a Fortran 77 source file.
     The file name is appended to form the complete command line.

`FLINK'
     The command used to actually link a pure Fortran 77 program or
     shared library.

   Automake can handle preprocessing Fortran 77 and Ratfor source files
in addition to compiling them(1).  Automake also contains some support
for creating programs and shared libraries that are a mixture of
Fortran 77 and other languages (see Mixing Fortran 77 With C and C++).

   These issues are covered in the following sections.

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

   (1) Much, if not most, of the information in the following sections
pertaining to preprocessing Fortran 77 programs was taken almost
verbatim from Catalogue of Rules (make).

Preprocessing Fortran 77
------------------------

   `N.f' is made automatically from `N.F' or `N.r'.  This rule runs
just the preprocessor to convert a preprocessable Fortran 77 or Ratfor
source file into a strict Fortran 77 source file.  The precise command
used is as follows:

`.F'
     `$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
     $(AM_FFLAGS) $(FFLAGS)'

`.r'
     `$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)'

Compiling Fortran 77 Files
--------------------------

   `N.o' is made automatically from `N.f', `N.F' or `N.r' by running
the Fortran 77 compiler.  The precise command used is as follows:

`.f'
     `$(F77) -c $(AM_FFLAGS) $(FFLAGS)'

`.F'
     `$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
     $(AM_FFLAGS) $(FFLAGS)'

`.r'
     `$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)'

Mixing Fortran 77 With C and C++
--------------------------------

   Automake currently provides _limited_ support for creating programs
and shared libraries that are a mixture of Fortran 77 and C and/or C++.
However, there are many other issues related to mixing Fortran 77 with
other languages that are _not_ (currently) handled by Automake, but
that are handled by other packages(1).

   Automake can help in two ways:

  1. Automatic selection of the linker depending on which combinations
     of source code.

  2. Automatic selection of the appropriate linker flags (e.g. `-L' and
     `-l') to pass to the automatically selected linker in order to link
     in the appropriate Fortran 77 intrinsic and run-time libraries.

     These extra Fortran 77 linker flags are supplied in the output
     variable `FLIBS' by the `AC_F77_LIBRARY_LDFLAGS' Autoconf macro
     supplied with newer versions of Autoconf (Autoconf version 2.13 and
     later).  See Fortran 77 Compiler Characteristics (autoconf).

   If Automake detects that a program or shared library (as mentioned in
some `_PROGRAMS' or `_LTLIBRARIES' primary) contains source code that
is a mixture of Fortran 77 and C and/or C++, then it requires that the
macro `AC_F77_LIBRARY_LDFLAGS' be called in `configure.in', and that
either `$(FLIBS)' or `@FLIBS@' appear in the appropriate `_LDADD' (for
programs) or `_LIBADD' (for shared libraries) variables.  It is the
responsibility of the person writing the `Makefile.am' to make sure
that `$(FLIBS)' or `@FLIBS@' appears in the appropriate `_LDADD' or
`_LIBADD' variable.

   For example, consider the following `Makefile.am':

     bin_PROGRAMS = foo
     foo_SOURCES  = main.cc foo.f
     foo_LDADD    = libfoo.la @FLIBS@

     pkglib_LTLIBRARIES = libfoo.la
     libfoo_la_SOURCES  = bar.f baz.c zardoz.cc
     libfoo_la_LIBADD   = $(FLIBS)

   In this case, Automake will insist that `AC_F77_LIBRARY_LDFLAGS' is
mentioned in `configure.in'.  Also, if `@FLIBS@' hadn't been mentioned
in `foo_LDADD' and `libfoo_la_LIBADD', then Automake would have issued
a warning.

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

   (1) For example, the cfortran package
(http://www-zeus.desy.de/~burow/cfortran/) addresses all of these
inter-language issues, and runs under nearly all Fortran 77, C and C++
compilers on nearly all platforms.  However, `cfortran' is not yet Free
Software, but it will be in the next major release.

How the Linker is Chosen
........................

   The following diagram demonstrates under what conditions a particular
linker is chosen by Automake.

   For example, if Fortran 77, C and C++ source code were to be compiled
into a program, then the C++ linker will be used.  In this case, if the
C or Fortran 77 linkers required any special libraries that weren't
included by the C++ linker, then they must be manually added to an
`_LDADD' or `_LIBADD' variable by the user writing the `Makefile.am'.

                          \              Linker
               source      \
                code        \     C        C++     Fortran
          -----------------  +---------+---------+---------+
                             |         |         |         |
          C                  |    x    |         |         |
                             |         |         |         |
                             +---------+---------+---------+
                             |         |         |         |
              C++            |         |    x    |         |
                             |         |         |         |
                             +---------+---------+---------+
                             |         |         |         |
                    Fortran  |         |         |    x    |
                             |         |         |         |
                             +---------+---------+---------+
                             |         |         |         |
          C + C++            |         |    x    |         |
                             |         |         |         |
                             +---------+---------+---------+
                             |         |         |         |
          C +       Fortran  |         |         |    x    |
                             |         |         |         |
                             +---------+---------+---------+
                             |         |         |         |
              C++ + Fortran  |         |    x    |         |
                             |         |         |         |
                             +---------+---------+---------+
                             |         |         |         |
          C + C++ + Fortran  |         |    x    |         |
                             |         |         |         |
                             +---------+---------+---------+

Fortran 77 and Autoconf
-----------------------

   The current Automake support for Fortran 77 requires a recent enough
version of Autoconf that also includes support for Fortran 77.  Full
Fortran 77 support was added to Autoconf 2.13, so you will want to use
that version of Autoconf or later.

Java Support
============

   Automake includes support for compiled Java, using `gcj', the Java
front end to the GNU Compiler Collection.

   Any package including Java code to be compiled must define the output
variable `GCJ' in `configure.in'; the variable `GCJFLAGS' must also be
defined somehow (either in `configure.in' or `Makefile.am').  The
simplest way to do this is to use the `AM_PROG_GCJ' macro.

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

   As always, the contents of `AM_GCJFLAGS' are passed to every
compilation invoking `gcj' (in its role as an ahead-of-time compiler -
when invoking it to create `.class' files, `AM_JAVACFLAGS' is used
instead).  If it is necessary to pass options to `gcj' from
`Makefile.am', this variable, and not the user variable `GCJFLAGS',
should be used.

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

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

Support for Other Languages
===========================

   Automake currently only includes full support for C, C++ (see C++ Support),
Fortran 77 (see Fortran 77 Support), and Java (see
Java Support).  There is only rudimentary support for other
languages, support for which will be improved based on user demand.

   Some limited support for adding your own languages is available via
the suffix rule handling; see Suffixes.

Automatic de-ANSI-fication
==========================

   Although the GNU standards allow the use of ANSI C, this can have the
effect of limiting portability of a package to some older compilers
(notably the SunOS C compiler).

   Automake allows you to work around this problem on such machines by
"de-ANSI-fying" each source file before the actual compilation takes
place.

   If the `Makefile.am' variable `AUTOMAKE_OPTIONS' (see Options)
contains the option `ansi2knr' then code to handle de-ANSI-fication is
inserted into the generated `Makefile.in'.

   This causes each C source file in the directory to be treated as
ANSI C.  If an ANSI C compiler is available, it is used.  If no ANSI C
compiler is available, the `ansi2knr' program is used to convert the
source files into K&R C, which is then compiled.

   The `ansi2knr' program is simple-minded.  It assumes the source code
will be formatted in a particular way; see the `ansi2knr' man page for
details.

   Support for de-ANSI-fication requires the source files `ansi2knr.c'
and `ansi2knr.1' to be in the same package as the ANSI C source; these
files are distributed with Automake.  Also, the package `configure.in'
must call the macro `AM_C_PROTOTYPES' (see Macros).

   Automake also handles finding the `ansi2knr' support files in some
other directory in the current package.  This is done by prepending the
relative path to the appropriate directory to the `ansi2knr' option.
For instance, suppose the package has ANSI C code in the `src' and
`lib' subdirs.  The files `ansi2knr.c' and `ansi2knr.1' appear in
`lib'.  Then this could appear in `src/Makefile.am':

     AUTOMAKE_OPTIONS = ../lib/ansi2knr

   If no directory prefix is given, the files are assumed to be in the
current directory.

   Note that automatic de-ANSI-fication will not work when the package
is being built for a different host architecture.  That is because
automake currently has no way to build `ansi2knr' for the build machine.

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

Automatic dependency tracking
=============================

   As a developer it is often painful to continually update the
`Makefile.in' whenever the include-file dependencies change in a
project.  Automake supplies a way to automatically track dependency
changes.

   Automake always uses complete dependencies for a compilation,
including system headers.  Automake's model is that dependency
computation should be a side effect of the build.  To this end,
dependencies are computed by running all compilations through a special
wrapper program called `depcomp'.  `depcomp' understands how to coax
many different C and C++ compilers into generating dependency
information in the format it requires.  `automake -a' will install
`depcomp' into your source tree for you.  If `depcomp' can't figure out
how to properly invoke your compiler, dependency tracking will simply
be disabled for your build.

   Experience with earlier versions of Automake (1) taught us that it
is not reliable to generate dependencies only on the maintainer's
system, as configurations vary too much.  So instead Automake
implements dependency tracking at build time.

   Automatic dependency tracking can be suppressed by putting
`no-dependencies' in the variable `AUTOMAKE_OPTIONS', or passing
`no-dependencies' as an argument to `AM_INIT_AUTOMAKE' (this should be
the prefered way).  Or, you can invoke `automake' with the `-i' option.
Dependency tracking is enabled by default.

   The person building your package also can choose to disable
dependency tracking by configuring with `--disable-dependency-tracking'.

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

   (1) See `http://sources.redhat.com/automake/dependencies.html' for
more information on the history and experiences with automatic
dependency tracking in Automake

Support for executable extensions
=================================

   On some platforms, such as Windows, executables are expected to have
an extension such as `.exe'.  On these platforms, some compilers (GCC
among them) will automatically generate `foo.exe' when asked to
generate `foo'.

   Automake provides mostly-transparent support for this.  Unfortunately
_mostly_ doesn't yet mean _fully_.  Until the English dictionary is
revised, you will have to assist Automake if your package must support
those platforms.

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

     bin_PROGRAMS = liver

   to this:

     bin_PROGRAMS = liver$(EXEEXT)

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

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

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

   Sometimes maintainers like to write an explicit link rule for their
program.  Without executable extension support, this is easy--you
simply write a target with the same name as the program.  However, when
executable extension support is enabled, you must instead add the
`$(EXEEXT)' suffix.

   Unfortunately, due to the change in Autoconf 2.50, this means you
must always add this extension.  However, this is a problem for
maintainers who know their package will never run on a platform that
has executable extensions.  For those maintainers, the `no-exeext'
option (see Options) will disable this feature.  This works in a
fairly ugly way; if `no-exeext' is seen, then the presence of a target
named `foo' in `Makefile.am' will override an automake-generated target
of the form `foo$(EXEEXT)'.  Without the `no-exeext' option, this use
will give an error.

Other Derived Objects
*********************

   Automake can handle derived objects which are not C programs.
Sometimes the support for actually building such objects must be
explicitly supplied, but Automake will still automatically handle
installation and distribution.

Executable Scripts
==================

   It is possible to define and install programs which are scripts.
Such programs are listed using the `SCRIPTS' primary name.  Automake
doesn't define any dependencies for scripts; the `Makefile.am' should
include the appropriate rules.

   Automake does not assume that scripts are derived objects; such
objects must be deleted by hand (see Clean).

   The `automake' program itself is a Perl script that is generated at
configure time from `automake.in'.  Here is how this is handled:

     bin_SCRIPTS = automake

   Since `automake' appears in the `AC_OUTPUT' macro, a target for it
is automatically generated, and it is also automatically cleaned
(despite the fact it's a script).

   Script objects can be installed in `bindir', `sbindir',
`libexecdir', or `pkgdatadir'.

   Scripts that need not being installed can be listed in
`noinst_SCRIPTS', and among them, those which are needed only by `make
check' should go in `check_SCRIPTS'.

Header files
============

   Header files are specified by the `HEADERS' family of variables.
Generally header files are not installed, so the `noinst_HEADERS'
variable will be the most used.  (1)

   All header files must be listed somewhere; missing ones will not
appear in the distribution.  Often it is clearest to list uninstalled
headers with the rest of the sources for a program.  See A Program.
Headers listed in a `_SOURCES' variable need not be listed in any
`_HEADERS' variable.

   Headers can be installed in `includedir', `oldincludedir', or
`pkgincludedir'.

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

   (1) However, for the case of a non-installed header file that is
actually used by a particular program, we recommend listing it in the
program's `_SOURCES' variable instead of in `noinst_HEADERS'.  We
believe this is more clear.

Architecture-independent data files
===================================

   Automake supports the installation of miscellaneous data files using
the `DATA' family of variables.

   Such data can be installed in the directories `datadir',
`sysconfdir', `sharedstatedir', `localstatedir', or `pkgdatadir'.

   By default, data files are _not_ included in a distribution.  Of
course, you can use the `dist_' prefix to change this on a per-variable
basis.

   Here is how Automake declares its auxiliary data files:

     dist_pkgdata_DATA = clean-kr.am clean.am ...

Built sources
=============

   Because Automake's automatic dependency tracking works as a
side-effect of compilation (see Dependencies) there is a bootstrap
issue: a target should not be compiled before its dependencies are
made, but these dependencies are unknown until the target is first
compiled.

   Ordinarily this is not a problem, because dependencies are
distributed sources: they preexist and do not need to be built.
Suppose that `foo.c' includes `foo.h'.  When it first compiles `foo.o',
`make' only knows that `foo.o' depends on `foo.c'.  As a side-effect of
this compilation `depcomp' records the `foo.h' dependency so that
following invocations of `make' will honor it.  In these conditions,
it's clear there is no problem: either `foo.o' doesn't exist and has to
be built (regardless of the dependencies), either accurate dependencies
exist and they can be used to decide whether `foo.o' should be rebuilt.

   It's a different story if `foo.h' doesn't exist by the first `make'
run.  For instance there might be a rule to build `foo.h'.  This time
`file.o''s build will fail because the compiler can't find `foo.h'.
`make' failed to trigger the rule to build `foo.h' first by lack of
dependency information.

   The `BUILT_SOURCES' variable is a workaround for this problem.  A
source file listed in `BUILT_SOURCES' is made on `make all' or `make
check' before other targets are processed.  However, such a source file
is not _compiled_ unless explicitly requested by mentioning it in some
other `_SOURCES' variable.

   So, to conclude our introductory example, we could use
`BUILT_SOURCES = foo.h' to ensure `foo.h' gets built before any other
target (including `foo.o') during `make all' or `make check'.

   `BUILT_SOURCES' is actually a bit of a misnomer, as any file which
must be created early in the build process can be listed in this
variable.  Moreover, all built sources do not necessarily have to be
listed in `BUILT_SOURCES'.  For instance a generated `.c' file doesn't
need to appear in `BUILT_SOURCES' (unless it is included by another
source), because it's a known dependency of the associated object.

   It might be important to emphasize that `BUILT_SOURCES' is honored
only by `make all' and `make check'.  This means you cannot build a
specific target (e.g., `make foo') in a clean tree if it depends on a
built source.  However it will succeed if you have run `make all'
earlier, because accurate dependencies are already available.

   The next section illustrates and discusses the handling of built
sources on a toy example.

Built sources example
---------------------

   Suppose that `foo.c' includes `bindir.h', which is
installation-dependent and not distributed: it needs to be built.  Here
`bindir.h' defines the preprocessor macro `bindir' to the value of the
`make' variable `bindir' (inherited from `configure').

   We suggest several implementations below.  It's not meant to be an
exhaustive listing of all ways to handle built sources, but it will give
you a few ideas if you encounter this issue.

First try
---------

   This first implementation will illustrate the bootstrap issue
mentioned in the previous section (see Sources).

   Here is a tentative `Makefile.am'.

     # This won't work.
     bin_PROGRAMS = foo
     foo_SOURCES = foo.c
     nodist_foo_SOURCES = bindir.h
     CLEANFILES = bindir.h
     bindir.h: Makefile
             echo '#define bindir "$(bindir)"' >$@

   This setup doesn't work, because Automake doesn't know that `foo.c'
includes `bindir.h'.  Remember, automatic dependency tracking works as
a side-effect of compilation, so the dependencies of `foo.o' will be
known only after `foo.o' has been compiled (see Dependencies).  The
symptom is as follows.

     % make
     source='foo.c' object='foo.o' libtool=no \
     depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
     depmode=gcc /bin/sh ./depcomp \
     gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
     foo.c:2: bindir.h: No such file or directory
     make: *** [foo.o] Error 1

Using `BUILT_SOURCES'
---------------------

   A solution is to require `bindir.h' to be built before anything
else.  This is what `BUILT_SOURCES' is meant for (see Sources).

     bin_PROGRAMS = foo
     foo_SOURCES = foo.c
     BUILT_SOURCES = bindir.h
     CLEANFILES = bindir.h
     bindir.h: Makefile
             echo '#define bindir "$(bindir)"' >$@

   See how `bindir.h' get built first:

     % make
     echo '#define bindir "/usr/local/bin"' >bindir.h
     make  all-am
     make[1]: Entering directory `/home/adl/tmp'
     source='foo.c' object='foo.o' libtool=no \
     depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
     depmode=gcc /bin/sh ./depcomp \
     gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
     gcc  -g -O2   -o foo  foo.o
     make[1]: Leaving directory `/home/adl/tmp'

   However, as said earlier, `BUILT_SOURCES' applies only to the `all'
and `check' targets.  It still fails if you try to run `make foo'
explicitly:

     % make clean
     test -z "bindir.h" || rm -f bindir.h
     test -z "foo" || rm -f foo
     rm -f *.o core *.core
     % : > .deps/foo.Po # Suppress previously recorded dependencies
     % make foo
     source='foo.c' object='foo.o' libtool=no \
     depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
     depmode=gcc /bin/sh ./depcomp \
     gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
     foo.c:2: bindir.h: No such file or directory
     make: *** [foo.o] Error 1

Recording dependencies manually
-------------------------------

   Usually people are happy enough with `BUILT_SOURCES' because they
never run targets such as `make foo' before `make all', as in the
previous example.  However if this matters to you, you can avoid
`BUILT_SOURCES' and record such dependencies explicitly in the
`Makefile.am'.

     bin_PROGRAMS = foo
     foo_SOURCES = foo.c
     foo.$(OBJEXT): bindir.h
     CLEANFILES = bindir.h
     bindir.h: Makefile
             echo '#define bindir "$(bindir)"' >$@

   You don't have to list _all_ the dependencies of `foo.o' explicitly,
only those which might need to be built.  If a dependency already
exists, it will not hinder the first compilation and will be recorded
by the normal dependency tracking code.  (Note that after this first
compilation the dependency tracking code will also have recorded the
dependency between `foo.o' and `bindir.h'; so our explicit dependency
is really useful to the first build only.)

   Adding explicit dependencies like this can be a bit dangerous if you
are not careful enough.  This is due to the way Automake tries not to
overwrite your rules (it assumes you know better than it).
`foo.$(OBJEXT): bindir.h' supersedes any rule Automake may want to
output to build `foo.$(OBJEXT)'.  It happens to work in this case
because Automake doesn't have to output any `foo.$(OBJEXT):' target: it
relies on a suffix rule instead (i.e., `.c.$(OBJEXT):').  Always check
the generated `Makefile.in' if you do this.

Build `bindir.h' from `configure'
---------------------------------

   It's possible to define this preprocessor macro from `configure',
either in `config.h' (see Defining Directories (autoconf)),
or by processing a `bindir.h.in' file using
`AC_CONFIG_FILES' (see Configuration Actions (autoconf)).

   At this point it should be clear that building `bindir.h' from
`configure' work well for this example.  `bindir.h' will exist before
you build any target, hence will not cause any dependency issue.

   The Makefile can be shrunk as follows.  We do not even have to
mention `bindir.h'.

     bin_PROGRAMS = foo
     foo_SOURCES = foo.c

   However, it's not always possible to build sources from `configure',
especially when these sources are generated by a tool that needs to be
built first...

Build `bindir.c', not `bindir.h'.
---------------------------------

   Another attractive idea is to define `bindir' as a variable or
function exported from `bindir.o', and build `bindir.c' instead of
`bindir.h'.

     noinst_PROGRAMS = foo
     foo_SOURCES = foo.c bindir.h
     nodist_foo_SOURCES = bindir.c
     CLEANFILES = bindir.c
     bindir.c: Makefile
             echo 'const char bindir[] = "$(bindir)";' >$

   `bindir.h' contains just the variable's declaration and doesn't need
to be built, so it won't cause any trouble.  `bindir.o' is always
dependent on `bindir.c', so `bindir.c' will get built first.

Which is best?
--------------

   There is no panacea, of course.  Each solution has its merits and
drawbacks.

   You cannot use `BUILT_SOURCES' if the ability to run `make foo' on a
clean tree is important to you.

   You won't add explicit dependencies if you are leery of overriding
an Automake target by mistake.

   Building files from `./configure' is not always possible, neither is
converting `.h' files into `.c' files.

Other GNU Tools
***************

   Since Automake is primarily intended to generate `Makefile.in's for
use in GNU programs, it tries hard to interoperate with other GNU tools.

Emacs Lisp
==========

   Automake provides some support for Emacs Lisp.  The `LISP' primary
is used to hold a list of `.el' files.  Possible prefixes for this
primary are `lisp_' and `noinst_'.  Note that if `lisp_LISP' is
defined, then `configure.in' must run `AM_PATH_LISPDIR' (see
Macros).

   By default Automake will byte-compile all Emacs Lisp source files
using the Emacs found by `AM_PATH_LISPDIR'.  If you wish to avoid
byte-compiling, simply define the variable `ELCFILES' to be empty.
Byte-compiled Emacs Lisp files are not portable among all versions of
Emacs, so it makes sense to turn this off if you expect sites to have
more than one version of Emacs installed.  Furthermore, many packages
don't actually benefit from byte-compilation.  Still, we recommend that
you leave it enabled by default.  It is probably better for sites with
strange setups to cope for themselves than to make the installation less
nice for everybody else.

Gettext
=======

   If `AM_GNU_GETTEXT' is seen in `configure.in', then Automake turns
on support for GNU gettext, a message catalog system for
internationalization (see GNU Gettext (gettext)).

   The `gettext' support in Automake requires the addition of two
subdirectories to the package, `intl' and `po'.  Automake insures that
these directories exist and are mentioned in `SUBDIRS'.

Libtool
=======

   Automake provides support for GNU Libtool (see Introduction (libtool))
with the `LTLIBRARIES' primary.  See A Shared Library.

Java
====

   Automake provides some minimal support for Java compilation with the
`JAVA' primary.

   Any `.java' files listed in a `_JAVA' variable will be compiled with
`JAVAC' at build time.  By default, `.class' files are not included in
the distribution.

   Currently Automake enforces the restriction that only one `_JAVA'
primary can be used in a given `Makefile.am'.  The reason for this
restriction is that, in general, it isn't possible to know which
`.class' files were generated from which `.java' files - so it would be
impossible to know which files to install where.  For instance, a
`.java' file can define multiple classes; the resulting `.class' file
names cannot be predicted without parsing the `.java' file.

   There are a few variables which are used when compiling Java sources:

`JAVAC'
     The name of the Java compiler.  This defaults to `javac'.

`JAVACFLAGS'
     The flags to pass to the compiler.  This is considered to be a user
     variable (see User Variables).

`AM_JAVACFLAGS'
     More flags to pass to the Java compiler.  This, and not
     `JAVACFLAGS', should be used when it is necessary to put Java
     compiler flags into `Makefile.am'.

`JAVAROOT'
     The value of this variable is passed to the `-d' option to
     `javac'.  It defaults to `$(top_builddir)'.

`CLASSPATH_ENV'
     This variable is an `sh' expression which is used to set the
     `CLASSPATH' environment variable on the `javac' command line.  (In
     the future we will probably handle class path setting differently.)

Python
======

   Automake provides support for Python compilation with the `PYTHON'
primary.

   Any files listed in a `_PYTHON' variable will be byte-compiled with
`py-compile' at install time.  `py-compile' actually creates both
standard (`.pyc') and byte-compiled (`.pyo') versions of the source
files.  Note that because byte-compilation occurs at install time, any
files listed in `noinst_PYTHON' will not be compiled.  Python source
files are included in the distribution by default.

   Automake ships with an Autoconf macro called `AM_PATH_PYTHON' which
will determine some Python-related directory variables (see below).  If
you have called `AM_PATH_PYTHON' from `configure.in', then you may use
the following variables to list you Python source files in your
variables: `python_PYTHON', `pkgpython_PYTHON', `pyexecdir_PYTHON',
`pkgpyexecdir_PYTHON', depending where you want your files installed.

   `AM_PATH_PYTHON' takes a single optional argument.  This argument,
if present, is the minimum version of Python which can be used for this
package.  If the version of Python found on the system is older than the
required version, then `AM_PATH_PYTHON' will cause an error.

   `AM_PATH_PYTHON' creates several output variables based on the
Python installation found during configuration.

`PYTHON'
     The name of the Python executable.

`PYTHON_VERSION'
     The Python version number, in the form MAJOR.MINOR (e.g. `1.5').
     This is currently the value of `sys.version[:3]'.

`PYTHON_PREFIX'
     The string `${prefix}'.  This term may be used in future work
     which needs the contents of Python's `sys.prefix', but general
     consensus is to always use the value from configure.

`PYTHON_EXEC_PREFIX'
     The string `${exec_prefix}'.  This term may be used in future work
     which needs the contents of Python's `sys.exec_prefix', but general
     consensus is to always use the value from configure.

`PYTHON_PLATFORM'
     The canonical name used by Python to describe the operating
     system, as given by `sys.platform'.  This value is sometimes
     needed when building Python extensions.

`pythondir'
     The directory name for the `site-packages' subdirectory of the
     standard Python install tree.

`pkgpythondir'
     This is is the directory under `pythondir' which is named after the
     package.  That is, it is `$(pythondir)/$(PACKAGE)'.  It is provided
     as a convenience.

`pyexecdir'
     This is the directory where Python extension modules (shared
     libraries) should be installed.

`pkgpyexecdir'
     This is a convenience variable which is defined as
     `$(pyexecdir)/$(PACKAGE)'.

   All these directory variables have values that start with either
`${prefix}' or `${exec_prefix}' unexpanded.  This works fine in
`Makefiles', but it makes these variables hard to use in `configure'.
This is mandated by the GNU conding standard, so that the user can run
`make prefix=/foo install'.  The Autoconf manual has a section with
more details on this topic (see Installation Directory Variables (autoconf)).

Building documentation
**********************

   Currently Automake provides support for Texinfo and man pages.

Texinfo
=======

   If the current directory contains Texinfo source, you must declare it
with the `TEXINFOS' primary.  Generally Texinfo files are converted
into info, and thus the `info_TEXINFOS' variable is most commonly used
here.  Any Texinfo source file must end in the `.texi', `.txi', or
`.texinfo' extension.  We recommend `.texi' for new manuals.

   Automake generates rules to build `.info', `.dvi', `.ps', and `.pdf'
files from your Texinfo sources.  The `.info' files are built by `make
all' and installed by `make install' (unless you use `no-installinfo',
see below).  The other files can be built on request by `make dvi',
`make ps', and `make pdf'.

   If the `.texi' file `@include's `version.texi', then that file will
be automatically generated.  The file `version.texi' defines four
Texinfo flag you can reference using `@value{EDITION}',
`@value{VERSION}', `@value{UPDATED}', and `@value{UPDATED-MONTH}'.

`EDITION'
`VERSION'
     Both of these flags hold the version number of your program.  They
     are kept separate for clarity.

`UPDATED'
     This holds the date the primary `.texi' file was last modified.

`UPDATED-MONTH'
     This holds the name of the month in which the primary `.texi' file
     was last modified.

   The `version.texi' support requires the `mdate-sh' program; this
program is supplied with Automake and automatically included when
`automake' is invoked with the `--add-missing' option.

   If you have multiple Texinfo files, and you want to use the
`version.texi' feature, then you have to have a separate version file
for each Texinfo file.  Automake will treat any include in a Texinfo
file that matches `vers*.texi' just as an automatically generated
version file.

   When an info file is rebuilt, the program named by the `MAKEINFO'
variable is used to invoke it.  If the `makeinfo' program is found on
the system then it will be used by default; otherwise `missing' will be
used instead.  The flags in the variables `MAKEINFOFLAGS' and
`AM_MAKEINFOFLAGS' will be passed to the `makeinfo' invocation; the
first of these is intended for use by the user (see User Variables)
and the second by the `Makefile.am' writer.

   Sometimes an info file actually depends on more than one `.texi'
file.  For instance, in GNU Hello, `hello.texi' includes the file
`gpl.texi'.  You can tell Automake about these dependencies using the
`TEXI_TEXINFOS' variable.  Here is how GNU Hello does it:

     info_TEXINFOS = hello.texi
     hello_TEXINFOS = gpl.texi

   By default, Automake requires the file `texinfo.tex' to appear in
the same directory as the Texinfo source.  However, if you used
`AC_CONFIG_AUX_DIR' in `configure.in' (see Finding `configure' Input (autoconf)),
then `texinfo.tex' is looked for there.  Automake
supplies `texinfo.tex' if `--add-missing' is given.

   If your package has Texinfo files in many directories, you can use
the variable `TEXINFO_TEX' to tell Automake where to find the canonical
`texinfo.tex' for your package.  The value of this variable should be
the relative path from the current `Makefile.am' to `texinfo.tex':

     TEXINFO_TEX = ../doc/texinfo.tex

   The option `no-texinfo.tex' can be used to eliminate the requirement
for `texinfo.tex'.  Use of the variable `TEXINFO_TEX' is preferable,
however, because that allows the `dvi', `ps', and `pdf' targets to
still work.

   Automake generates an `install-info' target; some people apparently
use this.  By default, info pages are installed by `make install'.
This can be prevented via the `no-installinfo' option.

Man pages
=========

   A package can also include man pages (but see the GNU standards on
this matter, see Man Pages (standards).)  Man pages are
declared using the `MANS' primary.  Generally the `man_MANS' variable
is used.  Man pages are automatically installed in the correct
subdirectory of `mandir', based on the file extension.

   File extensions such as `.1c' are handled by looking for the valid
part of the extension and using that to determine the correct
subdirectory of `mandir'.  Valid section names are the digits `0'
through `9', and the letters `l' and `n'.

   Sometimes developers prefer to name a man page something like
`foo.man' in the source, and then rename it to have the correct suffix,
e.g. `foo.1', when installing the file.  Automake also supports this
mode.  For a valid section named SECTION, there is a corresponding
directory named `manSECTIONdir', and a corresponding `_MANS' variable.
Files listed in such a variable are installed in the indicated section.
If the file already has a valid suffix, then it is installed as-is;
otherwise the file suffix is changed to match the section.

   For instance, consider this example:
     man1_MANS = rename.man thesame.1 alsothesame.1c

   In this case, `rename.man' will be renamed to `rename.1' when
installed, but the other files will keep their names.

   By default, man pages are installed by `make install'.  However,
since the GNU project does not require man pages, many maintainers do
not expend effort to keep the man pages up to date.  In these cases, the
`no-installman' option will prevent the man pages from being installed
by default.  The user can still explicitly install them via `make
install-man'.

   Here is how the man pages are handled in GNU `cpio' (which includes
both Texinfo documentation and man pages):

     man_MANS = cpio.1 mt.1
     EXTRA_DIST = $(man_MANS)

   Man pages are not currently considered to be source, because it is
not uncommon for man pages to be automatically generated.  Therefore
they are not automatically included in the distribution.  However, this
can be changed by use of the `dist_' prefix.

   The `nobase_' prefix is meaningless for man pages and is disallowed.

What Gets Installed
*******************

Basics of installation
======================

   Naturally, Automake handles the details of actually installing your
program once it has been built.  All files named by the various
primaries are automatically installed in the appropriate places when the
user runs `make install'.

   A file named in a primary is installed by copying the built file into
the appropriate directory.  The base name of the file is used when
installing.

     bin_PROGRAMS = hello subdir/goodbye

   In this example, both `hello' and `goodbye' will be installed in
`$(bindir)'.

   Sometimes it is useful to avoid the basename step at install time.
For instance, you might have a number of header files in subdirectories
of the source tree which are laid out precisely how you want to install
them.  In this situation you can use the `nobase_' prefix to suppress
the base name step.  For example:

     nobase_include_HEADERS = stdio.h sys/types.h

   Will install `stdio.h' in `$(includedir)' and `types.h' in
`$(includedir)/sys'.

The two parts of install
========================

   Automake generates separate `install-data' and `install-exec'
targets, in case the installer is installing on multiple machines which
share directory structure--these targets allow the machine-independent
parts to be installed only once.  `install-exec' installs
platform-dependent files, and `install-data' installs
platform-independent files.  The `install' target depends on both of
these targets.  While Automake tries to automatically segregate objects
into the correct category, the `Makefile.am' author is, in the end,
responsible for making sure this is done correctly.

   Variables using the standard directory prefixes `data', `info',
`man', `include', `oldinclude', `pkgdata', or `pkginclude' (e.g.
`data_DATA') are installed by `install-data'.

   Variables using the standard directory prefixes `bin', `sbin',
`libexec', `sysconf', `localstate', `lib', or `pkglib' (e.g.
`bin_PROGRAMS') are installed by `install-exec'.

   Any variable using a user-defined directory prefix with `exec' in
the name (e.g. `myexecbin_PROGRAMS' is installed by `install-exec'.
All other user-defined prefixes are installed by `install-data'.

Extending installation
======================

   It is possible to extend this mechanism by defining an
`install-exec-local' or `install-data-local' target.  If these targets
exist, they will be run at `make install' time.  These rules can do
almost anything; care is required.

   Automake also supports two install hooks, `install-exec-hook' and
`install-data-hook'.  These hooks are run after all other install rules
of the appropriate type, exec or data, have completed.  So, for
instance, it is possible to perform post-installation modifications
using an install hook.

Staged installs
===============

   Automake generates support for the `DESTDIR' variable in all install
rules.  `DESTDIR' is used during the `make install' step to relocate
install objects into a staging area.  Each object and path is prefixed
with the value of `DESTDIR' before being copied into the install area.
Here is an example of typical DESTDIR usage:

     make DESTDIR=/tmp/staging install

   This places install objects in a directory tree built under
`/tmp/staging'.  If `/gnu/bin/foo' and `/gnu/share/aclocal/foo.m4' are
to be installed, the above command would install
`/tmp/staging/gnu/bin/foo' and `/tmp/staging/gnu/share/aclocal/foo.m4'.

   This feature is commonly used to build install images and packages.
For more information, see Makefile Conventions (standards).

   Support for `DESTDIR' is implemented by coding it directly into the
install rules.  If your `Makefile.am' uses a local install rule (e.g.,
`install-exec-local') or an install hook, then you must write that code
to respect `DESTDIR'.

Rules for the user
==================

   Automake also generates an `uninstall' target, an `installdirs'
target, and an `install-strip' target.

   Automake supports `uninstall-local' and `uninstall-hook'.  There is
no notion of separate uninstalls for "exec" and "data", as these
features would not provide additional functionality.

   Note that `uninstall' is not meant as a replacement for a real
packaging tool.

What Gets Cleaned
*****************

   The GNU Makefile Standards specify a number of different clean rules.
See Standard Targets for Users (standards).

   Generally the files that can be cleaned are determined automatically
by Automake.  Of course, Automake also recognizes some variables that
can be defined to specify additional files to clean.  These variables
are `MOSTLYCLEANFILES', `CLEANFILES', `DISTCLEANFILES', and
`MAINTAINERCLEANFILES'.

   As the GNU Standards aren't always explicit as to which files should
be removed by which target, we've adopted a heuristic which we believe
was first formulated by Franc,ois Pinard:

   * If `make' built it, and it is commonly something that one would
     want to rebuild (for instance, a `.o' file), then `mostlyclean'
     should delete it.

   * Otherwise, if `make' built it, then `clean' should delete it.

   * If `configure' built it, then `distclean' should delete it

   * If the maintainer built it, then `maintainer-clean' should delete
     it.

   We recommend that you follow this same set of heuristics in your
`Makefile.am'.