     [file version.texi not included]

     START-INFO-DIR-ENTRY
     * automake: (automake).		Making Makefile.in's
     END-INFO-DIR-ENTRY

This file documents GNU automake VERSION

Copyright (C) 1995 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 VERSION.

Introduction
************

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

Typical Automake input files are simply a series of macro definitions. Automake processes these files to produce Makefile.ins which are distribution-ready.

Automake does force some structure on the package maintainer.  However, it is felt that this (minor) inconvenience is more than offset by Automake's convenience.

Making automake templates
*************************

General use of Automake
=======================

Automake is a tool for automatically generating Makefile.ins from files called Makefile.am.  The Makefile.am is basically a series of make macro definitions (with the occasional rule thrown in).  The generated Makefile.ins are compliant with the GNU Makefile standards.

There should be one Makefile.am per directory of a project (though it is possible to incorporate directories that don't use automake if necessary).

automake assumes the package in question uses autoconf.

How automake and configure interact
===================================

Automake enforces a certain amount of structure on the package maintainer.  One such item is its requirement that the configure.in for the package define the variables PACKAGE and VERSION.

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 being worked on.  We recommend that you make configure.in the only place you define the version number for your package; this makes releases simpler.

Here is an example of what to put in configure.in:

     PACKAGE=cpio
     VERSION=2.3.911
     AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
     AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
     AC_SUBST(PACKAGE)
     AC_SUBST(VERSION)

If your configure.in uses AC_CONFIG_HEADER, then in each directory you should define the CONFIG_HEADER variable to hold the name of the header.

For instance, in cpio's src/Makefile.am, we see:

     CONFIG_HEADER = ../config.h

automake also assumes that your configure script will define the variable INSTALL_SCRIPT.  Until this is incorporated in autoconf's AC_PROG_INSTALL macro, you can use this replacement instead:

     ## --------------------------------------------------------- ##
     ## Use AC_PROG_INSTALL, supplementing it with INSTALL_SCRIPT ##
     ## substitution.                                             ##
     ## --------------------------------------------------------- ##

     AC_DEFUN(fp_PROG_INSTALL,
     [AC_PROG_INSTALL
     test -z "$INSTALL_SCRIPT" && INSTALL_SCRIPT='${INSTALL} -m 755'
     AC_SUBST(INSTALL_SCRIPT)dnl
     ])

automake also assumes your configure.in calls AC_ARG_PROGRAM.

Types of directory hierarchy
============================

automake supports three kinds of directory hierarcy: ``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, although it does not presently use automake).  The top level Makefile.am for a deep package will contain a SUBDIRS macro, but no other macros to define objects which are built. Typically, PROGRAMS is defined in src/Makefile.am.

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

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 expected to contain Makefile.ams; only Makefiles (after configuration).  This allows inclusion of libraries from packages which do not use automake (such as gettext).

If SUBDIRS is defined, then your configure.in must include AC_PROG_MAKE_SET.

FIXME supply complete list of recursive targets?

The uniform naming scheme
=========================

Automake uses a uniform naming scheme to make it easy to decide how programs are built, and how they are installed.  This scheme also supports configure-time determination of what should be built.

There are certain variables which are used at make time to determine which objects are to be built.  For instance, PROGRAMS holds a list of programs which are to be compiled and linked.  These variables are called ``primary'' variables.

A different set of variables are 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 (FIXME xref).  automake extends this list with pkglibdir, pkgincludedir, and pkgdatadir; these are the same as the non-pkg versions, but with @PACKAGE@ appended.

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:

     PROGRAMS = @PROGRAMS@
     bin_PROGRAMS = cpio pax
     sbin_PROGRAMS = rmt mt

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.

The special prefix noinst indicates that the objects in question should not be installed at all.

Possible primary names are PROGRAMS, LIBRARIES, SCRIPTS, DATA, and HEADERS.

FIXME currently TEXINFOS and MANS don't follow this rule, but they probably should.

Which Programs Are Built
========================

In a directory containing source that gets built into a program (as opposed to a library), the PROGRAMS variable is used:

     PROGRAMS = hello

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

     hello_SOURCE = hello.c

