[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Patch: FYI: doc updates
From: |
Tom Tromey |
Subject: |
Patch: FYI: doc updates |
Date: |
28 Jul 2001 13:59:56 -0600 |
More documentation changes.
Tom
Index: ChangeLog
from Tom Tromey <address@hidden>
* automake.texi (Strictness): Mention Cygnus mode.
(Cygnus): Updated.
(Uniform): Likewise.
(Canonicalization): Likewise.
(Install): Add `nobase_' to example; typo fix.
(Clean): Typo.
(Dist): Expand on putting a directory into EXTRA_DIST. Insert
section markers.
(Options): Texinfo fixes; some text updates.
Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.230
diff -u -r1.230 automake.texi
--- automake.texi 2001/07/27 15:34:14 1.230
+++ automake.texi 2001/07/28 19:27:49
@@ -338,7 +338,12 @@
For more information on the precise implications of the strictness
level, see @ref{Gnits}.
+Automake also has a special ``cygnus'' mode which is similar to
+strictness but handled differently. This mode is useful for packages
+which are put into a ``Cygnus'' style tree (e.g., the GCC tree). For
+more information on this mode, see @ref{Cygnus}.
+
@node Uniform, Canonicalization, Strictness, Generalities
@section The Uniform Naming Scheme
@@ -357,8 +362,11 @@
@cindex Primary variable, defined
At @code{make} time, certain variables are used to determine which
-objects are to be built. These variables are called @dfn{primary
-variables}. For instance, the primary variable @code{PROGRAMS} holds a
+objects are to be built. The variable names are made of several pieces
+which are concatenated together.
+
+The piece which tells automake what is being built is commonly called
+the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
list of programs which are to be compiled and linked.
@vindex PROGRAMS
@@ -370,16 +378,15 @@
@vindex pkgincludedir
@vindex pkgdatadir
-A different set of variables is used to decide where the built objects
-should be installed. These variables are named after the primary
-variables, but have a prefix indicating which standard directory should
-be used as the installation directory. The standard directory names are
-given in the GNU standards (@pxref{Directory Variables, , , standards,
-The GNU Coding Standards}). Automake extends this list with
address@hidden, @code{pkgincludedir}, and @code{pkgdatadir}; these are
-the same as the address@hidden versions, but with @samp{@@PACKAGE@@}
-appended. For instance, @code{pkglibdir} is defined as
address@hidden(libdir)/@@PACKAGE@@}.
+A different set of names is used to decide where the built objects
+should be installed. These names are prefixes to the primary which
+indicate which standard directory should be used as the installation
+directory. The standard directory names are given in the GNU standards
+(@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
+Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
+and @code{pkgdatadir}; these are the same as the address@hidden
+versions, but with @samp{@@PACKAGE@@} appended. For instance,
address@hidden is defined as @code{$(libdir)/@@PACKAGE@@}.
@cvindex PACKAGE
@cindex EXTRA_, prepending
@@ -405,8 +412,8 @@
sbin_PROGRAMS = @@MORE_PROGRAMS@@
@end example
-Defining a primary variable without a prefix (e.g. @code{PROGRAMS}) is
-an error.
+Defining a primary without a prefix as a variable, e.g.,
address@hidden, is an error.
Note that the common @samp{dir} suffix is left off when constructing the
variable names; thus one writes @samp{bin_PROGRAMS} and not
@@ -446,7 +453,7 @@
The special prefix @samp{check} indicates that the objects in question
should not be built until the @code{make check} command is run.
-Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
+The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
@samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
@samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
@vindex PROGRAMS
@@ -471,18 +478,23 @@
@cindex canonicalizing Automake macros
-Sometimes a Makefile variable name is derived from some text the user
-supplies. For instance, program names are rewritten into Makefile macro
-names. Automake canonicalizes this text, so that it does not have to
-follow Makefile macro naming rules. All characters in the name except
-for letters, numbers, the strudel (@@), and the underscore are turned into
-underscores when making macro references. For example, if your program
-is named @code{sniff-glue}, the derived variable name would be
address@hidden, not @code{sniff-glue_SOURCES}. The strudel
-is an addition since Automake 1.4c, to make the use of Autoconf
-substitutions in macro names less obfuscating.
+Sometimes a Makefile variable name is derived from some text the
+maintainer supplies. For instance, a program name listed in
address@hidden 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
+rules. All characters in the name except for letters, numbers, the
+strudel (@@), and the underscore are turned into underscores when making
+macro references.
+
+For example, if your program is named @code{sniff-glue}, the derived
+variable name would be @code{sniff_glue_SOURCES}, not
address@hidden
+The strudel is an addition, to make the use of Autoconf substitutions in
+macro names less obfuscating.
+
@node User Variables, Auxiliary Programs, Canonicalization, Generalities
@section Variables reserved for the user
@@ -3350,10 +3362,10 @@
suppress the base name step. For example:
@example
-include_HEADERS = stdio.h sys/types.h
+nobase_include_HEADERS = stdio.h sys/types.h
@end example
-Will include @file{stdio.h} in @code{$(includedir)} and @file{types.h}
+Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
in @code{$(includedir)/sys}.
Automake generates separate @code{install-data} and @code{install-exec}
@@ -3432,7 +3444,7 @@
@vindex MAINTAINERCLEANFILES
As the GNU Standards aren't always explicit as to which files should be
-removed by which target, we've adopted a heuristic which we believe were
+removed by which target, we've adopted a heuristic which we believe was
first formulated by Fran@,{c}ois Pinard:
@itemize @bullet
@@ -3459,6 +3471,8 @@
@node Dist, Tests, Clean, Top
@chapter What Goes in a Distribution
address@hidden Basics of distribution
+
@cindex make dist
@cindex make distcheck
@@ -3484,14 +3498,18 @@
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 @code{EXTRA_DIST} variable. You can mention files from
-subdirectories in @code{EXTRA_DIST}. You can also mention a directory
-there; in this case the entire directory will be recursively copied into
-the distribution. Please note that this will also copy
address@hidden in the directory, including CVS/RCS version control
-files.
+subdirectories in @code{EXTRA_DIST}.
+You can also mention a directory in @code{EXTRA_DIST}; in this case the
+entire directory will be recursively copied into the distribution.
+Please note that this will also copy @emph{everything} in the directory,
+including CVS/RCS version control files. We recommend against using
+this feature.
+
@vindex EXTRA_DIST
address@hidden Fine-grained distribution control
+
Sometimes you need tighter control over what does @emph{not} go into the
distribution; for instance you might have source files which are
generated and which you do not want to distribute. In this case
@@ -3512,6 +3530,8 @@
nodist_foo_SOURCES = do-not-distribute.c
@end example
address@hidden The dist hook
+
Another way to to use this is for removing unnecessary files that get
recursively included by specifying a directory in EXTRA_DIST:
@@ -3545,6 +3565,8 @@
cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
@end example
address@hidden Checking the distribution
+
Automake also generates a @code{distcheck} target which can be of help
to ensure that a given distribution will actually work.
@code{distcheck} makes a distribution, and then tries to do a
@@ -3657,7 +3679,7 @@
@item @code{gnits}
@itemx @code{gnu}
@itemx @code{foreign}
address@hidden @code{cygnus}
address@hidden @code{cygnus}
@cindex Option, gnits
@cindex Option, gnu
@cindex Option, foreign
@@ -3667,13 +3689,13 @@
@code{readme-alpha} and @code{check-news}.
@item @code{ansi2knr}
address@hidden @code{path/ansi2knr}
address@hidden @address@hidden/ansi2knr}
@cindex Option, ansi2knr
Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
path, the generated @file{Makefile.in} will look in the specified
-directory to find the @file{ansi2knr} program. Generally the path
-should be a relative path to another directory in the same distribution
-(though Automake currently does not check this).
+directory to find the @file{ansi2knr} program. The path should be a
+relative path to another directory in the same distribution (Automake
+currently does not check this).
@item @code{check-news}
@cindex Option, check-news
@@ -3813,9 +3835,10 @@
@file{TAGS} file that includes by reference all @file{TAGS} files from
subdirectories.
-Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
-will be generated. This variable is intended for use in directories
-which contain taggable source that @code{etags} does not understand.
+The @code{tags} target will also be generated if the variable
address@hidden is defined. This variable is intended for use in
+directories which contain taggable source that @code{etags} does not
+understand.
@vindex ETAGS_ARGS
Here is how Automake generates tags for its source, and for nodes in its
@@ -4069,10 +4092,14 @@
@cindex Cygnus strictness
-Cygnus Solutions has slightly different rules for how a
address@hidden is to be constructed. Passing @samp{--cygnus} to
address@hidden will cause any generated @file{Makefile.in} to comply
-with Cygnus rules.
+Some packages, notably GNU GCC and GNU gdb, have a build environment
+originally written at Cygnus Support (subsequently renamed Cygnus
+Solutions, and then later purchased by Red Hat). Packages with this
+ancestry are sometimes referred to as ``Cygnus'' trees.
+
+A Cygnus tree has slightly different rules for how a @file{Makefile.in}
+is to be constructed. Passing @samp{--cygnus} to @code{automake} will
+cause any generated @file{Makefile.in} to comply with Cygnus rules.
Here are the precise effects of @samp{--cygnus}:
@@ -4088,9 +4115,8 @@
Cygnus packages are typically bundled.
@item
address@hidden dist} will look for files in the build directory as well as
-the source directory. This is required to support putting info files
-into the build directory.
address@hidden dist} is not supported, and the rules for it are not
+generated. Cygnus-style trees use their own distribution mechanism.
@item
Certain tools will be searched for in the build tree as well as in the
@@ -4113,7 +4139,10 @@
@end itemize
GNU maintainers are advised to use @samp{gnu} strictness in preference
-to the special Cygnus mode.
+to the special Cygnus mode. Some day, perhaps, the differences between
+Cygnus trees and GNU trees will disappear (for instance, as GCC is made
+more standards compliant). At that time the special Cygnus mode will be
+removed.
@node Extending, Distributing, Cygnus, Top
Index: stamp-vti
===================================================================
RCS file: /cvs/automake/automake/stamp-vti,v
retrieving revision 1.129
diff -u -r1.129 stamp-vti
--- stamp-vti 2001/07/27 15:34:14 1.129
+++ stamp-vti 2001/07/28 19:27:49
@@ -1,4 +1,4 @@
address@hidden UPDATED 27 July 2001
address@hidden UPDATED 28 July 2001
@set UPDATED-MONTH July 2001
@set EDITION 1.4i
@set VERSION 1.4i
Index: version.texi
===================================================================
RCS file: /cvs/automake/automake/version.texi,v
retrieving revision 1.202
diff -u -r1.202 version.texi
--- version.texi 2001/07/27 15:34:14 1.202
+++ version.texi 2001/07/28 19:27:49
@@ -1,4 +1,4 @@
address@hidden UPDATED 27 July 2001
address@hidden UPDATED 28 July 2001
@set UPDATED-MONTH July 2001
@set EDITION 1.4i
@set VERSION 1.4i
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Patch: FYI: doc updates,
Tom Tromey <=