From 3acca049aec00bd777d40e7b985bb5131448766e Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Sun, 28 Sep 1997 21:51:52 +0000 Subject: [PATCH] doc update from akim --- automake.texi | 190 +++++++++++++++++++++++++++++++++----------------- stamp-vti | 2 +- version.texi | 2 +- 3 files changed, 127 insertions(+), 67 deletions(-) diff --git a/automake.texi b/automake.texi index ce6dbbbd..9e9958a2 100644 --- a/automake.texi +++ b/automake.texi @@ -115,18 +115,78 @@ documents version @value{VERSION}. * Tests:: Support for test suites * Options:: Changing Automake's behavior * Miscellaneous:: Miscellaneous rules -* Conditionals:: Conditionals +* Conditionals:: Conditionals * Gnits:: The effect of @code{--gnu} and @code{--gnits} * Cygnus:: The effect of @code{--cygnus} * Extending:: Extending Automake * Distributing:: Distributing the Makefile.in * Future:: Some ideas for the future * Index:: General index + + --- The Detailed Node Listing --- + +General ideas + +* General Operation:: General operation of Automake +* Depth:: The kinds of packages +* Strictness:: Standards conformance checking +* Uniform:: The Uniform Naming Scheme +* Canonicalization:: How derived variables are named + +Some example packages + +* Complete:: A simple example, start to finish +* Hello:: A classic program +* etags:: Building etags and ctags + +Scanning @file{configure.in} + +* Requirements:: Configuration requirements +* Optional:: Other things Automake recognizes +* Invoking aclocal:: Auto-generating aclocal.m4 +* Macros:: Autoconf macros supplied with Automake +* Extending aclocal:: Writing your own aclocal macros + +Building Programs and Libraries + +* A Program:: Building a program +* A Library:: Building a library +* LIBOBJS:: Special handling for LIBOBJS and ALLOCA +* A Shared Library:: Building a Libtool library +* Program variables:: Variables used when building a program +* Yacc and Lex:: Yacc and Lex support +* C++:: +* ANSI:: Automatic de-ANSI-fication +* Dependencies:: Automatic dependency tracking + +Other Derived Objects + +* Scripts:: Executable scripts +* Headers:: Header files +* Data:: Architecture-independent data files +* Sources:: Derived sources + +Other GNU Tools + +* Emacs Lisp:: Emacs Lisp +* gettext:: Gettext +* Guile:: Guile +* Libtool:: Libtool + +Building documentation + +* Texinfo:: Texinfo +* Man pages:: Man pages + +Miscellaneous Rules + +* Tags:: Interfacing to etags and mkid +* Suffixes:: Handling new file extensions @end menu @end ifinfo -@node Introduction +@node Introduction, Generalities, Top, Top @chapter Introduction Automake is a tool for automatically generating @file{Makefile.in}s from @@ -161,7 +221,7 @@ Mail suggestions and bug reports for Automake to @email{automake-bugs@@gnu.ai.mit.edu}. -@node Generalities +@node Generalities, Examples, Introduction, Top @chapter General ideas There are a few basic ideas that will help understand how Automake @@ -175,7 +235,7 @@ works. * Canonicalization:: How derived variables are named @end menu -@node General Operation +@node General Operation, Depth, Generalities, Generalities @section General Operation Automake works by reading a @file{Makefile.am} and generating a @@ -239,7 +299,7 @@ It is customary to make the first line of @file{Makefile.am} read: -@node Depth +@node Depth, Strictness, General Operation, Generalities @section Depth @code{automake} supports three kinds of directory hierarchy: ``flat'', ``shallow'', and ``deep''. @@ -263,7 +323,7 @@ reside in subdirectories. Automake is one such package (as is GNU @code{make}, which does not currently use @code{automake}). -@node Strictness +@node Strictness, Uniform, Depth, Generalities @section Strictness While Automake is intended to be used by maintainers of GNU packages, it does make some effort to accommodate those who wish to use it, but do @@ -300,7 +360,7 @@ For more information on the precise implications of the strictness level, see @xref{Gnits}. -@node Uniform +@node Uniform, Canonicalization, Strictness, Generalities @section The Uniform Naming Scheme Automake variables generally follow a uniform naming scheme that makes it easy to decide how programs (and other derived objects) are built, @@ -388,7 +448,7 @@ and @samp{TEXINFOS}. @vindex TEXINFOS -@node Canonicalization +@node Canonicalization, , Uniform, Generalities @section How derived variables are named Sometimes a Makefile variable name is derived from some text the user @@ -401,7 +461,7 @@ underscores when making macro references. E.g., if your program is named @code{sniff_glue_SOURCES}, not @code{sniff-glue_SOURCES}. -@node Examples +@node Examples, Invoking Automake, Generalities, Top @chapter Some example packages @menu @@ -410,7 +470,7 @@ underscores when making macro references. E.g., if your program is named * etags:: Building etags and ctags @end menu -@node Complete +@node Complete, Hello, Examples, Examples @section A simple example, start to finish Let's suppose you just finished writing @code{zardoz}, a program to make @@ -465,7 +525,7 @@ Now you can run @code{automake --add-missing} to generate your you're done! -@node Hello +@node Hello, etags, Complete, Examples @section A classic program @code{hello} is renowned for its classic simplicity and versatility. @@ -559,7 +619,7 @@ INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\" @end example -@node etags +@node etags, , Hello, Examples @section Building etags and ctags Here is another, trickier example. It shows how to generate two @@ -610,7 +670,7 @@ ctags._o: etags._c @end example -@node Invoking Automake +@node Invoking Automake, configure, Examples, Top @chapter Creating a @file{Makefile.in} To create all the @file{Makefile.in}s for a package, run the @@ -710,7 +770,7 @@ Print the version number of Automake and exit. @end table -@node configure +@node configure, Top level, Invoking Automake, Top @chapter Scanning @file{configure.in} Automake scans the package's @file{configure.in} to determine certain @@ -732,12 +792,12 @@ maintenance easier. These macros can automatically be put into your @end menu -@node Requirements +@node Requirements, Optional, configure, configure @section Configuration requirements The simplest way to meet the basic Automake requirements is to use the -macro @code{AM_INIT_AUTOMAKE} (FIXME: xref). But if you prefer, you can -do the required steps by hand: +macro @code{AM_INIT_AUTOMAKE} (@pxref{Macros}). But if you prefer, you +can do the required steps by hand: @cvindex AM_INIT_AUTOMAKE @itemize @bullet @@ -754,7 +814,7 @@ the release that is being developed. We recommend that you make number is defined; this makes releases simpler. Automake doesn't do any interpretation of @code{PACKAGE} or -@code{VERSION}, except in @samp{Gnits} mode (FIXME xref). +@code{VERSION}, except in @samp{Gnits} mode (@pxref{Gnits}). @item Use the macro @code{AC_ARG_PROGRAM} if a program or script is installed. @@ -802,7 +862,7 @@ are removed by @code{make clean}. @cvindex AC_OUTPUT @end table -@node Optional +@node Optional, Invoking aclocal, Requirements, configure @section Other things Automake recognizes Automake will also recognize the use of certain macros and tailor the @@ -931,8 +991,8 @@ requirements. This macro adds a @samp{--enable-maintainer-mode} option to @code{configure}. If this is used, @code{automake} will cause ``maintainer-only'' rules to be turned off by default in the generated -@file{Makefile.in}s. This macro is disallowed in @samp{Gnits} mode. -FIXME xref. +@file{Makefile.in}s. This macro is disallowed in @samp{Gnits} mode +(@pxref{Gnits}). @cvindex AM_MAINTAINER_MODE @item AC_SUBST @@ -953,7 +1013,7 @@ a variable in each generated @file{Makefile.in}. @end table -@node Invoking aclocal +@node Invoking aclocal, Macros, Optional, configure @section Auto-generating aclocal.m4 Automake includes a number of Autoconf macros which can be used in your @@ -1001,7 +1061,7 @@ Print the version number of Automake and exit. @end table -@node Macros +@node Macros, Extending aclocal, Invoking aclocal, configure @section Autoconf macros supplied with Automake @c consider generating this node automatically from m4 files. @@ -1123,7 +1183,7 @@ into @samp{LIBOBJS}. @end table -@node Extending aclocal +@node Extending aclocal, , Macros, configure @section Writing your own aclocal macros Aclocal doesn't have any built-in knowledge of any macros, so it is easy @@ -1142,7 +1202,7 @@ separate file. A macro file's name should end in @samp{.m4}. Such files should be installed in @file{$(datadir)/aclocal}. -@node Top level +@node Top level, Programs, configure, Top @chapter The top-level @file{Makefile.am} In non-flat packages, the top level @file{Makefile.am} must tell @@ -1181,7 +1241,7 @@ The use of @code{SUBDIRS} is not restricted to just the top-level arbitrary depth. -@node Programs +@node Programs, Other objects, Top level, Top @chapter Building Programs and Libraries A large part of Automake's functionality is dedicated to making it easy @@ -1194,13 +1254,13 @@ to build C programs and libraries. * A Shared Library:: Building a Libtool library * Program variables:: Variables used when building a program * Yacc and Lex:: Yacc and Lex support -* C++:: C++ and other languages +* C++:: * ANSI:: Automatic de-ANSI-fication * Dependencies:: Automatic dependency tracking @end menu -@node A Program +@node A Program, A Library, Programs, Programs @section Building a program In a directory containing source that gets built into a program (as @@ -1319,7 +1379,7 @@ known that they will not cause an invalid value for @samp{prog_DEPENDENCIES} to be generated. -@node A Library +@node A Library, LIBOBJS, A Program, Programs @section Building a library Building a library is much like building a program. In this case, the @@ -1353,7 +1413,7 @@ variable. This should be used for objects determined by libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@ @end example -@node LIBOBJS +@node LIBOBJS, A Shared Library, A Library, Programs @section Special handling for LIBOBJS and ALLOCA Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and @@ -1366,7 +1426,7 @@ dependency-tracking scheme, see @xref{Dependencies}. @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any @samp{_LDADD} or @samp{_LIBADD} variable. -@node A Shared Library +@node A Shared Library, Program variables, LIBOBJS, Programs @section Building a Shared Library Building shared libraries is a relatively complex matter. For this @@ -1408,7 +1468,7 @@ hand. @xref{Using Automake, Using Automake with Libtool, The Libtool Manual, libtool, The Libtool Manual}, for more information. -@node Program variables +@node Program variables, Yacc and Lex, A Shared Library, Programs @section Variables used when building a program Occasionally it is useful to know which @file{Makefile} variables @@ -1444,7 +1504,7 @@ This is the command used to actually link a C program. @end table -@node Yacc and Lex +@node Yacc and Lex, C++, Program variables, Programs @section Yacc and Lex support Automake has somewhat idiosyncratic support for Yacc and Lex. @@ -1547,7 +1607,7 @@ These defines work for @code{bison}, @code{byacc}, and traditional covered here, please report the new name so it can be added to the list. -@node C++ +@node C++, ANSI, Yacc and Lex, Programs @section C++ and other languages Automake includes full support for C++, and rudimentary support for @@ -1580,7 +1640,7 @@ The command used to actually link a C++ program. @end table -@node ANSI +@node ANSI, Dependencies, C++, Programs @section Automatic de-ANSI-fication Although the GNU standards allow the use of ANSI C, this can have the @@ -1628,7 +1688,7 @@ AUTOMAKE_OPTIONS = ../lib/ansi2knr If no directory prefix is given, the files are assumed to be in the current directory. -@node Dependencies +@node Dependencies, , ANSI, Programs @section Automatic dependency tracking As a developer it is often painful to continually update the @@ -1683,7 +1743,7 @@ specific. It is safe to delete them if you like; they will be automatically recreated during the next build. -@node Other objects +@node Other objects, Other GNU Tools, Programs, Top @chapter Other Derived Objects Automake can handle derived objects which are not C programs. Sometimes @@ -1699,7 +1759,7 @@ distribution. @end menu -@node Scripts +@node Scripts, Headers, Other objects, Other objects @section Executable Scripts It is possible to define and install programs which are scripts. Such @@ -1725,7 +1785,7 @@ Script objects can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir}, or @code{pkgdatadir}. -@node Headers +@node Headers, Data, Scripts, Other objects @section Header files Header files are specified by the @samp{HEADERS} family of variables. @@ -1743,7 +1803,7 @@ Headers can be installed in @code{includedir}, @code{oldincludedir}, or @code{pkgincludedir}. -@node Data +@node Data, Sources, Headers, Other objects @section Architecture-independent data files Automake supports the installation of miscellaneous data files using the @@ -1763,7 +1823,7 @@ pkgdata_DATA = clean-kr.am clean.am @dots{} @end example -@node Sources +@node Sources, , Data, Other objects @section Built sources Occasionally a file which would otherwise be called ``source'' (eg a C @@ -1782,7 +1842,7 @@ automatic dependency tracking, the @file{Makefile} must depend on what might seem like funny times. -@node Other GNU Tools +@node Other GNU Tools, Documentation, Other objects, Top @chapter Other GNU Tools Since Automake is primarily intended to generate @file{Makefile.in}s for @@ -1795,14 +1855,14 @@ use in GNU programs, it tries hard to interoperate with other GNU tools. * Libtool:: Libtool @end menu -@node Emacs Lisp +@node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools @section Emacs Lisp Automake provides some support for Emacs Lisp. The @samp{LISP} primary is used to hold a list of @samp{.el} files. Possible prefixes for this primary are @samp{lisp_} and @samp{noinst_}. Note that if @code{lisp_LISP} is defined, then @file{configure.in} must run -@code{AM_PATH_LISPDIR} (fixme xref). +@code{AM_PATH_LISPDIR} (@pxref{Macros}). @vindex LISP @vindex lisp_LISP @vindex noinst_LISP @@ -1819,7 +1879,7 @@ you leave it enabled by default. It is probably better for sites with strange setups to cope for themselves than to make the installation less nice for everybody else. -@node gettext +@node gettext, Guile, Emacs Lisp, Other GNU Tools @section Gettext If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake @@ -1836,7 +1896,7 @@ in @file{configure.in} corresponds to all the valid @samp{.po} files, and nothing more. -@node Guile +@node Guile, Libtool, gettext, Other GNU Tools @section Guile Automake provides some automatic support for writing Guile modules. @@ -1856,14 +1916,14 @@ macro is understood to mean: As the Guile module code matures, no doubt the Automake support will grow as well. -@node Libtool +@node Libtool, , Guile, Other GNU Tools @section Libtool Automake provides support for GNU Libtool (@pxref{Top, , The Libtool Manual, libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary. @xref{A Shared Library}. -@node Documentation +@node Documentation, Install, Other GNU Tools, Top @chapter Building documentation Currently Automake provides support for Texinfo and man pages. @@ -1874,7 +1934,7 @@ Currently Automake provides support for Texinfo and man pages. @end menu -@node Texinfo +@node Texinfo, Man pages, Documentation, Documentation @section Texinfo If the current directory contains Texinfo source, you must declare it @@ -1931,7 +1991,7 @@ use this. By default, info pages are installed by @samp{make install}. This can be prevented via the @code{no-installinfo} option. -@node Man pages +@node Man pages, , Texinfo, Documentation @section Man pages A package can also include man pages. (Though see the GNU standards on @@ -1968,7 +2028,7 @@ Man pages are not currently considered to be source, because it is not uncommon for man pages to be automatically generated. -@node Install +@node Install, Clean, Documentation, Top @chapter What Gets Installed Naturally, Automake handles the details of actually installing your @@ -2014,7 +2074,7 @@ the name (eg @samp{myexecbin_PROGRAMS} is installed by @samp{install-data}. -@node Clean +@node Clean, Dist, Install, Top @chapter What Gets Cleaned The GNU Makefile Standards specify a number of different clean rules. @@ -2030,7 +2090,7 @@ be defined to specify additional files to clean. These variables are @vindex MAINTAINERCLEANFILES -@node Dist +@node Dist, Tests, Clean, Top @chapter What Goes in a Distribution The @code{dist} target in the generated @file{Makefile.in} can be used @@ -2084,7 +2144,7 @@ makes a distribution, and then tries to do a @code{VPATH} build. @trindex distcheck @c FIXME: document distcheck-hook here -@node Tests +@node Tests, Options, Dist, Top @chapter Support for test suites Automake supports a two forms of test suite. @@ -2132,7 +2192,7 @@ names. In either case, the testing is done via @samp{make check}. -@node Options +@node Options, Miscellaneous, Tests, Top @chapter Changing Automake's Behavior Various features of Automake can be controlled by options in the @@ -2210,7 +2270,7 @@ will be suppressed. Unrecognized options are diagnosed by @code{automake}. -@node Miscellaneous +@node Miscellaneous, Conditionals, Options, Top @chapter Miscellaneous Rules There are a few rules and variables that didn't fit anywhere else. @@ -2221,7 +2281,7 @@ There are a few rules and variables that didn't fit anywhere else. @end menu -@node Tags +@node Tags, Suffixes, Miscellaneous, Miscellaneous @section Interfacing to @code{etags} @code{automake} will generate rules to generate @file{TAGS} files for @@ -2260,7 +2320,7 @@ directory-by-directory basis. @trindex id -@node Suffixes +@node Suffixes, , Tags, Miscellaneous @section Handling new file extensions It is sometimes useful to introduce a new implicit rule to handle a file @@ -2277,7 +2337,7 @@ source files, you would also need to add these suffixes to the list: SUFFIXES = .java .class @end example -@node Conditionals +@node Conditionals, Gnits, Miscellaneous, Top @chapter Conditionals Automake supports a simple type of conditionals. @@ -2340,7 +2400,7 @@ and are based on variables passed to the make program or defined in the Automake conditionals will work with any make program. -@node Gnits +@node Gnits, Cygnus, Conditionals, Top @chapter The effect of @code{--gnu} and @code{--gnits} The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS} @@ -2395,7 +2455,7 @@ The file @file{THANKS} is required. @end itemize -@node Cygnus +@node Cygnus, Extending, Gnits, Top @chapter The effect of @code{--cygnus} Cygnus Solutions has slightly different rules for how a @@ -2445,7 +2505,7 @@ GNU maintainers are advised to use @samp{gnu} strictness in preference to the special Cygnus mode. -@node Extending +@node Extending, Distributing, Cygnus, Top @chapter When Automake Isn't Enough Automake's implicit copying semantics means that many problems can be @@ -2502,7 +2562,7 @@ install-exec-hook: @c rules -@node Distributing +@node Distributing, Future, Extending, Top @chapter Distributing @file{Makefile.in}s Automake places no restrictions on the distribution of the resulting @@ -2515,7 +2575,7 @@ Some of the files that can be automatically installed via the to see. -@node Future +@node Future, Index, Distributing, Top @chapter Some ideas for the future Here are some things that might happen in the future: @@ -2545,7 +2605,7 @@ Rewrite in Guile. This won't happen in the near future, but it will eventually happen. @end itemize -@node Index +@node Index, , Future, Top @unnumbered Index @printindex cp diff --git a/stamp-vti b/stamp-vti index 45abee21..62396764 100644 --- a/stamp-vti +++ b/stamp-vti @@ -1,3 +1,3 @@ -@set UPDATED 24 September 1997 +@set UPDATED 28 September 1997 @set EDITION 1.2b @set VERSION 1.2b diff --git a/version.texi b/version.texi index 45abee21..62396764 100644 --- a/version.texi +++ b/version.texi @@ -1,3 +1,3 @@ -@set UPDATED 24 September 1997 +@set UPDATED 28 September 1997 @set EDITION 1.2b @set VERSION 1.2b -- 2.43.5