Update Clang Windows getting started docs

[rnk]

Summary

• Update the example VS project generation to use VS2017.
• Add docs for generating ninja build files, since they are popular.
• Remove reference to "make update" which no longer exists. Mention the monorepo instead.
• Try to explain gnuwin32/coreutils requirements better.

[smeenai]

clang/www/get_started.html

197 ↗

(On Diff #168159)

Does the Win64 generator automatically imply -Thost=x64?

[steveire]

clang/www/get_started.html

197 ↗

(On Diff #168159)

Nope.

And using "Visual Studio 15 2017 Win64" is deprecated. Use -G "Visual Studio 15 2017" -A x64 instead as per https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2015%202017.html

[STL_MSFT]

clang/www/get_started.html

160 ↗

(On Diff #168159)

This URL redirects to https://cmake.org/download/. (Clang's docs should use HTTPS everywhere possible, especially for self-links.)

164 ↗

(On Diff #168159)

Redirected to https://www.python.org/downloads/.

179 ↗

(On Diff #168159)

Can these be HTTPS? (I had to figure out HTTPS incantations for git clone and git svn init, but I haven't used SVN directly.)

246 ↗

(On Diff #168159)

This assumes the Professional SKU; perhaps the instructions should be for Community?

[zturner]

clang/www/get_started.html

246 ↗

(On Diff #168159)

Would something like %VS2017INSTALLDIR% be even better?

246 ↗

(On Diff #168159)

Granted it assumes 2017, but not as bad as assuming both Professional SKU + default installation path.

[rnk]

• Use https: where possible over http:
• Fix CMake VS generator invocation

[rnk]

clang/www/get_started.html

179 ↗

(On Diff #168159)

These can, but getgnuwin32 is http-only for now I guess. =/

197 ↗

(On Diff #168159)

Thanks, check the new instructions, hopefully they are correct.

246 ↗

(On Diff #168159)

I'll change it, and hopefully users of Professional will understand what "run the appropriate vcvarsall.bat incantation" means.

[rnk]

I'm going to go ahead and commit this. Hopefully it's more accurate and useful than what we have, and we can fix any issues in post.

www/get_started.html

<ol>
   </li>
   <li>Run the testsuite:
   <ul>
     <li><tt>make check-clang</tt></li>
   </ul>
   </li>
 </ol>
 
-<p>If you encounter problems while building Clang, make sure that your LLVM
-checkout is at the same revision as your Clang checkout. LLVM's interfaces
-change over time, and mismatched revisions are not expected to work
-together.</p>
-
 <h3>Simultaneously Building Clang and LLVM:</h3>
 
 <p>Once you have checked out Clang into the llvm source tree it will build along
 with the rest of <tt>llvm</tt>. To build all of LLVM and Clang together all at
 once simply run <tt>make</tt> from the root LLVM directory.</p>
 
-<p><em>Note:</em> Observe that Clang is technically part of a separate
-Subversion repository. As mentioned above, the latest Clang sources are tied to
-the latest sources in the LLVM tree. You can update your toplevel LLVM project
-and all (possibly unrelated) projects inside it with <tt><b>make
-update</b></tt>. This will run <tt>svn update</tt> on all subdirectories related
-to subversion. </p>
+<p>If you encounter problems while building Clang, make sure that your LLVM
+checkout is at the same revision as your Clang checkout. LLVM's interfaces
+change over time, and mismatched revisions are not expected to work
+together. We recommend writing a script to automatically run <tt>svn up</tt> in
+each repository to keep them synchronized. Alternatively, you may consider using
+the unofficial
+<a href="https://llvm.org/docs/GettingStarted.html#for-developers-to-work-with-a-git-monorepo">git monorepo</a>
+which automatically keeps everything in sync at the same revision and lets you
+commit changes atomically across multiple LLVM subprojects.</p>
 
 <h3 id="buildWindows">Using Visual Studio</h3>
 
 <p>The following details setting up for and building Clang on Windows using
 Visual Studio:</p>
 
 <ol>
   <li>Get the required tools:
   <ul>
     <li><b>Subversion</b>.  Source code control program.  Get it from:
-        <a href="http://subversion.apache.org/packages.html">
-        http://subversion.apache.org/packages.html</a></li>
+        <a href="https://subversion.apache.org/packages.html">
+        https://subversion.apache.org/packages.html</a></li>
     <li><b>CMake</b>.  This is used for generating Visual Studio solution and
         project files.  Get it from:
-        <a href="http://www.cmake.org/cmake/resources/software.html">
-        http://www.cmake.org/cmake/resources/software.html</a></li>
-    <li><b>Visual Studio 2013 or later</b></li>
-    <li><b>Python</b>.  This is needed only if you will be running the tests
-        (which is essential, if you will be developing for clang).
-        Get it from:
-        <a href="http://www.python.org/download/">
-        http://www.python.org/download/</a></li>
+        <a href="https://cmake.org/download/">
+        https://cmake.org/download/</a></li>
+    <li><b>Visual Studio 2015 or later</b></li>
+    <li><b>Python</b>.  It is used to run the clang test suite. Get it from:
+        <a href="https://www.python.org/download/">
+        https://www.python.org/download/</a></li>
     <li><b>GnuWin32 tools</b>
-        These are also necessary for running the tests.
-        (Note that the grep from MSYS or Cygwin doesn't work with the tests
-        because of embedded double-quotes in the search strings.  The GNU
-        grep does work in this case.)
-        Get them from <a href="http://getgnuwin32.sourceforge.net/">
+        The Clang and LLVM test suite use various GNU core utilities, such as
+        <tt>grep</tt>, <tt>sed</tt>, and <tt>find</tt>. The gnuwin32 packages
+        are the oldest and most well-tested way to get these tools. However, the
+        MSys utilities provided by git for Windows have been known to work.
+        Cygwin has worked in the past, but is not well tested.
+        If you don't already have the core utilies from some other source, get
+        gnuwin32 from <a href="http://getgnuwin32.sourceforge.net/">
         http://getgnuwin32.sourceforge.net/</a>.</li>
   </ul>
   </li>
 
   <li>Check out LLVM:
   <ul>
-    <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
+    <li><tt>svn co https://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
   </ul>
   </li>
   <li>Check out Clang:
   <ul>
      <li><tt>cd llvm\tools</tt>
-     <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li>
+     <li><tt>svn co https://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li>
   </ul>
   <p><em>Note</em>:  Some Clang tests are sensitive to the line endings.  Ensure
      that checking out the files does not convert LF line endings to CR+LF.
      If you use git-svn, make sure your <tt>core.autocrlf</tt> setting is false.</p>
   </li>
   <li>Run CMake to generate the Visual Studio solution and project files:
   <ul>
     <li><tt>cd ..\..</tt>  (back to where you started)</li>
     <li><tt>mkdir build</tt> (for building without polluting the source dir)</li>
     <li><tt>cd build</tt></li>
-    <li>If you are using Visual Studio 2013:  <tt>cmake -G "Visual Studio 12" ..\llvm</tt></li>
-    <li>By default, the Visual Studio project files generated by CMake use the
-     32-bit toolset. If you are developing on a 64-bit version of Windows and
-     want to use the 64-bit toolset, pass the ``-Thost=x64`` flag when
-     generating the Visual Studio solution. This requires CMake 3.8.0 or later.</li>
+    <li>
+      If you are using Visual Studio 2017:
+      <tt>cmake -G "Visual Studio 15 2017" -A x64 -Thost=x64 ..\llvm</tt><br/>
+      <tt>-Thost=x64</tt> is required, since the 32-bit linker will run out of memory.
+    </li>
+    <li>To generate x86 binaries instead of x64, pass <tt>-A Win32</tt>.</li>
     <li>See the <a href="https://www.llvm.org/docs/CMake.html">LLVM CMake guide</a> for
         more information on other configuration options for CMake.</li>
     <li>The above, if successful, will have created an LLVM.sln file in the
        <tt>build</tt> directory.
   </ul>
   </li>
   <li>Build Clang:
   <ul>
     <li>Open LLVM.sln in Visual Studio.</li>
     <li>Build the "clang" project for just the compiler driver and front end, or
       the "ALL_BUILD" project to build everything, including tools.</li>
   </ul>
   </li>
   <li>Try it out (assuming you added llvm/debug/bin to your path).  (See the
     running examples from above.)</li>
   <li>See <a href="hacking.html#testingWindows">
      Hacking on clang - Testing using Visual Studio on Windows</a> for information
      on running regression tests on Windows.</li>
 </ol>
 
 <p>Note that once you have checked out both llvm and clang, to synchronize
 to the latest code base, use the <tt>svn update</tt> command in both the
 llvm and llvm\tools\clang directories, as they are separate repositories.</p>
 
+<h3 id="buildWindowsNinja">Using Ninja alongside Visual Studio</h3>
+
+<p>We recommend that developers who want the fastest incremental builds use the
+<a href="https://ninja-build.org/">Ninja build system</a>. You can use the
+generated Visual Studio project files to edit Clang source code and generate a
+second build directory next to it for running the tests with these steps:</p>
+
+<ol>
+  <li>Check out clang and LLVM as described above</li>
+  <li>Open a developer command prompt with the appropriate environment.
+    <ul>
+      <li>If you open the start menu and search for "Command Prompt", you should
+        see shortcuts created by Visual Studio to do this. To use native x64
+        tools, choose the one titled "x64 Native Tools Command Prompt for VS
+        2017".</li>
+      <li> Alternatively, launch a regular <tt>cmd</tt> prompt and run the
+        appropriate vcvarsall.bat incantation. To get the 2017 x64 tools, this
+        would be:<br/>
+        <tt>"C:\Program Files (x86)\Microsoft Visual
+          Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" x64</tt>
+      </li>
+    </ul>
+  </li>
+  <li><tt>mkdir build_ninja</tt> (or <tt>build</tt>, or use your own
+    organization)</li>
+  <li><tt>cd build_ninja</tt></li>
+  <li><tt>set CC=cl</tt> (necessary to force CMake to choose MSVC over mingw GCC
+    if you have it installed)</li>
+  <li><tt>set CXX=cl</tt></li>
+  <li><tt>cmake -GNinja ..\llvm</tt></li>
+  <li><tt>ninja clang</tt> This will build just clang.</li>
+  <li><tt>ninja check-clang</tt> This will run the clang tests.</li>
+</ol>
+
 <h2 id="driver">Clang Compiler Driver (Drop-in Substitute for GCC)</h2>
 
 <p>The <tt>clang</tt> tool is the compiler driver and front-end, which is
 designed to be a drop-in replacement for the <tt>gcc</tt> command.  Here are
 some examples of how to use the high-level driver:
 </p>
 
 <pre class="code">