Import bmake-20130123vendor/NetBSD/bmake/20130123

Approved by:	marcel (mentor)

1 files changed, 27 insertions, 14 deletions

diff --git a/bmake.cat1 b/bmake.cat1
index 2d54ee2f89cf..7800726ccf60 100644
--- a/bmake.cat1
+++ b/bmake.cat1
@@ -284,6 +284,32 @@ SSHHEELLLL CCOOMMMMAANNDDSS
      line of a script.  A `--' causes any non-zero exit status of the command
      line to be ignored.
 
+     When bbmmaakkee is run in jobs mode with --jj _m_a_x___j_o_b_s, the entire script for
+     the target is fed to a single instance of the shell.
+
+     In compatibility (non-jobs) mode, each command is run in a separate
+     process.  If the command contains any shell meta characters
+     (`#=|^(){};&<>*?[]:$`\\n') it will be passed to the shell, otherwise
+     bbmmaakkee will attempt direct execution.
+
+     Since bbmmaakkee will chdir(2) to `_._O_B_J_D_I_R' before executing any targets, each
+     child process starts with that as its current working directory.
+
+     Makefiles should be written so that the mode of bbmmaakkee operation does not
+     change their behavior.  For example, any command which needs to use
+     ``cd'' or ``chdir'', without side-effect should be put in parenthesis:
+
+
+           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`
+
 VVAARRIIAABBLLEE AASSSSIIGGNNMMEENNTTSS
      Variables in make are much like variables in the shell, and, by tradi-
      tion, consist of all upper-case letters.
@@ -1293,19 +1319,6 @@ CCOOMMPPAATTIIBBIILLIITTYY
      stops them being treated as syntax, and removes some obscure problems
      using them in .if statements.
 
-     Unlike other bbmmaakkee 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 tar-
-     get commands change the current working directory using ``cd'' or
-     ``chdir''.  To be compatible with Makefiles that do this, one can use --BB
-     to disable this behavior.
-
-     In compatibility mode, each command is run in a separate process.  If the
-     command contains any shell meta characters (`#=|^(){};&<>*?[]:$`\\n') it
-     will be passed to the shell, otherwise bbmmaakkee will attempt direct execu-
-     tion.
-
 SSEEEE AALLSSOO
      mkdep(1)
 
@@ -1327,4 +1340,4 @@ BBUUGGSS
 
      There is no way of escaping a space character in a filename.
 
-NetBSD 5.1                      October 8, 2012                     NetBSD 5.1
+NetBSD 5.1                     January 23, 2013                     NetBSD 5.1