Improve documentation for building with CMake

BUILDING.md

@@ -116,7 +116,9 @@ $ bazel test --config=dbg //test/...
 NOTE: If you are gRPC maintainer and you have access to our test cluster, you should use the our [gRPC's Remote Execution environment](tools/remote_build/README.md)
 to get significant improvement to the build and test speed (and a bunch of other very useful features).
 
-## CMake: Linux/Unix, Using Make
+## Building with CMake
+
+### Linux/Unix, Using Make
 
 Run from grpc directory after cloning the repo with --recursive or updating submodules.
 ```
@@ -128,7 +130,7 @@ $ make
 
 If you want to build shared libraries (`.so` files), run `cmake` with `-DBUILD_SHARED_LIBS=ON`.
 
-## Building with CMake: Windows, Using Visual Studio 2015 or 2017 (can only build with OPENSSL_NO_ASM).
+### Windows, Using Visual Studio 2015 or 2017
 
 When using the "Visual Studio" generator,
 cmake will generate a solution (`grpc.sln`) that contains a VS project for
@@ -143,7 +145,9 @@ you will be able to browse and build the code.
 > cmake --build . --config Release
 ```
 
-## Building with CMake: Windows, Using Ninja (faster build, supports boringssl's assembly optimizations).
+If you want to build DLLs, run `cmake` with `-DBUILD_SHARED_LIBS=ON`.
+
+### Windows, Using Ninja (faster build).
 
 Please note that when using Ninja, you will still need Visual C++ (part of Visual Studio)
 installed to be able to compile the C/C++ sources.
@@ -156,7 +160,67 @@ installed to be able to compile the C/C++ sources.
 > cmake --build .
 ```
 
-## Building with make (on UNIX systems)
+If you want to build DLLs, run `cmake` with `-DBUILD_SHARED_LIBS=ON`.
+
+### Dependency management
+
+gRPC's CMake build system provides two modes for handling dependencies.
+* module - build dependencies alongside gRPC.
+* package - use external copies of dependencies that are already available
+on your system.
+
+This behavior is controlled by the `gRPC_<depname>_PROVIDER` CMake variables,
+ie `gRPC_CARES_PROVIDER`.
+
+### Install after build
+
+Perform the following steps to install gRPC using CMake.
+* Set `gRPC_INSTALL` to `ON`
+* Build the `install` target
+
+The install destination is controlled by the
+[`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) variable.
+
+If you are running CMake v3.13 or newer you can build gRPC's dependencies
+in "module" mode and install them alongside gRPC in a single step.
+[Example](test/distrib/cpp/run_distrib_test_cmake_module_install.sh)
+
+If you are using an older version of gRPC, you will need to select "package"
+mode (rather than "module" mode) for the dependencies.
+This means you will need to have external copies of these libraries available
+on your system.
+```
+$ cmake .. -DgRPC_CARES_PROVIDER=package    \
+           -DgRPC_PROTOBUF_PROVIDER=package \
+           -DgRPC_SSL_PROVIDER=package      \
+           -DgRPC_ZLIB_PROVIDER=package
+$ make
+$ make install
+```
+[Example](test/distrib/cpp/run_distrib_test_cmake.sh)
+
+### Cross-compiling
+
+You can use CMake to cross-compile gRPC for another architecture. In order to
+do so, you will first need to build `protoc` and `grpc_cpp_plugin`
+for the host architecture. These tools are used during the build of gRPC, so
+we need copies of executables that can be run natively.
+
+You will likely need to install the toolchain for the platform you are
+targeting for your cross-compile. Once you have done so, you can write a
+toolchain file to tell CMake where to find the compilers and system tools
+that will be used for this build.
+
+This toolchain file is specified to CMake by setting the `CMAKE_TOOLCHAIN_FILE`
+variable.
+```
+$ cmake .. -DCMAKE_TOOLCHAIN_FILE=path/to/file
+$ make
+```
+
+[Cross-compile example](test/distrib/cpp/run_distrib_test_raspberry_pi.sh)
+
+## Building with make on UNIX systems (deprecated)
 
 NOTE: `make` used to be gRPC's default build system, but we're no longer recommending it. You should use `bazel` or `cmake` instead. The `Makefile` is only intended for internal usage and is not meant for public consumption.