From: Tom Tromey Date: Fri, 17 Nov 1995 08:12:28 +0000 (+0000) Subject: Initial revision X-Git-Tag: Release-0-25~303 X-Git-Url: https://sourceware.org/git/?a=commitdiff_plain;h=168f022ec11defde1fff814ceb7d2d74946df5e5;p=automake.git Initial revision --- diff --git a/automake.texi b/automake.texi new file mode 100644 index 00000000..e007e509 --- /dev/null +++ b/automake.texi @@ -0,0 +1,264 @@ +\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. + +@menu +* Introduction:: AutoMake's purpose +* Details:: Creating an AutoMake template file +* Invoking automake:: Creating a Makefile.in +* 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 +* 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. + + +@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 +@node 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 + + +@node Source +@section Specifying Source Code + +Any header files in your distribution must be listed in the +@samp{HEADERS} variable: + +@example +HEADERS = hello.o 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. + + +@node Scripts + +La. + +@node Libraries + +La. + +@node Libstuff + +La. + +@node Docs + +Live. + +@node ANSI + +For. + +@node Distribution + +Today. + +@node Tags + +@node Extending + +Sometimes AutoMake isn't enough. Then you just lose. + + +@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 Some index + +@bye