summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorNico Weber <nicolasweber@gmx.de>2015-12-29 15:08:23 (GMT)
committerNico Weber <nicolasweber@gmx.de>2015-12-29 15:08:23 (GMT)
commita99dcc914c9f12790ccb774a1e68e97bae7d4b79 (patch)
tree08693a87849f33aab79690b9896f05506232223a
parentda68d8998dfbc8dfa5455642b3ca287f8a3dbceb (diff)
parent202fdd64c869eb7e1d6084a10fe93f164aa4cedb (diff)
downloadNinja-a99dcc914c9f12790ccb774a1e68e97bae7d4b79.zip
Ninja-a99dcc914c9f12790ccb774a1e68e97bae7d4b79.tar.gz
Ninja-a99dcc914c9f12790ccb774a1e68e97bae7d4b79.tar.bz2
Merge pull request #1074 from ninja-build/manual-command
add a section to the manual discussion the command= variable
-rw-r--r--doc/manual.asciidoc30
1 files changed, 24 insertions, 6 deletions
diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc
index 6aef164..ab5c945 100644
--- a/doc/manual.asciidoc
+++ b/doc/manual.asciidoc
@@ -781,11 +781,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
@@ -853,6 +851,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
~~~~~~~~~~~~~~~~~~
@@ -953,4 +972,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.
-