diff --git a/BUILDING.md b/BUILDING.md index fc9e18173f0..30e6dcd1ddd 100644 --- a/BUILDING.md +++ b/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__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.