This causes hello.o to be built from hello.c at compile time, and then linked into hello.

Multiple programs can be built in a single directory -- simply list them all in the PROGRAMS definition.  Multiple programs can share a single source file.  The source file must be listed in each ``_SOURCE'' definition.

Sometimes it is useful to determine the programs that are to be built at configure time.  For instance, GNU cpio only builts 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 trivially by making the PROGRAMS variable determined at configure time, and letting automake look in the install variables for the static list of 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 PROGRAMS 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.  Thus:

     LDADD = ../lib/libcpio.a @INTLLIBS@
     rmt_LDADD =

Programs Which are Scripts
==========================

It is possible to define and install programs which are scripts.  Such programs should be listed in the SCRIPTS variable. automake doesn't define any dependencies for scripts; the Makefile.am should include the appropriate rules.

automake does assume that objects listed in the SCRIPTS macro are derived objects; such objects are deleted by make clean.

automake itself is a script that is generated at configure time from automake.in.  Here is how this is handled:

     bin_SCRIPTS = automake

     automake: automake.in
     	CONFIG_FILES=$@ CONFIG_HEADERS= ./config.status

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

Building Libraries
==================

The LIBRARIES variable holds the names of libraries to be built in the current directory.  If the libraries to be built vary at configure time, you may define AM_LIBRARIES to supply automake with the full static list of possible libraries.

For a given library zot, the sources are taken to be in zot_SOURCES, just as for programs.  Note that libraries and programs share one namespace in automake: one directory cannot contain both a library (``liblob.a'') and a program (``lob'') with the same name.

Here is how the libcpio.a library is built in the GNU cpio distribution's lib subdirectory:

     noinst_LIBRARIES = cpio
     cpio_SOURCES = dirname.c dstring.c error.c filemode.c \
     getopt.c getopt1.c idcache.c makepath.c octal.c \
     stpcpy.c stripslash.c userspec.c xmalloc.c xstrdup.c

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:

     cpio_LIBADD = @LIBOBJS@ @ALLOCA@

Library objects can be installed in libdir or pkglibdir.

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.

All header files must be listed somewhere; missing ones will not appear in the distribution.

You can also put conditionally compiled source file names into a HEADERS variable.  (This will probably change in a future release).

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.

All such data files are included in the distribution.  (FIXME, this is probably a bug)

Here is how autoconf installs its auxiliary data files:

     pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
     compile.am data.am depend.am dist-subd-top.am dist-subd-vars.am \
     dist-subd.am dist-vars.am dist.am footer.am header-vars.am header.am \
     libscripts.am libprograms.am libraries-vars.am libraries.am library.am \
     mans-vars.am mans.am packagedata.am program.am programs.am remake-hdr.am \
     remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
     texinfos-vars.am texinfos.am hack-make.sed nl-remove.sed

Texinfo and Man Pages
=====================

Texinfo
-------

