automake.texi

Branch :
Show log
Commit
Author : Tom Tromey
Date : 1996-02-12 06:27:59
Hash : 8da47dfc
Message : Can put version in AUTOMAKE_OPTIONS. Bug fixes
automake.texi
\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename automake.info
@settitle automake
@setchapternewpage off
@c %**end of header

@include version.texi

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

@ifinfo
This file documents GNU automake @value{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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph


@end ignore
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.
@end ifinfo


@titlepage
@title GNU Automake
@subtitle For version @value{VERSION}, @value{UPDATED}
@c copyright page
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995 Free Software Foundation, Inc.
@sp 2
This is the first edition of the GNU Automake documentation,@*
and is consistent with GNU Automake @value{VERSION}.@*
@sp 2
Published by the Free Software Foundation @*
675 Massachusetts Avenue, @*
Cambridge, MA 02139 USA @*

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 Free Software Foundation.
@end titlepage

@ifinfo
@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top GNU Automake

This file documents the GNU Automake package for creating GNU
Standards-compliant Makefiles from template files.  This edition
documents version @value{VERSION}.

@menu
* Introduction::                Automake's purpose
* Details::                     Creating an Automake template file
* Invoking automake::           Creating a Makefile.in
* Distributing::                Distributing generated Makefile.ins
* Future::                      Some ideas for the future.
* Some index::                  Index of variables
@end menu

@end ifinfo

@node Introduction
@chapter Introduction

The GNU Makefile Standards Document
(@pxref{Makefile Conventions, , Makefile Conventions, standards.info, 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 @file{Makefile.in}s 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.


@node Details
@chapter Making @code{automake} templates

@menu
* Generalities::                General overview
* configure::                   Automake and configure
* Depth::                       Types of package hierarchy
* Naming::                      The uniform naming scheme
* Programs::                    Building programs
* ANSI::                        Automatic de-ANSI-fication
* Scripts::                     Building scripts
* Libraries::                   Building libraries
* Headers::                     Header files
* Data::                        Data files.
* Docs::                        Specifying documentation files
* Install::                     What gets installed
* Clean::                       What gets cleaned
* Distribution::                What gets distributed
* Tags::                        TAGS files
* Dependencies::                Automatic dependency tracking
* Options::                     Setting options.
* Extending::                   If the defaults aren't enough
@end menu

@node Generalities
@section General use of Automake

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

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

@code{automake} assumes the package in question uses @code{autoconf}.


@node configure
@section How @code{automake} and @code{configure} interact

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

@var{PACKAGE} should be the name of the package as it appears when
bundled for distribution.  For instance, Automake defines @samp{PACKAGE}
to be @samp{automake}.

@var{VERSION} should be the version number of the release being worked
on.  We recommend that you make @file{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 @file{configure.in}:

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

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

@example
## --------------------------------------------------------- ##
## 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
])
@end example

@code{automake} requires this macro if you install any scripts.
Otherwise only @code{AC_PROG_INSTALL} is required.

@code{automake} also assumes your @file{configure.in} calls
@samp{AC_ARG_PROGRAM}.


@node Depth
@section Types of directory hierarchy

@code{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 @file{Makefile.am} for such a package by definition lacks a
@samp{SUBDIRS} macro.  An example of such a package is @code{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 @code{tar}, although
it does not presently use @code{automake}).  The top level
@file{Makefile.am} for a deep package will contain a @samp{SUBDIRS}
macro, but no other macros to define objects which are built.
Typically, @samp{PROGRAMS} is defined in @file{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.  @code{automake} is one such package (as is GNU
@code{make}, which does not currently use @code{automake}).


The @samp{SUBDIRS} macro holds a list of subdirectories in which
building of various sorts can occur.  Many targets (eg @samp{all}) in
the generated @file{Makefile} will run both locally and in all specified
subdirectories.  Note that the directories listed in @samp{SUBDIRS} are
not required to contain @file{Makefile.am}s; only @file{Makefile}s
(after configuration).  This allows inclusion of libraries from packages
which do not use @code{automake} (such as @code{gettext}).

If @samp{SUBDIRS} is defined, then your @file{configure.in} must include
@code{AC_PROG_MAKE_SET}.

FIXME supply complete list of recursive targets?


@node Naming
@section The uniform naming scheme

@code{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 @code{configure}-time determination of what should be built.

There are certain variables which are used at @code{make} time to
determine which objects are to be built.  For instance, @samp{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).  @code{automake} extends this
list with @samp{pkglibdir}, @samp{pkgincludedir}, and @samp{pkgdatadir};
these are the same as the non-@samp{pkg} versions, but with
@code{@@PACKAGE@@} appended.

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

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

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

Not every sort of object can be installed in every directory.
@code{automake} will flag those attempts it finds in error.

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

Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
@samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
@samp{TEXINFOS}.


@node Programs
@section Which Programs Are Built

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

@example
PROGRAMS = hello
@end example

In this simple case, the resulting @file{Makefile.in} will contain code
to generate a program named @code{hello}.  The variable
@samp{@var{prog}_SOURCES} is used to specify which source files get built
into an executable:

@example
hello_SOURCES = hello.c
@end example

This causes @file{hello.o} to be built from @code{hello.c} at compile
time, and then linked into @file{hello}.

If @samp{@var{prog}_SOURCES} is not specified, then it defaults to the
single file @samp{@var{prog}.c}.

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

Sometimes it is useful to determine the programs that are to be built at
configure time.  For instance, GNU @code{cpio} only builts @code{mt} and
@code{rmt} under special circumstances.

In this case, you must notify @code{Automake} of all the programs that
can possibly be built, but at the same time cause the generated
@file{Makefile.in} to use the programs specified by @code{configure}.
This is done trivially by making the @code{PROGRAMS} variable determined
at configure time, and letting @code{automake} look in the install
variables for the static list of programs.

If you need to link against libraries that are not found by
@code{configure}, you can use @samp{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
@samp{@var{prog}_LDADD} variable (where @var{PROG} is the name of the
program as it appears in @samp{PROGRAMS}) to override the global
@samp{LDADD}.  (If this variable exists for a given program, then that
program is not linked using @samp{LDADD}.)

For instance, in GNU @code{cpio}, @code{pax}, @code{cpio}, and @code{mt} are
linked against the library @file{libcpio.a}.  However, @code{rmt} is
built in the same directory, and has no such link requirement.  Thus:

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

@node Scripts
@section Programs Which are Scripts

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

@code{automake} does assume that objects listed in the @samp{SCRIPTS}
macro are derived objects; such objects are deleted by @code{make clean}.

@code{automake} itself is a script that is generated at configure time
from @file{automake.in}.  Here is how this is handled:

@example
bin_SCRIPTS = automake
@end example

FIXME xref to rebuilding things listed in AC_OUTPUT

Script objects can be installed in @samp{bindir}, @samp{sbindir}, or
@samp{libexecdir}.


@node Libraries
@section Building Libraries

The @samp{LIBRARIES} variable holds the names of libraries to be built
in the current directory.

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

Here is how the @file{libcpio.a} library is built in the GNU @code{cpio}
distribution's @file{lib} subdirectory:

@example
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
@end example

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

@example
cpio_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
@end example

Library objects can be installed in @samp{libdir} or @samp{pkglibdir}.


@node Headers
@section Header files

Header files are specified by the @samp{HEADERS} family of variables.
Generally header files are not installed, so the @samp{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
@samp{HEADERS} variable.  (This will probably change in a future
release).


@node Data
@section Architecture-independent data files

@code{automake} supports the installation of miscellaneous data files
using the @samp{DATA} family of variables.

Such data can be installed in the directories @code{datadir},
@code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
@code{pkgdatadir}.

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

Here is how @code{autoconf} installs its auxiliary data files:

@example
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
@end example


@node Docs
@section Texinfo and Man Pages

@subsection Texinfo
If the current directory contains Texinfo source, you must declare it
with the @samp{TEXINFOS} primary.  Generally Texinfo files are converted
into info, and thus the @samp{info_TEXINFOS} macro is most commonly used
here.
Note that any Texinfo source file must end in the @file{.texi} extension
(@file{.texinfo} won't work).

If the @file{.texi} file ``@@include''s @file{version.texi}, then that
file will be automatically generated.  @file{version.texi} defines three
Texinfo macros you can reference: @samp{EDITION}, @samp{VERSION}, and
@samp{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 @file{version.texi} support requires a version of @code{date} that
accepts the @samp{-r} (read time from a file) option.

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

@example
info_TEXINFOS = kpathsea.texi
kpathsea_TEXINFOS = install.texi copying.texi freedom.texi
@end example

@code{automake} might be modified to detect these dependencies
automatically.

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

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

In the future, @code{automake} will probably be modified to support
generating @samp{HTML} from Texinfo source.


@subsection 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 @samp{MANS} primary.  Generally the
@samp{man_MANS} macro is used.

By default, man pages are installed by @code{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
@samp{no-installman} option will prevent the man pages from being
installed by default.  (The user can still install them via
@code{make install-man})


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

@example
TEXINFOS = cpio.texi
MANS = cpio.1 mt.1
@end example

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


@node ANSI
@section Automatic de-ANSI-fication of Source

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

@c FIXME xref to options here.

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 @file{ansi2knr.c} and @file{ansi2knr.1}.  Also, your
@file{configure} script must define the variables @samp{U} and
@samp{ANSI2KNR}.  Here is a snippet you can add to @file{aclocal.m4} to
achieve this:

@example
## ------------------------------- ##
## 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
])
@end example


@node Install
@section What Gets Installed

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

@code{automake} also handles installing any specified info and man
pages.

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

@code{automake} generates separate @samp{install-data} and
@samp{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.

@code{automake} also generates an @samp{uninstall} target, and an
@samp{installdirs} target.


@node Clean
@section Clean targets

The GNU Makefile Standards specify a number of different clean rules.
Generally the files that can cleaned are determined automatically by
@code{automake}.  Of course, @code{automake} also recognizes some
variables that can be defined to specify additional files to clean.
These variables are @samp{MOSTLYCLEANFILES}, @samp{CLEANFILES},
@samp{DISTCLEANFILES}, and @samp{MAINTAINERCLEANFILES}.


@node Distribution
@section Building a Release

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

For the most part, the files to distribute are automatically found by
@code{automake}: all source files are automatically included in a
distribution, as are all @file{Makefile.am}s and @file{Makefile.in}s.
@code{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 @code{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 @samp{DIST_OTHER} variable.

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

@example
DIST_OTHER = automake.in
@end example

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

@node Tags
@section Interfacing to @code{etags}

@code{automake} will generate rules to generate @file{TAGS} files for
use with GNU Emacs under some circumstances.

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

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

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

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

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


@node Dependencies
@section Automatic dependency tracking

As a developer it is often painful to continually update the
@file{Makefile.in} whenever the include-file dependencies change in a
project.  @code{automake} supplies a way to automatically track
dependency changes, and distribute the dependencies in the generated
@file{Makefile.in}.

Currently this support requires the use of @code{GNU make} and
@code{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 @samp{dist} target will
re-run @code{automake} with the @samp{--include-deps} option.  This
causes the previously generated dependencies to be inserted into the
generated @file{Makefile.in}, and thus into the distribution.
@samp{--include-deps} also turns off inclusion of the dependency
generation code.

This mode can be suppressed by putting @samp{no-dependencies} in the
variable @samp{AUTOMAKE_OPTIONS}.


@node Options
@section Setting options

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

@table @samp
@item gnits
@item gnu
@item normal
The same as the corresponding @samp{--strictness} option.

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

@item ansi2knr
Turn on automatic de-ANSI-fication.

@item dist-shar
Generate a @samp{dist-shar} target as well as the ordinary @samp{dist}
target.

@item no-dependencies
This is similar to using @samp{--include-deps} on the command line, but
is useful for those situations where you don't have the necessary bits
to make automatic dependency tracking work @xref{Dependencies}.  In this
case the effect is to effectively disable automatic dependency tracking.

@item version
A version number (eg @samp{0.30}) can be specified.  If Automake is not
newer than the version specified, creation of the @file{Makefile.in}
will be suppressed.
@end table

@node Extending
@section When Automake Isn't Enough

Sometimes @code{automake} isn't enough.  Then you just lose.

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

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

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

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

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


@node Invoking automake
@chapter Using @code{automake} to Create @file{Makefile.in}

There are basically two modes in which @code{automake} can be run.

In the first, most common, mode, @code{automake} is simply run without
any arguments.  It will determine which @file{Makefile.am}s exist by
looking in the current directory and immediate subdirectories, and will
automatically build @file{Makefile.in}s in these directories.

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


@node Distributing
@chapter Distributing @file{Makefile.in}s

Automake places no restrictions on the distribution of the resulting
@file{Makefile.in}s.  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
@samp{--install-missing} switch do fall under the GPL; examine each file
to see.


@node Future
@chapter Some ideas for the future

Here are some things that might happen in the future:

@itemize @bullet
@item
Better error checking would be good.  Automake has been moving in this
direction for a while.

@item
The manual could stand updating.

@item
HTML support.

@item
The output will be cleaned up.
@end itemize

@node Some index
@chapter Nothing yet

@bye

NOTES:

* Need section on operation of automake: it reads Makefile.am and COPIES
the contents.  This section should include info on SUFFIXES, because
that is usually only needed when copying in additional targets (?)
kc3-lang/automake/automake.texi

Commit

kc3-lang/automake /automake.texi
