Module Name: src
Committed By: dholland
Date: Sun Sep 14 03:13:49 UTC 2014
Modified Files:
src/usr.bin/make: make.1
Log Message:
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.
To generate a diff of this commit:
cvs rdiff -u -r1.238 -r1.239 src/usr.bin/make/make.1
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/usr.bin/make/make.1
diff -u src/usr.bin/make/make.1:1.238 src/usr.bin/make/make.1:1.239
--- src/usr.bin/make/make.1:1.238 Tue Sep 9 06:41:56 2014
+++ src/usr.bin/make/make.1 Sun Sep 14 03:13:49 2014
@@ -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 @@ The value
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,43 +489,45 @@ 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
+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:
+.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} $@)
+ @(cd ${.CURDIR} && ${MAKE} $@)
@echo Back in `pwd`
ensure-one-shell-regardless-of-mode:
@echo Building $@ in `pwd`; \\
- (cd ${.CURDIR} && ${.MAKE} $@); \\
+ (cd ${.CURDIR} && ${MAKE} $@); \\
echo Back in `pwd`
.Ed
+.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.
.Sh VARIABLE ASSIGNMENTS
Variables in make are much like variables in the shell, and, by tradition,
consist of all upper-case letters.
