[src/trunk]: src/usr.bin/make In SHELL COMMANDS section, provide some clues a...

[sjg <sjg%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/22171a06d92b
branches:  trunk
changeset: 784394:22171a06d92b
user:      sjg <sjg%NetBSD.org@localhost>
date:      Sun Jan 27 18:52:01 2013 +0000

description:
In SHELL COMMANDS section, provide some clues about different
behavior in jobs vs non-jobs mode.
Move the comment about when shell is skipped to this discussion
from COMPATABILITY.
Remove the incorrect statement about default mode being somehow
neither jobs mode or compat mode (it is compat mode).

diffstat:

 usr.bin/make/make.1 |  70 ++++++++++++++++++++++++++++++++++------------------
 1 files changed, 46 insertions(+), 24 deletions(-)

diffs (98 lines):

diff -r d289cea02eec -r 22171a06d92b usr.bin/make/make.1
--- a/usr.bin/make/make.1       Sun Jan 27 18:31:31 2013 +0000
+++ b/usr.bin/make/make.1       Sun Jan 27 18:52:01 2013 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: make.1,v 1.209 2012/10/08 15:09:48 christos Exp $
+.\"    $NetBSD: make.1,v 1.210 2013/01/27 18:52:01 sjg Exp $
 .\"
 .\" Copyright (c) 1990, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"    from: @(#)make.1        8.4 (Berkeley) 3/19/94
 .\"
-.Dd October 8, 2012
+.Dd January 23, 2013
 .Dt MAKE 1
 .Os
 .Sh NAME
@@ -468,6 +468,50 @@
 A
 .Ql Ic \-
 causes any non-zero exit status of the command line to be ignored.
+.Pp
+When
+.Nm
+is run in jobs mode with
+.Fl j Ar max_jobs ,
+the entire script for the target is fed to a
+single instance of the shell.
+.Pp
+In compatibility (non-jobs) mode, each command is run in a separate process.
+If the command contains any shell meta characters
+.Pq Ql #=|^(){};&<>*?[]:$`\e\en
+it will be passed to the shell, otherwise
+.Nm
+will attempt direct execution.
+.Pp
+Since
+.Nm
+will
+.Xr chdir 2
+to
+.Ql Va .OBJDIR
+before executing any targets, each child process
+starts with that as its current working directory.
+.Pp
+Makefiles should be written so that the mode of
+.Nm
+operation does not change their behavior.
+For example, any command which needs to use
+.Dq cd
+or
+.Dq chdir ,
+without side-effect should be put in parenthesis:
+.Bd -literal -offset indent
+
+avoid-chdir-side-effects:
+       @echo Building $@ in `pwd`
+       @(cd ${.CURDIR} && ${.MAKE} $@)
+       @echo Back in `pwd`
+
+ensure-one-shell-regardless-of-mode:
+       @echo Building $@ in `pwd`; \\
+       (cd ${.CURDIR} && ${.MAKE} $@); \\
+       echo Back in `pwd`
+.Ed
 .Sh VARIABLE ASSIGNMENTS
 Variables in make are much like variables in the shell, and, by tradition,
 consist of all upper-case letters.
@@ -2027,28 +2071,6 @@
 so that they still appear to be variable expansions.
 In particular this stops them being treated as syntax, and removes some
 obscure problems using them in .if statements.
-.Pp
-Unlike other
-.Nm
-programs, this implementation by default executes all commands for a given
-target using a single shell invocation.
-This is done for both efficiency and to simplify error handling in remote
-command invocations.
-Typically this is transparent to the user, unless the target commands change
-the current working directory using
-.Dq cd
-or
-.Dq chdir .
-To be compatible with Makefiles that do this, one can use
-.Fl B
-to disable this behavior.
-.Pp
-In compatibility mode, each command is run in a separate process.
-If the command contains any shell meta characters
-.Pq Ql #=|^(){};&<>*?[]:$`\e\en
-it will be passed to the shell, otherwise
-.Nm
-will attempt direct execution.
 .Sh SEE ALSO
 .Xr mkdep 1
 .Sh HISTORY