Improve documentation for building with CMake

pull/21529/head
Zack Galbreath 5 years ago
parent 8ba63b39c1
commit e3c1ee698d
  1. 80
      BUILDING.md

@ -41,7 +41,7 @@ If you plan to build from source and run tests, install the following as well:
$ brew install gflags
```
*Tip*: when building,
*Tip*: when building,
you *may* want to explicitly set the `LIBTOOL` and `LIBTOOLIZE`
environment variables when running `make` to ensure the version
installed by `brew` is being used:
@ -63,7 +63,7 @@ To prepare for cmake + Microsoft Visual C++ compiler build
# Clone the repository (including submodules)
Before building, you need to clone the gRPC github repository and download submodules containing source code
Before building, you need to clone the gRPC github repository and download submodules containing source code
for gRPC's dependencies (that's done by the `submodule` command or `--recursive` flag). The following commands will clone the gRPC
repository at the latest stable version.
@ -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,12 +130,12 @@ $ 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
cmake will generate a solution (`grpc.sln`) that contains a VS project for
every target defined in `CMakeLists.txt` (+ few extra convenience projects
added automatically by cmake). After opening the solution with Visual Studio
added automatically by cmake). After opening the solution with Visual Studio
you will be able to browse and build the code.
```
> @rem Run from grpc directory after cloning the repo with --recursive or updating submodules.
@ -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.

Loading…
Cancel
Save