Merge pull request #11462 from jtattermusch/improve_windows_build_docs

Mark pre-generated Visual Studio projects as deprecated, recommend cmake

2 files changed, 27 insertions, 4 deletions

diff --git a/INSTALL.md b/INSTALL.md
index 5406fec84d..9526a8637b 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -89,17 +89,19 @@ gRPC C Core library.
 There are several ways to build under Windows, of varying complexity depending
 on experience with the tools involved.
 
-### Pre-generated Visual Studio solution
 
-The pre-generated VS projects & solution are checked into the repository under the [vsprojects](/vsprojects) directory.
 
-### Building using CMake (with BoringSSL)
+### Building using CMake (RECOMMENDED)
+
+Builds gRPC C and C++ with boringssl.
 - Install [CMake](https://cmake.org/download/).
 - Install [Active State Perl](http://www.activestate.com/activeperl/) (`choco install activeperl`)
 - Install [Ninja](https://ninja-build.org/) (`choco install ninja`)
 - Install [Go](https://golang.org/dl/) (`choco install golang`)
 - Install [yasm](http://yasm.tortall.net/) and add it to `PATH` (`choco install yasm`)
 - Run these commands in the repo root directory
+
+Using Ninja (faster build, supports boringssl's assembly optimizations)
 ```
 > md .build
 > cd .build
@@ -107,7 +109,14 @@ The pre-generated VS projects & solution are checked into the repository under t
 > cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release
 > cmake --build .
 ```
-NOTE: Currently you can only use Ninja to build using cmake on Windows (because of the boringssl dependency).
+
+Using Visual Studio 2015 (can only build with OPENSSL_NO_ASM)
+```
+> md .build
+> cd .build
+> cmake .. -G "Visual Studio 14 2015" -DCMAKE_BUILD_TYPE=Release
+> cmake --build .
+```
 
 ### msys2 (with mingw)
 
@@ -131,3 +140,9 @@ MINGW64$ make
 
 NOTE: While most of the make targets are buildable under Mingw, some haven't been ported to Windows yet
 and may fail to build (mostly trying to include POSIX headers not available on Mingw).
+
+### Pre-generated Visual Studio solution (DEPRECATED)
+
+*WARNING: This used to be the recommended way to build on Windows, but because of significant limitations (hard to build dependencies including boringssl, .proto codegen is hard to support, ..), it is no longer recommended. Use cmake to build on Windows instead.*
+
+The pre-generated VS projects & solution are checked into the repository under the [vsprojects](/vsprojects) directory.
diff --git a/vsprojects/README.md b/vsprojects/README.md
index 1f0cdc24ba..4b6608ba93 100644
--- a/vsprojects/README.md
+++ b/vsprojects/README.md
@@ -1,5 +1,13 @@
 # Pre-generated MS Visual Studio project & solution files
 
+**DEPRECATED, please use cmake instead (it can generate Visual Studio projects for you). We will continue providing pre-generated VS projects for a while, but we will likely get rid of them entirely at some point.**
+
+**Pre-generated MS Visual Studio projects used to be the recommended way to build on Windows, but there were some limitations:**
+- **hard to build dependencies, expecially boringssl (deps usually support cmake quite well)**
+- **the nuget-based openssl & zlib dependencies are hard to maintain and update. We've received issues indicating that they are flawed.**
+- **.proto codegen is hard to support in Visual Studio directly (but we have a pretty decent support in cmake)**
+- **It's a LOT of generated files. We prefer not to have too much generated code in our github repo.**
+
 Versions 2013 and 2015 are both supported. You can use [their respective
 community
 editions](https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx).