From 202fdd64c869eb7e1d6084a10fe93f164aa4cedb Mon Sep 17 00:00:00 2001
From: Evan Martin <martine@danga.com>
Date: Wed, 16 Dec 2015 08:44:23 -0800
Subject: add a section to the manual discussing the command= variable

This includes a mention of using cmd /c on Windows.
This would have helped on issue #1070 for example.
---
 doc/manual.asciidoc | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc
index 003c71e..4d0727e 100644
--- a/doc/manual.asciidoc
+++ b/doc/manual.asciidoc
@@ -778,11 +778,9 @@ A `rule` block contains a list of `key = value` declarations that
 affect the processing of the rule.  Here is a full list of special
 keys.
 
-`command` (_required_):: the command line to run.  This string (after
-  $variables are expanded) is passed directly to `sh -c` without
-  interpretation by Ninja. Each `rule` may have only one `command`
-  declaration. To specify multiple commands use `&&` (or similar) to
-  concatenate operations.
+`command` (_required_):: the command line to run.  Each `rule` may
+  have only one `command` declaration. See <<ref_rule_command,the next
+  section>> for more details on quoting and executing multiple commands.
 
 `depfile`:: path to an optional `Makefile` that contains extra
   _implicit dependencies_ (see <<ref_dependencies,the reference on
@@ -850,6 +848,27 @@ rule link
 build myapp.exe: link a.obj b.obj [possibly many other .obj files]
 ----
 
+[[ref_rule_command]]
+Interpretation of the `command` variable
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Fundamentally, command lines behave differently on Unixes and Windows.
+
+On Unixes, commands are arrays of arguments.  The Ninja `command`
+variable is passed directly to `sh -c`, which is then responsible for
+interpreting that string into an argv array.  Therefore the quoting
+rules are those of the shell, and you can use all the normal shell
+operators, like `&&` to chain multiple commands, or `VAR=value cmd` to
+set environment variables.
+
+On Windows, commands are strings, so Ninja passes the `command` string
+directly to `CreateProcess`.  (In the common case of simply executing
+a compiler this means there is less overhead.)  Consequently the
+quoting rules are deterimined by the called program, which on Windows
+are usually provided by the C library.  If you need shell
+interpretation of the command (such as the use of `&&` to chain
+multiple commands), make the command execute the Windows shell by
+prefixing the command with `cmd /c`.
+
 [[ref_dependencies]]
 Build dependencies
 ~~~~~~~~~~~~~~~~~~
@@ -947,4 +966,3 @@ Variable declarations indented in a `build` block are scoped to the
 
 5. Variables from the file that included that file using the
    `subninja` keyword.
-
-- 
cgit v1.2.1