more updates to building & installation

BUILDING.md

@@ -90,7 +90,8 @@ with something else than `bazel` (e.g. `cmake`).
 # Build from source
 
 In the C++ world, there's no "standard" build system that would work for in all supported use cases and on all supported platforms.
-Therefore, gRPC supports several major build systems, which should satisfy most users.
+Therefore, gRPC supports several major build systems, which should satisfy most users. Depending on your needs
+we recommend building using `bazel` or `cmake`.
 
 ## Building with bazel (recommended)
 
@@ -157,7 +158,8 @@ installed to be able to compile the C/C++ sources.
 
 ## Building with make (on UNIX systems)
 
-NOTE: `make` used to be gRPC's default build system, but we're no longer recommending it. Use should use `bazel` or `cmake` instead.
+NOTE: `make` used to be gRPC's default build system, but we're no longer recommending it. You should use `bazel` or `cmake` instead.
+While still supported, make should only be used inside the gRPC repository (to satisfy some project-internal needs)
 
 From the grpc repository root
 ```sh

src/cpp/README.md

@@ -30,11 +30,23 @@ To add gRPC as a dependency in bazel:
   grpc_deps()
   ```
 
-NOTE: currently bazel is only supported for building gRPC on Linux.
+## cmake
+
+`cmake` is your best option if you cannot use bazel. It supports building on Linux, MacOS and Windows (official support) but also has a good chance of working on other platforms (no promises!). `cmake` has good
+support for crosscompiling and can be used for targeting Android platform.
+
+If your project is using cmake, there are several ways to add gRPC dependency.
+- install gRPC via cmake first and then locate it with `find_package(gRPC CONFIG)`. [Example](../../examples/cpp/helloworld/CMakeLists.txt)
+- via cmake's `ExternalProject_Add` using a technique called "superbuild". [Example](../../examples/cpp/helloworld/cmake_externalproject/CMakeLists.txt)
+- add gRPC source tree to your project (preferably as a git submodule) and add it to your cmake project with `add_subdirectory`. [Example](../../examples/cpp/helloworld/CMakeLists.txt)
+
+If your project is not using cmake (e.g. you're using `make` directly), you can first install gRPC C++ using cmake,
+and have your non-cmake project rely on the `pkgconfig` files which are provided by gRPC installation. [Example](../../test/distrib/cpp/run_distrib_test_cmake_pkgconfig.sh)
 
 ## make
 
-Currently the default choice for building on UNIX based systems is `make`.
+The default choice for building on UNIX based systems used to be `make`, but we are no longer recommending it.
+You should use `bazel` or `cmake` instead.
 
 To install gRPC for C++ on your system using `make`, follow the [Building gRPC C++](../../BUILDING.md)
 instructions to build from source and then install locally using `make install`.
@@ -44,16 +56,6 @@ and the C++ gRPC plugin for `protoc`.
 WARNING: After installing with `make install` there is no easy way to uninstall, which can cause issues
 if you later want to remove the grpc and/or protobuf installation or upgrade to a newer version.
 
-## cmake
-
-`cmake` is the default build option on Windows, but also works on Linux, MacOS. `cmake` has good
-support for crosscompiling and can be used for targeting Android platform.
-
-If your project is using cmake, there are several ways to add gRPC dependency.
-- install gRPC via cmake first and then locate it with `find_package(gRPC CONFIG)`. [Example](../../examples/cpp/helloworld/CMakeLists.txt)
-- via cmake's `ExternalProject_Add` using a technique called "superbuild". [Example](../../examples/cpp/helloworld/cmake_externalproject/CMakeLists.txt)
-- add gRPC source tree to your project (preferably as a git submodule) and add it to your cmake project with `add_subdirectory`. [Example](../../examples/cpp/helloworld/CMakeLists.txt)
-
 ## Packaging systems
 
 We do not officially support any packaging system for C++, but there are some community-maintained packages that are kept up-to-date