If the current directory contains Texinfo source, you must declare it with the TEXINFOS macro. Note that any Texinfo source file must end in the .texi extension (.texinfo won't work).

If the .texi file ``@include''s version.texi, then that file will be automatically generated.  version.texi defines three Texinfo macros you can reference: EDITION, VERSION, and UPDATED.  The first two hold the version number of your package (but are kept separate for clarity); the last is the date the primary file was last modified. The version.texi support requires a version of date that accepts the -r (read time from a file) option.

Sometimes an info file actually depends on more than one .texi file.  For instance, in the xdvik distribution, kpathsea.texi includes the files install.texi, copying.texi, and freedom.texi.  You can tell automake about these dependencies using the texi_TEXINFOS variable.  Here is how xdvik could do it:

     TEXINFOS = kpathsea.texi
     kpathsea_TEXINFOS = install.texi copying.texi freedom.texi

automake might be modified to detect these dependencies automatically.

Currently automake can only handle one primary .texi file. This restriction will be lifted if it proves too onerous.

automake will warn if a directory containing Texinfo source does not also contain the file texinfo.tex.  (I'm not sure if this is a good rule or not.  Comments?)

Man pages
---------

A package can also include man pages.  (Though see the GNU standards on this matter.  FIXME xref). Man pages are declared using the MANS macro.

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

     TEXINFOS = cpio.texi
     MANS = cpio.1 mt.1

Texinfo source, info pages and man pages are all considered to be ``source'' for the purposes of making a distribution.

Automatic de-ANSI-fication of Source
====================================

If the AUTOMAKE_OPTIONS variable contains the ansi2knr option, then code to handle automatic de-ANSI-fication is included in the generated Makefile.in.  This will also happen if Makefile.am includes the text @kr@, but this use is deprecated and will go away eventually.

This means that each C source file will be treated as ANSI C.  If no ANSI C compiler is available on the build system, then the code will be turned into K&R C before compilation.

Each directory that uses automatic de-ANSI-fication must include the source files ansi2knr.c and ansi2knr.1.  Also, your configure script must define the variables U and ANSI2KNR.  Here is a snippet you can add to aclocal.m4 to achieve this:

     ## ------------------------------- ##
     ## Check for function prototypes.  ##
     ## ------------------------------- ##

     AC_DEFUN(fp_C_PROTOTYPES,
     [AC_REQUIRE([fp_PROG_CC_STDC])
     AC_MSG_CHECKING([for function prototypes])
     if test "$ac_cv_prog_cc_stdc" != no; then
       AC_MSG_RESULT(yes)
       AC_DEFINE(PROTOTYPES)
       U= ANSI2KNR=
     else
       AC_MSG_RESULT(no)
       U=_ ANSI2KNR=./ansi2knr
     fi
     AC_SUBST(U)dnl
     AC_SUBST(ANSI2KNR)dnl
     ])

     ## ----------------------------------------- ##
     ## ANSIfy the C compiler whenever possible.  ##
     ## ----------------------------------------- ##

     # @defmac AC_PROG_CC_STDC
     # @maindex PROG_CC_STDC
     # @ovindex CC
     # If the C compiler in not in ANSI C mode by default, try to add an option
     # to output variable @code{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 @code{__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
     # @code{ac_cv_prog_cc_stdc} is set to @samp{no}.  If you wrote your source
     # code in ANSI C, you can make an un-ANSIfied copy of it by using the
     # program @code{ansi2knr}, which comes with Ghostscript.
     # @end defmac

     AC_DEFUN(fp_PROG_CC_STDC,
     [AC_MSG_CHECKING(for ${CC-cc} option to accept ANSI C)
     AC_CACHE_VAL(ac_cv_prog_cc_stdc,
     [ac_cv_prog_cc_stdc=no
     ac_save_CFLAGS="$CFLAGS"
     # Don't try gcc -ansi; that turns off useful extensions and
     # breaks some systems' header files.
     # AIX			-qlanglvl=ansi
     # Ultrix and OSF/1	-std1
     # HP-UX			-Aa -D_HPUX_SOURCE
     # SVR4			-Xc
     for ac_arg in "" -qlanglvl=ansi -std1 "-Aa -D_HPUX_SOURCE" -Xc
     do
       CFLAGS="$ac_save_CFLAGS $ac_arg"
       AC_TRY_COMPILE(
     [#if !defined(__STDC__) || __STDC__ != 1
     choke me
     #endif
     ], [int test (int i, double x);
     struct s1 {int (*f) (int a);};
     struct s2 {int (*f) (double a);};],
     [ac_cv_prog_cc_stdc="$ac_arg"; break])
     done
     CFLAGS="$ac_save_CFLAGS"
     ])
     AC_MSG_RESULT($ac_cv_prog_cc_stdc)
     case "x$ac_cv_prog_cc_stdc" in
       x|xno) ;;
       *) CC="$CC $ac_cv_prog_cc_stdc" ;;
     esac
     ])

What Gets Installed
===================

Naturally, automake handles the details of actually installing your program once it has been built.  All PROGRAMS, SCRIPTS, LIBRARIES, DATA and HEADERS are automatically installed in the appropriate places.

automake also handles installing any specified info and man pages.

FIXME xref to Extending node here; sometimes you need to install more.

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.

automake also generates an uninstall target, and an installdirs target.

