automake.texi

Branch :
Show log
Commit
Author : Tom Tromey
Date : 1995-11-22 07:26:26
Hash : 2fb7540d
Message : *** empty log message ***
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
* Single::                      Single directory packages
* Multi::                       Multiple directory packages
* Programs::                    What gets built
* Source::                      Specifying source files
* Scripts::                     Building scripts
* Libraries::                   Building libraries
* Libstuff::                    Programs that aren't user-visible
* Docs::                        Specifying documentation files
* ANSI::                        Automatic de-ANSI-fication
* Install::                     What gets installed
* 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


@node Single
@section Single directory packages

Blah blah.

A good example of a single directory package is AutoMake itself.


@node Multi
@section Multiple directory packages

A good example of a multiple directory package is GNU cpio.

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

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

Although there appears to be support in @code{automake} to allow a
@file{Makefile.am} to specify the @samp{SOURCE} variable, it is
currently not recommended.  This support is still preliminary, and does
not work.

Eventually @code{automake} might be modified to ignore header files
listed in ``_SOURCE'' definitions.  At that time the @samp{HEADERS}
macro will go away.


@node Scripts
@section Programs Which are Scripts

La.

@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 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 Texinfo source must end in the @file{.texi} extension
(@file{.texinfo} won't work).
Currently the Texinfo support is in flux.  Some ideas which might be
implemented:

@itemize @bullet
@item
Automatic support for generating a @file{version.texi} file.  This file
conventionally holds macro definitions recording the date of the last
change to the manual, and the version number of the package.

@item
Better support for installing only the correct info files.
@end itemize

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

For.

@node Install
@section What Gets Installed

Today.

@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, there are many data
files which are distributed.  Also, @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 stamp-vti $(am_DATA)
@end example

FIXME: plan to remove the data files and make rules for this.
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 onerous 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.

In order to use this mode, when developing your package, always run
@code{automake} with the @samp{--use-deps} option.  This will cause
dependency generating code to be inserted into your @file{Makefile.in}.

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.

The interface here might change as well.  In particular, dependency
generation might become the default.


@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.  If you introduce a target whose
name is also used by @code{automake}, you should make sure it is a
double-colon target (FIXME xref make docs).

For instance, in @code{automake}, many data files are installed.
However, the code for this installation is not generated automatically,
but is instead done explicitly in @file{Makefile.am}:

@example
amdatadir = $(datadir)/automake
install:: $(am_DATA)
	$(srcdir)/mkinstalldirs $(amdatadir)
	for i in $(am_DATA); do			\
	  $(INSTALL_DATA) $(srcdir)/$$i $(amdatadir)/$$i; \
	done
@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...
kc3-lang/automake/automake.texi

Commit

kc3-lang/automake /automake.texi
