Update docs: Ninja now required to build with MSVC (#48)

.appveyor.yml

@@ -26,9 +26,9 @@ install:
  - if not %target% == %host% rustup target add %target%
  - rustc -vV && cargo -vV
 
- # Because that MSBUild does not support path longer than MAX_PATH
- # (https://github.com/Microsoft/msbuild/issues/53),
- # we use ninja to build.
+ # Ninja is required to build with Visual Studio because MSBuild does not
+ # support paths longer than MAX_PATH
+ # (https://github.com/Microsoft/msbuild/issues/53).
  - set NINJA_URL="https://github.com/ninja-build/ninja/releases/download/v1.9.0/ninja-win.zip"
  - appveyor DownloadFile %NINJA_URL% -FileName ninja.zip
  - 7z x ninja.zip -oC:\projects\deps\ninja > nul

README.md

@@ -103,30 +103,22 @@ which requires `git`, `cmake`, and `python` existing in the `PATH`.
 
 To build your own libshaderc for the shaderc-sys crate, the following tools must be installed and available on `PATH`:
 - [CMake](https://cmake.org/)
+- [Ninja](https://github.com/ninja-build/ninja/releases) (required on windows-msvc, but optional on all other platforms)
 - [Git](https://git-scm.com/)
 - [Python](https://www.python.org/) (works with both Python 2.x and 3.x, on windows the executable must be named `python.exe`)
 - a C++11 compiler
 
-Additionally, the build script can auto detect and use the following if they are on `PATH`:
-- [Ninja](https://github.com/ninja-build/ninja/releases)
-
 These requirements can be either installed with your favourite package manager or with installers
 from the projects' websites. Below are some example ways to get setup.
 
 ### windows-msvc Example Setup
 
 1. `rustup default stable-x86_64-pc-windows-msvc`
 2. Install [Build Tools for Visual Studio 2017](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017). If you have already been using this toolchain then its probably already installed.
-3. Install [msys2](http://www.msys2.org/), following ALL of the instructions.
-4. Then in the msys2 terminal run: `pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-python2`
-5. Add the msys2 mingw64 binary path to the PATH environment variable.
-
-NOTE: On Windows if building with MSBuild (the default), it may fail because of
-file path too long. That is a [limitation of MSBuild](https://github.com/Microsoft/msbuild/issues/53).
-You can work around either by set the target directory to a shallower one using
-`cargo --target-dir`, or [download Ninja](https://github.com/ninja-build/ninja/releases)
-and make it accessible on `PATH`. The build script will automatically detect
-and use Ninja instead of MSBuild.
+3. Install [Ninja](https://github.com/ninja-build/ninja/releases) (download ninja-win.zip and extract ninja.exe somewhere suitable).
+4. Install [msys2](http://www.msys2.org/), following ALL of the instructions.
+5. Then in the msys2 terminal run: `pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-python2`
+6. Edit the PATH environment variable to include the path where you extracted ninja.exe, and the msys2 mingw64 binary path.
 
 ### windows-gnu Example Setup
 
@@ -139,10 +131,11 @@ Steps 1 and 2 are to workaround https://github.com/rust-lang/rust/issues/49078 b
 3. Run the command: `rustup default stable-x86_64-pc-windows-msvc`
 4. Run the command: `rustup target install x86_64-pc-windows-gnu`
 5. Install [Build Tools for Visual Studio 2017](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017). If you have already been using this toolchain then its probably already installed.
-6. Install [msys2](http://www.msys2.org/), following ALL of the instructions.
-7. Then in the msys2 terminal run: `pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-make mingw-w64-x86_64-python2`
-8. Add the msys2 mingw64 binary path to the PATH environment variable.
-9. Any cargo command that builds the project needs to include `--target x86_64-pc-windows-gnu` e.g. to run: `cargo run --target x86_64-pc-windows-gnu`
+6. Install [Ninja](https://github.com/ninja-build/ninja/releases) (download ninja-win.zip and extract ninja.exe somewhere suitable).
+7. Install [msys2](http://www.msys2.org/), following ALL of the instructions.
+8. Then in the msys2 terminal run: `pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-make mingw-w64-x86_64-python2`
+9. Edit the PATH environment variable to include the path where you extracted ninja.exe, and the msys2 mingw64 binary path.
+10. Any cargo command that builds the project needs to include `--target x86_64-pc-windows-gnu` e.g. to run: `cargo run --target x86_64-pc-windows-gnu`
 
 ### Linux Example Setup
 

shaderc-sys/src/lib.rs

@@ -40,6 +40,11 @@
 //! 4. If no other option was set or succeeded, shaderc-sys will fall back to
 //! checking out and compiling a copy of Shaderc. This procedure is quite
 //! slow.
+//!
+//! The build script also tries to check whether [Ninja](https://ninja-build.org/)
+//! is available on `PATH`. Ninja is required to build with Visual Studio because
+//! MSBuild does not support paths longer than MAX_PATH. On other platforms,
+//! Ninja is optional but is generally faster than the default build tool.
 
 #![allow(non_camel_case_types)]