[src/trunk]: src/usr.bin/make Improvements pertaining to shell commands and c...

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

details:   https://anonhg.NetBSD.org/src/rev/b05d6b1fd6e4
branches:  trunk
changeset: 332287:b05d6b1fd6e4
user:      dholland <dholland%NetBSD.org@localhost>
date:      Sun Sep 14 03:13:49 2014 +0000

description:
Improvements pertaining to shell commands and chdir. Some of this
appeared in the PR 49085 changes, even though it's not actually
relevant there except tangentially. However, I've reworked most of
that for clarity and added some more.

diffstat:

 usr.bin/make/make.1 |  74 +++++++++++++++++++++++++++++++---------------------
 1 files changed, 44 insertions(+), 30 deletions(-)

diffs (113 lines):

diff -r ca20d8e36c1a -r b05d6b1fd6e4 usr.bin/make/make.1
--- a/usr.bin/make/make.1       Sun Sep 14 02:32:51 2014 +0000
+++ b/usr.bin/make/make.1       Sun Sep 14 03:13:49 2014 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: make.1,v 1.238 2014/09/09 06:41:56 dholland Exp $
+.\"    $NetBSD: make.1,v 1.239 2014/09/14 03:13:49 dholland Exp $
 .\"
 .\" Copyright (c) 1990, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -441,17 +441,29 @@
 need not necessarily be used to describe existing files.
 Expansion is in directory order, not alphabetically as done in the shell.
 .Sh SHELL COMMANDS
-Each target may have associated with it a series of shell commands, normally
+Each target may have associated with it one or more lines of shell
+commands, normally
 used to create the target.
-Each of the commands in this script
+Each of the lines in this script
 .Em must
 be preceded by a tab.
-While any target may appear on a dependency line, only one of these
-dependencies may be followed by a creation script, unless the
+(For historical reasons, spaces are not accepted.)
+While targets can appear in many dependency lines if desired, by
+default only one of these rules may be followed by a creation
+script.
+If the
 .Ql Ic \&::
-operator is used.
+operator is used, however, all rules may include scripts and the
+scripts are executed in the order found.
 .Pp
-If the first characters of the command line are any combination of
+Each line is treated as a separate shell command, unless the end of
+line is escaped with a backslash
+.Pq Ql \e
+in which case that line and the next are combined.
+.\" The escaped newline is retained and passed to the shell, which
+.\" normally ignores it.
+.\" However, the tab at the beginning of the following line is removed.
+If the first characters of the command are any combination of
 .Ql Ic @ ,
 .Ql Ic + ,
 or
@@ -477,14 +489,37 @@
 .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
+it will be passed to the shell; otherwise
 .Nm
 will attempt direct execution.
 .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 potentially changing the directory for subsequent commands
+should be put in parentheses so it executes in a subshell.
+To force the use of one shell, escape the line breaks so as to make
+the whole script one command.
+For example:
+.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
+.Pp
 Since
 .Nm
 will
@@ -493,27 +528,6 @@
 .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.