Changeset 903 in kBuild for trunk/src/gmakenew/doc

Timestamp:

May 23, 2007 5:31:19 AM (18 years ago)

Author:

bird

Message:

Merged with the 2007-05-23 CVS. Added rsort and fixed a couple of windows build issues.

Location:

trunk/src/gmakenew/doc

Files:

• Makefile.in (deleted)
• fdl.texi (deleted)
• make-stds.texi (deleted)
• make.info (deleted)
• make.info-1 (deleted)
• make.info-2 (deleted)
• make.texi (modified) (16 diffs)
• stamp-vti (deleted)
• version.texi (deleted)

trunk/src/gmakenew/doc/make.texi

@@ -5 +5 @@
 @include version.texi
 @set EDITION 0.70
-@set RCSID $Id: make.texi,v 1.45 2006/04/01 06:36:40 psmith Exp $
+@set RCSID $Id: make.texi,v 1.47 2007/05/11 20:57:21 psmith Exp $
 
 @settitle GNU @code{make}
@@ -51 +51 @@
 
 
-@dircategory GNU Packages
+@dircategory Software development
 @direntry
 * Make: (make).            Remake files automatically.
@@ -1010 +1010 @@
 specially in certain situations.
 
+You cannot use comments within variable references or function calls:
+any instance of @code{#} will be treated literally (rather than as the
+start of a comment) inside a variable reference or function call.
+
 Within a command script (if the line begins with a TAB character) the
 entire line is passed to the shell, just as with any other line that
@@ -1252 +1256 @@
 @end example
 
-@xref{Text Functions}, for more information on the @code{word} and
-@code{words} functions used above.  @xref{Flavors, The Two Flavors of
-Variables}, for more information on simply-expanded (@code{:=})
-variable definitions.
+@xref{Text Functions}, for more information on the @code{lastword}
+function used above.  @xref{Flavors, The Two Flavors of Variables},
+for more information on simply-expanded (@code{:=}) variable
+definitions.
 
 @node Special Variables, Remaking Makefiles, MAKEFILE_LIST Variable, Makefiles
@@ -1745 +1749 @@
 @code{foo.1 bar.1} respectively.  In the third they will have values
 @code{foo.1}, @code{foo.1 bar.1 foo.2 bar.2}, and @code{foo.1 bar.1
-foo.2 bar.2} respectively.
+foo.2 bar.2 foo.1 foo.1 bar.1 foo.1 bar.1} respectively.
 
 Rules undergo secondary expansion in makefile order, except that
@@ -1938 +1942 @@
 Variables, ,How to Use Variables}).  If you have enabled secondary
 expansion (@pxref{Secondary Expansion}) and you want a literal dollar
-sign in the prerequisites lise, you must actually write @emph{four}
+sign in the prerequisites list, you must actually write @emph{four}
 dollar signs (@samp{$$$$}).
 
@@ -2001 +2005 @@
 The normal prerequisites section may of course be empty.  Also, you
 may still declare multiple lines of prerequisites for the same target:
-they are appended appropriately.  Note that if you declare the same
-file to be both a normal and an order-only prerequisite, the normal
-prerequisite takes precedence (since they are a strict superset of the
-behavior of an order-only prerequisite).
+they are appended appropriately (normal prerequisites are appended to
+the list of normal prerequisites; order-only prerequisites are
+appended to the list of order-only prerequisites).  Note that if you
+declare the same file to be both a normal and an order-only
+prerequisite, the normal prerequisite takes precedence (since they
+have a strict superset of the behavior of an order-only prerequisite).
+
+Consider an example where your targets are to be placed in a separate
+directory, and that directory might not exist before @code{make} is
+run.  In this situation, you want the directory to be created before
+any targets are placed into it but, because the timestamps on
+directories change whenever a file is added, removed, or renamed, we
+certainly don't want to rebuild all the targets whenever the
+directory's timestamp changes.  One way to manage this is with
+order-only prerequisites: make the directory an order-only
+prerequisite on all the targets:
+
+@example
+OBJDIR := objdir
+OBJS := $(addprefix $(OBJDIR)/,foo.o bar.o baz.o)
+
+$(OBJDIR)/%.o : %.c
+        $(COMPILE.c) $(OUTPUT_OPTION) $<
+
+all: $(OBJS)
+
+$(OBJS): | $(OBJDIR)
+
+$(OBJDIR):
+        mkdir $(OBJDIR)
+@end example
+
+Now the rule to create the @file{objdir} directory will be run, if
+needed, before any @samp{.o} is built, but no @samp{.o} will be built
+because the @file{objdir} directory timestamp changed.
 
 @node Wildcards, Directory Search, Prerequisite Types, Rules
@@ -2906 +2941 @@
 @xref{Secondary Expansion, ,Secondary Expansion}.
 
-The prerequisites of the special target @code{.SUFFIXES} are the list
-of suffixes to be used in checking for suffix rules.
-@xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
-
 @findex .DELETE_ON_ERROR
 @item .DELETE_ON_ERROR
@@ -2996 +3027 @@
 @cindex parallel execution, overriding
 
