Beginnings of switch to uniform naming scheme

[platform/upstream/automake.git] / 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
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

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
* 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
* configure::                   AutoMake and configure
* Depth::                       Types of package hierarchy
* Programs::                    What gets built
* Source::                      Specifying source files
* Scripts::                     Building scripts
* Libraries::                   Building libraries
* Libstuff::                    Programs that aren't user-visible
* Data::                        Data files.
* Docs::                        Specifying documentation files
* ANSI::                        Automatic de-ANSI-fication
* Install::                     What gets installed
* Clean::                       What gets cleaned
* Distribution::                What gets distributed
* Tags::                        TAGS files
* Dependencies::                Automatic dependency tracking
* Extending::                   If the defaults aren't enough
@end menu

@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{am}.

@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

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

For instance, in cpio's @file{src/Makefile.am}, we see:

@example
CONFIG_HEADER = ../config.h
@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} 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.  (There are not any @code{automake}-using packages
which are flat)

A deep package is one in which all the source lies in subdirectories;
the top level directory contains only configuration information.  GNU
cpio is a good example of such a package (as is GNU 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 (eg
@samp{PROGRAMS}).

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 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 expected 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 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 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}_SOURCE} is used to specify which source files get built
into an executable:

@example
hello_SOURCE = 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}.

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

Sometimes it is useful to determine the programs that are to be built at
configure time.  For instance, GNU cpio only builts @code{mt} and
@code{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
@file{Makefile.in} to use the programs specified by @code{configure}.
You can do this using the @code{AM_PROGRAMS} variable.  Here is the
relevant code from cpio:

@example
PROGRAMS = @@PROGS@@
AM_PROGRAMS = cpio pax mt rmt
@end example


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 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 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 Source
@section Specifying Source Code

Any header files in your distribution must be listed in the
@samp{HEADERS} variable.  This is used both for making distributions,
and for automatic de-ANSI-fication.

@example
HEADERS = hello.h getopt.h rx.h
@end example

@samp{HEADERS} should also be used to list any sources files which are
conditionally built.  FIXME probably should use @samp{SOURCES} for this;
that support might even work.


@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; if a script
is not to be installed as-is, the @file{Makefile.am} should include the
appropriate rules.

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

@example
SCRIPTS = automake

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


@node Libraries
@section Building Libraries

The @samp{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 @samp{AM_LIBRARIES} to supply
@code{automake} with the full static list of possible libraries.

For a given library @samp{zot}, the sources are taken to be in
@samp{@var{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 cpio
distribution's @file{lib} subdirectory:

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


@node Libstuff
@section Programs which are not User-Visible

@code{automake} allows for the automatic building and installation of
programs which are not actually used by the user, but are instead used
by other user-visible programs.  Such programs are installed in a
separate directory from user-visible programs.

For programs of this sort which are build from C source, define the
names in @samp{LIBPROGRAMS}.  For scripts, use @samp{LIBSCRIPTS}.  In
other respects, these variables are similar to @samp{PROGRAMS} and
@samp{SCRIPTS}.  Both of these variables have ``AM_'' override forms.

Here is how to generate a program named @code{goodbye}, a helper for
@code{hello}:

@example
LIBPROGRAMS = goodbye
goodbye_SOURCES = goodbye.c
@end example


@node Data
@section Architecture-independent data files

@code{automake} supports two different ways to install
architecture-independent data files.

The first variable that can be used is @samp{DATA}.  This is intended to
be used for only a small number of data files.  The files are installed
in @samp{$@{datadir@}}.

The second variable that can be used is @samp{PACKAGEDATA}.  This is
intended for a larger number of data files.  The files are installed in
@samp{$@{datadir@}/$@{PACKAGE@}}.  This variable is what @code{automake}
itself uses:

@example
PACKAGEDATA = 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

All @samp{DATA} and @samp{PACKAGEDATA} files are included in a
distribution.


@node Docs
@section Texinfo and Man Pages

@subsection Texinfo
If the current directory contains Texinfo source, you must declare it
with the @samp{TEXINFOS} macro.
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
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?)


@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} macro.


Here is how the documentation is handled in GNU 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 @file{Makefile.am} includes the text @samp{@@kr@@}, then code to
handle automatic de-ANSI-fication is included in the generated
@file{Makefile.in}.

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.  Any objects specified in
@samp{PROGRAMS}, @samp{LIBPROGRAMS}, @samp{SCRIPTS}, @samp{LIBSCRIPTS},
@samp{DATA}, and @samp{PACKAGEDATA} are automatically installed in the
appropriate place.

@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 mention files that are found automatically but not printed by
--help.
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.
(For instance, it could be set to a regexp to recognize node names in
Texinfo documentation)


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

There should probably be a way to suppress this mode.


@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}.  (Currently @samp{install} is also supported, but this
might go away)

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 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.
@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 (?)