From 60263132bc79123c77e840ed59a25f5bd7958076 Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Mon, 9 Sep 1996 00:24:03 +0000 Subject: [PATCH] More doc fixes --- TODO | 18 ---------- automake.texi | 99 +++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 84 insertions(+), 33 deletions(-) diff --git a/TODO b/TODO index d18e09bc..1cccfe30 100644 --- a/TODO +++ b/TODO @@ -308,18 +308,10 @@ autosystem... Document: -go through handle_configure and make sure each macro is documented in -the appropriate place. Clean up ordering in document. Add info about -AM_ macros. - -should write more complete explanation of implicit copying semantics - finish yacc, lex Document customary ordering of Makefile.am. From François. -must document that @ALLOCA@ works in _LDADD - Should include extended version of diagram from Autoconf (suggested by Greg Woods) @@ -342,16 +334,6 @@ This is insufficiently clear must document the targets required for integration with non-automake-using subdirs -document actual uses of PACKAGE and VERSION - -Must document aclocal program - -document *not* putting config.h into _SOURCES - -document variable scanning: $() and ${} interpolation - -mention libit when talking about LIBOBJS - ================================================================ Libraries: diff --git a/automake.texi b/automake.texi index d7cd63b1..41bc58ae 100644 --- a/automake.texi +++ b/automake.texi @@ -105,7 +105,7 @@ documents version @value{VERSION}. * Top level:: The top-level Makefile.am * Programs:: Building programs and libraries * Other objects:: Other derived objects -* Emacs Lisp:: Emacs Lisp support +* Other GNU Tools:: Other GNU Tools * Documentation:: Building documentation * Install:: What gets installed * Clean:: What gets cleaned @@ -263,9 +263,20 @@ works. @node General Operation @section General Operation + Automake essentially works by reading a @file{Makefile.am} and -generating a @file{Makefile.in}. The macro definitions and targets in -the @file{Makefile.am} are copied into the generated file. +generating a @file{Makefile.in}. + +The macro definitions and targets in the @file{Makefile.am} are copied +into the generated file. This allows you to add essentially arbitrary +code into the generated @file{Makefile.in}. For instance the Automake +distribution includes a non-standard @code{cvs-dist} target, which the +Automake maintainer uses to make distributions from his source control +system. + +Note that GNU make extensions are not recognized by Automake. Using +such extensions in a @file{Makefile.am} will lead to errors or confusing +behavior. Automake tries to group comments with adjoining targets (or variable definitions) in an intelligent way. @@ -276,6 +287,18 @@ target of a similar name that would be automatically generated by best to avoid making use of it, as sometimes the generated rules are very particular. +When examining a variable definition, Automake will recursively examine +variables referenced in the definition. Eg if Automake is looking at +the content of @samp{foo_SOURCES} in this snippet + +@example +xs = a.c b.c +foo_SOURCES = c.c $(xs) +@end example + +it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the +contents of @samp{foo_SOURCES}. + Automake also allows a form of comment which is @emph{not} copied into the output; all lines beginning with @samp{##} are completely ignored by Automake. @@ -641,9 +664,9 @@ This is required when using automatic de-ANSI-fication, see @ref{ANSI}. @cvindex AM_C_PROTOTYPES @item ud_GNU_GETTEXT -This macro is required for packages which use GNU gettext (FIXME xref). -It is distributed with gettext. Automake uses this macro to ensure that -the package meets some of gettext's requirements. +This macro is required for packages which use GNU gettext +(@pxref{gettext}). It is distributed with gettext. Automake uses this +macro to ensure that the package meets some of gettext's requirements. @cvindex ud_GNU_GETTEXT @item AM_MAINTAINER_MODE @@ -769,6 +792,7 @@ to build C programs and libraries. @menu * A Program:: Building a program * A Library:: Building a library +* LIBOBJS:: Special handling for LIBOBJS and ALLOCA * Program variables:: Variables used when building a program * Yacc and Lex:: Yacc and Lex support * C++:: C++ and other languages @@ -814,7 +838,9 @@ can share a single source file. The source file must be listed in each @samp{_SOURCES} definition. Header files listed in a @samp{_SOURCES} definition will be included in -the distribution but otherwise ignored. +the distribution but otherwise ignored. In case it isn't obvious, you +should not include the header file generated by @file{configure} in an +@samp{_SOURCES} variable; this file should not be distributed. Lex (@samp{.l}) and yacc (@samp{.y}) files can also be listed; support for these should work but is still preliminary. @c lex & yacc should have a separate section @@ -870,6 +896,12 @@ target which is not actually part of that program. This can be done using the @samp{prog_DEPENDENCIES} variable. Each program depends on the contents of such a variable, but no further interpretation is done. +If @samp{prog_DEPENDENCIES} is not supplied, it is computed by Automake. +The automatically-assigned value is the contents of @samp{prog_LDADD} +with all the @samp{-l} and @samp{-L} options removed. Be warned that +@file{configure} substitutions are preserved; this can lead to bad +dependencies if you are not careful. + @node A Library @section Building a library @@ -901,12 +933,19 @@ variable. This should be used for objects determined by cpio_LIBADD = @@LIBOBJS@@ @@ALLOCA@@ @end example -Note that Automake explicitly recognizes the use of @code{@@LIBOBJS@@} -and @code{@@ALLOCA@@} in the above example, and uses this information, -plus the list of @code{LIBOBJS} files derived from @file{configure.in} -to automatically include the appropriate source files in the -distribution (@pxref{Dist}). These source files are also automatically -handled in the dependency-tracking scheme, see @xref{Dependencies}. + +@node LIBOBJS +@section Special handling for LIBOBJS and ALLOCA + +Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and +@code{@@ALLOCA@@}, and uses this information, plus the list of +@code{LIBOBJS} files derived from @file{configure.in} to automatically +include the appropriate source files in the distribution (@pxref{Dist}). +These source files are also automatically handled in the +dependency-tracking scheme, see @xref{Dependencies}. + +@code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any +@samp{_LDADD} or @samp{_LIBADD} variable. @node Program variables @@ -1147,8 +1186,20 @@ dependency tracking is done. Built sources are included in a distribution. +@node Other GNU Tools +@chapter Other GNU Tools + +Since Automake is primarily intended to generate @file{Makefile.in}s for +use in GNU programs, it tries hard to interoperatoe with other GNU +tools. + +@menu +* Emacs Lisp:: Emacs Lisp +* gettext:: Gettext +@end menu + @node Emacs Lisp -@chapter Emacs Lisp +@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 @@ -1164,6 +1215,23 @@ the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid byte-compiling, simply define the variable @samp{ELCFILES} to be empty. @vindex ELCFILES +@node gettext +@section Gettext + +If @code{ud_GNU_GETTEXT} is seen in @file{configure.in}, then Automake +turns on support for GNU gettext, a message catalog system for +internationalization +(@pxref{GNU Gettext, , , gettext.info, GNU gettext utilities}). + +The @code{gettext} support in Automake requires the addition of two +subdirectories to the package, @file{intl} and @file{po}. Automake +ensure that these directories exist and are mentioned in @code{SUBDIRS}. + +Furthermore, Automake checks that the definition of @samp{ALL_LINGUAS} +in @file{configure.in} corresponds to all the valid @samp{.po} files, +and nothing more. + + @node Documentation @chapter Building documentation @@ -1304,7 +1372,8 @@ be defined to specify additional files to clean. These variables are The @code{dist} target in the generated @file{Makefile.in} can be used to generate a gzip'd @code{tar} file for distribution. The tar file is -named based on the @var{PACKAGE} and @var{VERSION} variables. +named based on the @var{PACKAGE} and @var{VERSION} variables; more +precisely it is named @samp{@var{PACKAGE}-@var{VERSION}.tar.gz}. @cvindex PACKAGE @cvindex VERSION @trindex dist -- 2.43.5