-If @code{.NOTPARALLEL} is mentioned as a target, then this invocation of
-@code{make} will be run serially, even if the @samp{-j} option is
-given.  Any recursively invoked @code{make} command will still be run in
-parallel (unless its makefile contains this target).  Any prerequisites
-on this target are ignored.
+If @code{.NOTPARALLEL} is mentioned as a target, then this invocation
+of @code{make} will be run serially, even if the @samp{-j} option is
+given.  Any recursively invoked @code{make} command will still run
+commands in parallel (unless its makefile also contains this target).
+Any prerequisites on this target are ignored.
 @end table
 
@@ -3094 +3125 @@
 if the file's name begins with a dot, no error message is printed.
 This odd behavior is only for compatibility with other implementations
-of @code{make}... you should avoid using it).  Occasionally it is
+of @code{make}@dots{} you should avoid using it).  Occasionally it is
 useful to have the same target invoke multiple commands which are
 defined in different parts of your makefile; you can use
@@ -3653 +3684 @@
 
 @noindent
-Notice how the backslash/newline pair was removed inside the string quoted
-with double quotes (@code{"..."}), but not from the string quoted with single
-quotes (@code{'...'}).  This is the way the default shell (@file{/bin/sh})
-handles backslash/newline pairs.  If you specify a different shell in your
-makefiles it may treat them differently.
+Notice how the backslash/newline pair was removed inside the string
+quoted with double quotes (@code{"@dots{}"}), but not from the string
+quoted with single quotes (@code{'@dots{}'}).  This is the way the
+default shell (@file{/bin/sh}) handles backslash/newline pairs.  If
+you specify a different shell in your makefiles it may treat them
+differently.
 
 Sometimes you want to split a long line inside of single quotes, but
@@ -3943 +3975 @@
 for it to finish before executing the next.  However, the @samp{-j} or
 @samp{--jobs} option tells @code{make} to execute many commands
-simultaneously.@refill
+simultaneously.  You can inhibit parallelism in a particular makefile
+with the @code{.NOTPARALLEL} pseudo-target (@pxref{Special
+Targets,Special Built-in Target Names}).@refill
 
 On MS-DOS, the @samp{-j} option has no effect, since that system doesn't
@@ -8353 +8387 @@
 the special target @code{.SUFFIXES}).  The default suffix list is:
 @code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc},
-@code{.C}, @code{.cpp}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y},
-@code{.l}, @code{.s}, @code{.S}, @code{.mod}, @code{.sym}, @code{.def},
-@code{.h}, @code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo},
-@code{.texi}, @code{.txinfo}, @code{.w}, @code{.ch} @code{.web},
-@code{.sh}, @code{.elc}, @code{.el}.  All of the implicit rules
-described below whose prerequisites have one of these suffixes are
-actually suffix rules.  If you modify the suffix list, the only
-predefined suffix rules in effect will be those named by one or two of
-the suffixes that are on the list you specify; rules whose suffixes fail
-to be on the list are disabled.  @xref{Suffix Rules, ,Old-Fashioned
-Suffix Rules}, for full details on suffix rules.
+@code{.C}, @code{.cpp}, @code{.p}, @code{.f}, @code{.F}, @code{.m},
+@code{.r}, @code{.y}, @code{.l}, @code{.ym}, @code{.lm}, @code{.s},
+@code{.S}, @code{.mod}, @code{.sym}, @code{.def}, @code{.h},
+@code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo}, @code{.texi},
+@code{.txinfo}, @code{.w}, @code{.ch} @code{.web}, @code{.sh},
+@code{.elc}, @code{.el}.  All of the implicit rules described below
+whose prerequisites have one of these suffixes are actually suffix
+rules.  If you modify the suffix list, the only predefined suffix
+rules in effect will be those named by one or two of the suffixes that
+are on the list you specify; rules whose suffixes fail to be on the
+list are disabled.  @xref{Suffix Rules, ,Old-Fashioned Suffix Rules},
+for full details on suffix rules.
 
 @table @asis
@@ -8694 +8729 @@
 @pindex cc
 
-@item CO
-@vindex CO
-Program for checking out files from RCS; default @samp{co}.
-@pindex cc
-
 @item CXX
 @vindex CXX
 Program for compiling C++ programs; default @samp{g++}.
 @pindex g++
-
-@item CO
-@vindex CO
-Program for extracting a file from RCS; default @samp{co}.
-@pindex co
 
 @item CPP
@@ -8720 +8745 @@
 @pindex f77
 
+@item M2C
+@vindex M2C
+Program to use to compile Modula-2 source code; default @samp{m2c}.
+@pindex m2c
+
+@item PC
+@vindex PC
+Program for compiling Pascal programs; default @samp{pc}.
+@pindex pc
+
+@item CO
+@vindex CO
+Program for extracting a file from RCS; default @samp{co}.
+@pindex co
+
 @item GET
 @vindex GET
@@ -8739 +8779 @@
 Program to use to run lint on source code; default @samp{lint}.
 @pindex lint
-
-@item M2C
-@vindex M2C
-Program to use to compile Modula-2 source code; default @samp{m2c}.
-@pindex m2c
-
-@item PC
-@vindex PC
-Program for compiling Pascal programs; default @samp{pc}.
-@pindex pc
 
 @item MAKEINFO