Clean targets
=============

The GNU Makefile Standards specify a number of different clean rules. Generally the files that can 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.

Building a Release
==================

The dist target in the generated Makefile.in can be used to generate a gzip'd tar file for distribution.  The tar file is named based on the PACKAGE and VERSION variables.

For the most part, the files to distribute are automatically found by automake: all source files are automatically included in a distribution, as are all Makefile.ams and Makefile.ins. automake also has a built-in list of commonly used files which, if present in the current directory, are automatically included.  This list is printed by automake --help.

Still, sometimes there are files which must be distributed, but which are not covered in the automatic rules.  These files should be listed in the DIST_OTHER variable.

For instance, in the automake distribution, automake.in (the source to automake) is not found automatically.  So in the Makefile.am, we have:

     DIST_OTHER = automake.in

FIXME: describe DIST_SUBDIRS or not?  It is a hack which might go away.

Interfacing to etags
====================

automake will generate rules to generate TAGS files for use with GNU Emacs under some circumstances.

If any C source code or headers are present, then a TAGS file will be generated for the directory.

At the topmost directory of a multi-directory package, a TAGS file will be generated that will include by reference all TAGS files from subdirectories.

Also, if the variable ETAGS_ARGS is defined, a TAGS file will be generated.  This variable is intended for use in directories which contain taggable source that etags does not understand.

Here is how automake generates tags for its source, and for nodes in its Texinfo file:

     ETAGS_ARGS = automake.in --lang=none \
      --regex='/^@node[ \t]+\([^,]+\)/\1/' automake.texi

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, and distribute the dependencies in the generated Makefile.in.

Currently this support requires the use of GNU make and gcc.  It might become possible in the future to supply a different dependency generating program, if there is enough demand.

This mode is enabled by default if any C program or library is defined in the current directory.

When you decide to make a distribution, the dist target will re-run automake with the --include-deps option.  This causes the previously generated dependencies to be inserted into the generated Makefile.in, and thus into the distribution. --include-deps also turns off inclusion of the dependency generation code.

There should probably be a way to suppress this mode.

Setting options
===============

Various features of Automake can be controlled by options in the Makefile.am.  Such options are listed in a special variable named AUTOMAKE_OPTIONS.  Currently understood options are:

gnits

gnu

normal
     The same as the corresponding --strictness option.

no-installman
     The generated Makefile.in will not cause man pages to be installed by default.  However, an install-man target will still be available for optional installation.

ansi2knr
     Turn on automatic de-ANSI-fication.

dist-shar
     Generate a dist-shar target as well as the ordinary dist target.

When Automake Isn't Enough
==========================

Sometimes automake isn't enough.  Then you just lose.

Actually, automakes implicit copying semantics means that many problems can be worked around by simply adding some make targets and rules to Makefile.in.  automake will ignore these additions.

There are some caveats to doing this.  You can't overload a target already used by automake.  However, various useful targets have a ``-local'' version you can specify in your Makefile.in.

The targets that support a local version are all, info, dvi, check, install-data, install-exec, and uninstall.

For instance, here is how to install a file in /etc:

     install-data-local:
             $(INSTALL_DATA) $(srcdir)/afile /etc/afile

Using automake to Create Makefile.in
************************************

There are basically two modes in which automake can be run.

In the first, most common, mode, automake is simply run without any arguments.  It will determine which Makefile.ams exist by looking in the current directory and immediate subdirectories, and will automatically build Makefile.ins in these directories.

In the second mode, automake is run with the name of one or more Makefiles as arguments.  It then rebuilds the corresponding Makefile.ins from the (also) corresponding Makefile.ams. This second mode is most often used by make itself, when it notices that a Makefile.in is out of date.

Distributing Makefile.ins
*************************

Automake places no restrictions on the distribution of the resulting Makefile.ins.  We still encourage software authors to distribute their work under terms like those of the GPL, but doing so is not required to use Automake.

Some of the files that can be automatically installed via the --install-missing switch do fall under the GPL; examine each file to see.

Some ideas for the future
*************************

Here are some things that might happen in the future:

  * Better error checking would be good.

Nothing yet
***********