From: Alexandre Duret-Lutz Date: Wed, 10 Jul 2002 21:21:27 +0000 (+0000) Subject: * automake.texi: Use `variable' instead of `macro' everywhere it X-Git-Tag: Release-1-6b~18 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=76b1f9e40e54a799f4e62229036535e63e2b27ee;p=thirdparty%2Fautomake.git * automake.texi: Use `variable' instead of `macro' everywhere it designates a Makefile variable. (Texinfo): `VERSION', `UPDATED', `EDITION', and `UPDATED-MONTH' are `flags', not `macros'. `Macro' means something else in Texinfo. Also show how to use these flags. * automake.in (file_contents_internal): s/macro/variable/ in error message. --- diff --git a/ChangeLog b/ChangeLog index 6d705600e..9f4b151c7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,13 @@ 2002-07-10 Alexandre Duret-Lutz + * automake.texi: Use `variable' instead of `macro' everywhere it + designates a Makefile variable. + (Texinfo): `VERSION', `UPDATED', `EDITION', and `UPDATED-MONTH' are + `flags', not `macros'. `Macro' means something else in Texinfo. + Also show how to use these flags. + * automake.in (file_contents_internal): s/macro/variable/ in + error message. + * automake.in (parse_arguments): Call Getopt twice: once to catch --help or --verbose, and once to process the other arguments. (usage, verbose): Always exit 0, ignoring $exit_code (which anyway diff --git a/automake.in b/automake.in index ab10831a0..14957f60f 100755 --- a/automake.in +++ b/automake.in @@ -7722,7 +7722,7 @@ sub file_contents_internal ($$%) elsif (/$ASSIGNMENT_PATTERN/mso) { my ($var, $type, $val) = ($1, $2, $3); - err $file, "macro `$var' with trailing backslash" + err $file, "variable `$var' with trailing backslash" if /\\$/; $is_rule = 0; diff --git a/automake.texi b/automake.texi index 9990aad68..23a0291f8 100644 --- a/automake.texi +++ b/automake.texi @@ -146,9 +146,11 @@ This edition documents version @value{VERSION}. Automake is a tool for automatically generating @file{Makefile.in}s from files called @file{Makefile.am}. Each @file{Makefile.am} is basically a -series of @code{make} macro definitions (with rules being thrown in -occasionally). The generated @file{Makefile.in}s are compliant with the -GNU Makefile standards. +series of @code{make} variable definitions@footnote{These variables are +also called @dfn{make macros} in Make terminology, however in this +manual we reserve the term @dfn{macro} for Autoconf's macros.}, with +rules being thrown in occasionally. The generated @file{Makefile.in}s +are compliant with the GNU Makefile standards. @cindex GNU Makefile standards @@ -159,7 +161,7 @@ remove the burden of Makefile maintenance from the back of the individual GNU maintainer (and put it on the back of the Automake maintainer). -The typical Automake input file is simply a series of macro definitions. +The typical Automake input file is simply a series of variable definitions. Each such file is processed to create a @file{Makefile.in}. There should generally be one @file{Makefile.am} per directory of a project. @@ -210,16 +212,16 @@ understand how Automake works. @section General Operation Automake works by reading a @file{Makefile.am} and generating a -@file{Makefile.in}. Certain macros and targets defined in the +@file{Makefile.in}. Certain variables and targets defined in the @file{Makefile.am} instruct Automake to generate more specialized code; -for instance, a @samp{bin_PROGRAMS} macro definition will cause targets +for instance, a @samp{bin_PROGRAMS} variable definition will cause targets for compiling and linking programs to be generated. @cindex Non-standard targets @cindex cvs-dist, non-standard example @trindex cvs-dist -The macro definitions and targets in the @file{Makefile.am} are copied +The variable definitions and targets in the @file{Makefile.am} are copied verbatim into the generated file. This allows you to add arbitrary code into the generated @file{Makefile.in}. For instance the Automake distribution includes a non-standard @code{cvs-dist} target, which the @@ -234,13 +236,12 @@ behavior. @cindex Append operator A special exception is that the GNU make append operator, @samp{+=}, is -supported. This operator appends its right hand argument to the macro +supported. This operator appends its right hand argument to the variable specified on the left. Automake will translate the operator into an ordinary @samp{=} operator; @samp{+=} will thus work with any make program. -Automake tries to group comments with adjoining targets and macro -definitions in an intelligent way. -@c FIXME: What does this imply practically? +Automake tries to keep comments grouped with any adjoining targets or +variable definitions. @cindex Make targets, overriding @cindex Overriding make targets @@ -251,22 +252,22 @@ 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. -@cindex Macros, overriding -@cindex Overriding make macros +@cindex Variables, overriding +@cindex Overriding make variables -Similarly, a macro defined in @file{Makefile.am} or @code{AC_SUBST}'ed -from @file{configure.in} will override any definition of the macro that +Similarly, a variable defined in @file{Makefile.am} or @code{AC_SUBST}'ed +from @file{configure.in} will override any definition of the variable that @code{automake} would ordinarily create. This feature is more often useful than the ability to override a target definition. Be warned that -many of the macros generated by @code{automake} are considered to be for +many of the variables generated by @code{automake} are considered to be for internal use only, and their names might change in future releases. @cindex Recursive operation of Automake @cindex Automake, recursive operation @cindex Example of recursive operation -When examining a macro definition, Automake will recursively examine -macros referenced in the definition. For example, if Automake is +When examining a variable definition, Automake will recursively examine +variables referenced in the definition. For example, if Automake is looking at the content of @code{foo_SOURCES} in this snippet @example @@ -358,11 +359,10 @@ more information on this mode, see @ref{Cygnus}. @cindex Uniform naming scheme -Automake macros (from here on referred to as @emph{variables}) generally -follow a @dfn{uniform naming scheme} that makes it easy to decide how -programs (and other derived objects) are built, and how they are -installed. This scheme also supports @code{configure} time -determination of what should be built. +Automake variables generally follow a @dfn{uniform naming scheme} that +makes it easy to decide how programs (and other derived objects) are +built, and how they are installed. This scheme also supports +@code{configure} time determination of what should be built. @cindex _PROGRAMS primary variable @cindex PROGRAMS primary variable @@ -487,16 +487,16 @@ are explained later (@pxref{Program and Library Variables}). @node Canonicalization, User Variables, Uniform, Generalities @section How derived variables are named -@cindex canonicalizing Automake macros +@cindex canonicalizing Automake variables Sometimes a Makefile variable name is derived from some text the maintainer supplies. For instance, a program name listed in @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES} variable. In cases like this, Automake canonicalizes the text, so that -program names and the like do not have to follow Makefile macro naming +program names and the like do not have to follow Makefile variable naming rules. All characters in the name except for letters, numbers, the strudel (@@), and the underscore are turned into underscores when making -macro references. +variable references. For example, if your program is named @code{sniff-glue}, the derived variable name would be @code{sniff_glue_SOURCES}, not @@ -505,7 +505,7 @@ variable name would be @code{sniff_glue_SOURCES}, not @code{libmumble___a_SOURCES} variable. The strudel is an addition, to make the use of Autoconf substitutions in -macro names less obfuscating. +variable names less obfuscating. @node User Variables, Auxiliary Programs, Canonicalization, Generalities @@ -1644,7 +1644,7 @@ tell Automake which subdirectories are to be built. This is done via the @code{SUBDIRS} variable. @vindex SUBDIRS -The @code{SUBDIRS} macro holds a list of subdirectories in which +The @code{SUBDIRS} variable holds a list of subdirectories in which building of various sorts can occur. Many targets (e.g. @code{all}) in the generated @file{Makefile} will run both locally and in all specified subdirectories. Note that the directories listed in @code{SUBDIRS} are @@ -1690,7 +1690,7 @@ The upshot of this is that Automake is tricked into building the package to take the subdirs, but doesn't actually bind that list until @code{configure} is run. -Although the @code{SUBDIRS} macro can contain configure substitutions +Although the @code{SUBDIRS} variable can contain configure substitutions (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the contents of this variable. @@ -1719,7 +1719,7 @@ subdirectories to be examined. In this case Automake will use @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to recurse. This variable will also be used when the user runs @code{distclean} or @code{maintainer-clean}. It should be set to the -full list of subdirectories in the project. If this macro is not set, +full list of subdirectories in the project. If this variable is not set, Automake will attempt to set it for you. @@ -1785,7 +1785,7 @@ Sometimes you need to run @code{aclocal} with an argument like @code{-I} to tell it where to find @file{.m4} files. Since sometimes @code{make} will automatically run @code{aclocal}, you need a way to specify these arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this -holds arguments which are passed verbatim to @code{aclocal}. This macro +holds arguments which are passed verbatim to @code{aclocal}. This variable is only useful in the top-level @file{Makefile.am}. @vindex ACLOCAL_AMFLAGS @@ -2274,7 +2274,7 @@ followed by the name of the library and then the objects being put into the library. You can override this by setting the @samp{_AR} variable. This is usually used with C++; some C++ compilers require a special invocation in order to instantiate all the templates which should go -into a library. For instance, the SGI C++ compiler likes this macro set +into a library. For instance, the SGI C++ compiler likes this variable set like so: @example libmaude_a_AR = $(CXX) -ar -o @@ -2410,7 +2410,7 @@ There are some additional variables which Automake itself defines: @vtable @code @item AM_CPPFLAGS -The contents of this macro are passed to every compilation which invokes +The contents of this variable are passed to every compilation which invokes the C preprocessor; it is a list of arguments to the preprocessor. For instance, @samp{-I} and @samp{-D} options should be listed here. @@ -2422,7 +2422,7 @@ the default @samp{-I} options using the @samp{nostdinc} option. @item INCLUDES This does the same job as @samp{AM_CPPFLAGS}. It is an older name for -the same functionality. This macro is deprecated; we suggest using +the same functionality. This variable is deprecated; we suggest using @samp{AM_CPPFLAGS} instead. @item AM_CFLAGS @@ -2902,8 +2902,8 @@ As always, the contents of @samp{AM_GCJFLAGS} are passed to every compilation invoking @code{gcj} (in its role as an ahead-of-time compiler -- when invoking it to create @file{.class} files, @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass -options to @code{gcj} from @file{Makefile.am}, this macro, and not the -user macro @samp{GCJFLAGS}, should be used. +options to @code{gcj} from @file{Makefile.am}, this variable, and not +the user variable @samp{GCJFLAGS}, should be used. @vindex AM_GCJFLAGS @@ -3480,7 +3480,7 @@ Currently Automake provides support for Texinfo and man pages. If the current directory contains Texinfo source, you must declare it with the @samp{TEXINFOS} primary. Generally Texinfo files are converted -into info, and thus the @code{info_TEXINFOS} macro is most commonly used +into info, and thus the @code{info_TEXINFOS} variable is most commonly used here. Any Texinfo source file must end in the @file{.texi}, @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi} for new manuals. @@ -3494,26 +3494,28 @@ are built by @code{make all} and installed by @code{make install} be built on request by @code{make dvi}, @code{make ps}, and @code{make pdf}. -@cindex Texinfo macro, VERSION -@cindex Texinfo macro, UPDATED -@cindex Texinfo macro, EDITION -@cindex Texinfo macro, UPDATED-MONTH +@cindex Texinfo flag, VERSION +@cindex Texinfo flag, UPDATED +@cindex Texinfo flag, EDITION +@cindex Texinfo flag, UPDATED-MONTH -@cindex VERSION Texinfo macro -@cindex UPDATED Texinfo macro -@cindex EDITION Texinfo macro -@cindex UPDATED-MONTH Texinfo macro +@cindex VERSION Texinfo flag +@cindex UPDATED Texinfo flag +@cindex EDITION Texinfo flag +@cindex UPDATED-MONTH Texinfo flag @cindex mdate-sh If the @file{.texi} file @code{@@include}s @file{version.texi}, then that file will be automatically generated. The file @file{version.texi} -defines four Texinfo macros you can reference: +defines four Texinfo flag you can reference using +@code{@@value@{EDITION@}}, @code{@@value@{VERSION@}}, +@code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}. @table @code @item EDITION @itemx VERSION -Both of these macros hold the version number of your program. They are +Both of these flags hold the version number of your program. They are kept separate for clarity. @item UPDATED @@ -3609,7 +3611,7 @@ This can be prevented via the @code{no-installinfo} option. A package can also include man pages (but see the GNU standards on this matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man pages are declared using the @samp{MANS} primary. Generally the -@code{man_MANS} macro is used. Man pages are automatically installed in +@code{man_MANS} variable is used. Man pages are automatically installed in the correct subdirectory of @code{mandir}, based on the file extension. @vindex MANS @vindex man_MANS @@ -4386,7 +4388,7 @@ SUFFIXES = .idl C.cpp # whatever @end example -As you may have noted, the @code{SUFFIXES} macro behaves like the +As you may have noted, the @code{SUFFIXES} variable behaves like the @code{.SUFFIXES} special target of @code{make}. You should not touch @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let Automake generate the suffix list for @code{.SUFFIXES}. Any given