BUILDING.md

   1 gRPC C++ - Building from source
   2 ===========================
   3
   4 This document has detailed instructions on how to build gRPC C++ from source. Note that it only covers the build of gRPC itself and is mostly meant for gRPC C++ contributors and/or power users.
   5 Other should follow the user instructions. See the [How to use](https://github.com/grpc/grpc/tree/master/src/cpp#to-start-using-grpc-c) instructions for guidance on how to add gRPC as a dependency to a C++ application (there are several ways and system wide installation is often not the best choice).
   6
   7 # Pre-requisites
   8
   9 ## Linux
  10
  11 ```sh
  12  $ [sudo] apt-get install build-essential autoconf libtool pkg-config
  13 ```
  14
  15 If you plan to build using CMake
  16 ```sh
  17  $ [sudo] apt-get install cmake
  18 ```
  19
  20 If you are a contributor and plan to build and run tests, install the following as well:
  21 ```sh
  22  $ # clang and LLVM C++ lib is only required for sanitizer builds
  23  $ [sudo] apt-get install clang-5.0 libc++-dev
  24 ```
  25
  26 ## MacOS
  27
  28 On a Mac, you will first need to
  29 install Xcode or
  30 [Command Line Tools for Xcode](https://developer.apple.com/download/more/)
  31 and then run the following command from a terminal:
  32
  33 ```sh
  34  $ [sudo] xcode-select --install
  35 ```
  36
  37 To build gRPC from source, you may need to install the following
  38 packages from [Homebrew](https://brew.sh):
  39
  40 ```sh
  41  $ brew install autoconf automake libtool shtool
  42 ```
  43
  44 If you plan to build using CMake, follow the instructions from https://cmake.org/download/
  45
  46 *Tip*: when building,
  47 you *may* want to explicitly set the `LIBTOOL` and `LIBTOOLIZE`
  48 environment variables when running `make` to ensure the version
  49 installed by `brew` is being used:
  50
  51 ```sh
  52  $ LIBTOOL=glibtool LIBTOOLIZE=glibtoolize make
  53 ```
  54
  55 ## Windows
  56
  57 To prepare for cmake + Microsoft Visual C++ compiler build
  58 - Install Visual Studio 2015 or 2017 (Visual C++ compiler will be used).
  59 - Install [Git](https://git-scm.com/).
  60 - Install [CMake](https://cmake.org/download/).
  61 - Install [nasm](https://www.nasm.us/) and add it to `PATH` (`choco install nasm`) - *required by boringssl*
  62 - (Optional) Install [Ninja](https://ninja-build.org/) (`choco install ninja`)
  63
  64 # Clone the repository (including submodules)
  65
  66 Before building, you need to clone the gRPC github repository and download submodules containing source code
  67 for gRPC's dependencies (that's done by the `submodule` command or `--recursive` flag). Use following commands
  68 to clone the gRPC repository at the [latest stable release tag](https://github.com/grpc/grpc/releases)
  69
  70 ## Unix
  71
  72 ```sh
  73  $ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc
  74  $ cd grpc
  75  $ git submodule update --init
  76  ```
  77
  78 ## Windows
  79
  80 ```
  81 > git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc
  82 > cd grpc
  83 > git submodule update --init
  84 ```
  85
  86 NOTE: The `bazel` build tool uses a different model for dependencies. You only need to worry about downloading submodules if you're building
  87 with something else than `bazel` (e.g. `cmake`).
  88
  89 # Build from source
  90
  91 In the C++ world, there's no "standard" build system that would work for in all supported use cases and on all supported platforms.
  92 Therefore, gRPC supports several major build systems, which should satisfy most users. Depending on your needs
  93 we recommend building using `bazel` or `cmake`.
  94
  95 ## Building with bazel (recommended)
  96
  97 Bazel is the primary build system for gRPC C++ and if you're comfortable with using bazel, we can certainly recommend it.
  98 Using bazel will give you the best developer experience as well as faster and cleaner builds.
  99
 100 You'll need `bazel` version `1.0.0` or higher to build gRPC.
 101 See [Installing Bazel](https://docs.bazel.build/versions/master/install.html) for instructions how to install bazel on your system.
 102 We support building with `bazel` on Linux, MacOS and Windows.
 103
 104 From the grpc repository root
 105 ```
 106 # Build gRPC C++
 107 $ bazel build :all
 108 ```
 109
 110 ```
 111 # Run all the C/C++ tests
 112 $ bazel test --config=dbg //test/...
 113 ```
 114
 115 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)
 116 to get significant improvement to the build and test speed (and a bunch of other very useful features).
 117
 118 ## Building with CMake
 119
 120 ### Linux/Unix, Using Make
 121
 122 Run from grpc directory after cloning the repo with --recursive or updating submodules.
 123 ```
 124 $ mkdir -p cmake/build
 125 $ cd cmake/build
 126 $ cmake ../..
 127 $ make
 128 ```
 129
 130 If you want to build shared libraries (`.so` files), run `cmake` with `-DBUILD_SHARED_LIBS=ON`.
 131
 132 ### Windows, Using Visual Studio 2015 or 2017
 133
 134 When using the "Visual Studio" generator,
 135 cmake will generate a solution (`grpc.sln`) that contains a VS project for
 136 every target defined in `CMakeLists.txt` (+ few extra convenience projects
 137 added automatically by cmake). After opening the solution with Visual Studio
 138 you will be able to browse and build the code.
 139 ```
 140 > @rem Run from grpc directory after cloning the repo with --recursive or updating submodules.
 141 > md .build
 142 > cd .build
 143 > cmake .. -G "Visual Studio 14 2015"
 144 > cmake --build . --config Release
 145 ```
 146
 147 Using gRPC C++ as a DLL is not recommended, but you can still enable it by running `cmake` with `-DBUILD_SHARED_LIBS=ON`.
 148
 149 ### Windows, Using Ninja (faster build).
 150
 151 Please note that when using Ninja, you will still need Visual C++ (part of Visual Studio)
 152 installed to be able to compile the C/C++ sources.
 153 ```
 154 > @rem Run from grpc directory after cloning the repo with --recursive or updating submodules.
 155 > cd cmake
 156 > md build
 157 > cd build
 158 > call "%VS140COMNTOOLS%..\..\VC\vcvarsall.bat" x64
 159 > cmake ..\.. -GNinja -DCMAKE_BUILD_TYPE=Release
 160 > cmake --build .
 161 ```
 162
 163 Using gRPC C++ as a DLL is not recommended, but you can still enable it by running `cmake` with `-DBUILD_SHARED_LIBS=ON`.
 164
 165 ### Windows: A note on building shared libs (DLLs)
 166
 167 Windows DLL build is supported at a "best effort" basis and we don't recommend using gRPC C++ as a DLL as there are some known drawbacks around how C++ DLLs work on Windows. For example, there is no stable C++ ABI and you can't safely allocate memory in one DLL, and free it in another etc.
 168
 169 That said, we don't actively prohibit building DLLs on windows (it can be enabled in cmake with `-DBUILD_SHARED_LIBS=ON`), and are free to use the DLL builds
 170 at your own risk.
 171 - you've been warned that there are some important drawbacks and some things might not work at all or will be broken in interesting ways.
 172 - we don't have extensive testing for DLL builds in place (to avoid maintenance costs, increased test duration etc.) so regressions / build breakages might occur
 173
 174 ### Dependency management
 175
 176 gRPC's CMake build system has two options for handling dependencies.
 177 CMake can build the dependencies for you, or it can search for libraries
 178 that are already installed on your system and use them to build gRPC.
 179
 180 This behavior is controlled by the `gRPC_<depname>_PROVIDER` CMake variables,
 181 e.g. `gRPC_CARES_PROVIDER`. The options that these variables take are as follows:
 182
 183 * module - build dependencies alongside gRPC. The source code is obtained from
 184 gRPC's git submodules.
 185 * package - use external copies of dependencies that are already available
 186 on your system. These could come from your system package manager, or perhaps
 187 you pre-installed them using CMake with the `CMAKE_INSTALL_PREFIX` option.
 188
 189 For example, if you set `gRPC_CARES_PROVIDER=module`, then CMake will build
 190 c-ares before building gRPC. On the other hand, if you set
 191 `gRPC_CARES_PROVIDER=package`, then CMake will search for a copy of c-ares
 192 that's already installed on your system and use it to build gRPC.
 193
 194 ### Install after build
 195
 196 Perform the following steps to install gRPC using CMake.
 197 * Set `-DgRPC_INSTALL=ON`
 198 * Build the `install` target
 199
 200 The install destination is controlled by the
 201 [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) variable.
 202
 203 If you are running CMake v3.13 or newer you can build gRPC's dependencies
 204 in "module" mode and install them alongside gRPC in a single step.
 205 [Example](test/distrib/cpp/run_distrib_test_cmake_module_install.sh)
 206
 207 If you are building gRPC < 1.27 or if you are using CMake < 3.13 you will need
 208 to select "package" mode (rather than "module" mode) for the dependencies.
 209 This means you will need to have external copies of these libraries available
 210 on your system. This [example](test/distrib/cpp/run_distrib_test_cmake.sh) shows
 211 how to install dependencies with cmake before proceeding to installing gRPC itself.
 212
 213 ```
 214 # NOTE: all of gRPC's dependencies need to be already installed
 215 $ cmake ../.. -DgRPC_INSTALL=ON                \
 216               -DCMAKE_BUILD_TYPE=Release       \
 217               -DgRPC_ABSL_PROVIDER=package     \
 218               -DgRPC_CARES_PROVIDER=package    \
 219               -DgRPC_PROTOBUF_PROVIDER=package \
 220               -DgRPC_RE2_PROVIDER=package      \
 221               -DgRPC_SSL_PROVIDER=package      \
 222               -DgRPC_ZLIB_PROVIDER=package
 223 $ make
 224 $ make install
 225 ```
 226
 227 ### Cross-compiling
 228
 229 You can use CMake to cross-compile gRPC for another architecture. In order to
 230 do so, you will first need to build `protoc` and `grpc_cpp_plugin`
 231 for the host architecture. These tools are used during the build of gRPC, so
 232 we need copies of executables that can be run natively.
 233
 234 You will likely need to install the toolchain for the platform you are
 235 targeting for your cross-compile. Once you have done so, you can write a
 236 toolchain file to tell CMake where to find the compilers and system tools
 237 that will be used for this build.
 238
 239 This toolchain file is specified to CMake by setting the `CMAKE_TOOLCHAIN_FILE`
 240 variable.
 241 ```
 242 $ cmake ../.. -DCMAKE_TOOLCHAIN_FILE=path/to/file
 243 $ make
 244 ```
 245
 246 [Cross-compile example](test/distrib/cpp/run_distrib_test_raspberry_pi.sh)
 247
 248 ## Building with make on UNIX systems (deprecated)
 249
 250 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.
 251
 252 From the grpc repository root
 253 ```sh
 254  $ make
 255 ```
 256
 257 NOTE: if you get an error on linux such as 'aclocal-1.15: command not found', which can happen if you ran 'make' before installing the pre-reqs, try the following:
 258 ```sh
 259 $ git clean -f -d -x && git submodule foreach --recursive git clean -f -d -x
 260 $ [sudo] apt-get install build-essential autoconf libtool pkg-config
 261 $ make
 262 ```
 263
 264 ### A note on `protoc`
 265
 266 By default gRPC uses [protocol buffers](https://github.com/google/protobuf),
 267 you will need the `protoc` compiler to generate stub server and client code.
 268
 269 If you compile gRPC from source, as described below, the Makefile will
 270 automatically try compiling the `protoc` in third_party if you cloned the
 271 repository recursively and it detects that you do not already have 'protoc' compiler
 272 installed.