From 7923d736c108cf19e15aa53f5a3fa30582530abb Mon Sep 17 00:00:00 2001
From: David 'Digit' Turner <digit+github@google.com>
Date: Tue, 15 Feb 2022 12:38:58 +0100
Subject: Document the `msvc` tool

---
 doc/manual.asciidoc | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc
index 9e2bec5..00b293c 100644
--- a/doc/manual.asciidoc
+++ b/doc/manual.asciidoc
@@ -312,6 +312,37 @@ file. _Available since Ninja 1.10._
 to pass to +ninja -t targets rule _name_+ or +ninja -t compdb+. Adding the `-d`
 flag also prints the description of the rules.
 
+`msvc`:: Available on Windows hosts only.
+Helper tool to invoke the `cl.exe` compiler with a pre-defined set of
+environment variables, as in:
++
+----
+ninja -t msvc -e ENVFILE -- cl.exe <arguments>
+----
++
+Where `ENVFILE` is a binary file that contains an environment block suitable
+for CreateProcessA() on Windows (i.e. a series of zero-terminated strings that
+look like NAME=VALUE, followed by an extra zero terminator). Note that this uses
+the local codepage encoding.
+
+This tool also supports a deprecated way of parsing the compiler's output when
+the `/showIncludes` flag is used, and generating a GCC-compatible depfile from it.
++
+---
+ninja -t msvc -o DEPFILE [-p STRING] -- cl.exe /showIncludes <arguments>
+---
++
+
+When using this option, `-p STRING` can be used to pass the localized line prefix
+that `cl.exe` uses to output dependency information. For English-speaking regions
+this is `"Note: including file: "` without the double quotes, but will be different
+for other regions.
+
+Note that Ninja supports this natively now, with the use of `deps = msvc` and
+`msvc_deps_prefix` in Ninja files. Native support also avoids launching an extra
+tool process each time the compiler must be called, which can speed up builds
+noticeably on Windows.
+
 `wincodepage`:: Available on Windows hosts (_since Ninja 1.11_).
 Prints the Windows code page whose encoding is expected in the build file.
 The output has the form:
-- 
cgit v1.2.1


From 66b05496ff0ef6114e3534418c970dd92d34accb Mon Sep 17 00:00:00 2001
From: David 'Digit' Turner <digit+github@google.com>
Date: Fri, 18 Feb 2022 15:05:10 +0100
Subject: Ensure the `msvc` tool is built in all Win32 Ninja binaries.

It was only previously available when Ninja was built when
`_MSVC` is defined (i.e. when compiling with the Microsoft
compiler of with `clang-cl`).

+ Tag the tool as DEPRECATED
---
 src/ninja.cc | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/ninja.cc b/src/ninja.cc
index 71dea21..ad0912e 100644
--- a/src/ninja.cc
+++ b/src/ninja.cc
@@ -52,7 +52,7 @@
 
 using namespace std;
 
-#ifdef _MSC_VER
+#ifdef _WIN32
 // Defined in msvc_helper_main-win32.cc.
 int MSVCHelperMain(int argc, char** argv);
 
@@ -449,7 +449,7 @@ int NinjaMain::ToolBrowse(const Options*, int, char**) {
 }
 #endif
 
-#if defined(_MSC_VER)
+#if defined(_WIN32)
 int NinjaMain::ToolMSVC(const Options* options, int argc, char* argv[]) {
   // Reset getopt: push one argument onto the front of argv, reset optind.
   argc++;
@@ -1043,8 +1043,8 @@ const Tool* ChooseTool(const string& tool_name) {
   static const Tool kTools[] = {
     { "browse", "browse dependency graph in a web browser",
       Tool::RUN_AFTER_LOAD, &NinjaMain::ToolBrowse },
-#if defined(_MSC_VER)
-    { "msvc", "build helper for MSVC cl.exe (EXPERIMENTAL)",
+#ifdef _WIN32
+    { "msvc", "build helper for MSVC cl.exe (DEPRECATED)",
       Tool::RUN_AFTER_FLAGS, &NinjaMain::ToolMSVC },
 #endif
     { "clean", "clean built files",
-- 
cgit v1.2.1