1 gRPC C++ - Building from source
2 ===========================
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).
12 $ [sudo] apt-get install build-essential autoconf libtool pkg-config
15 If you plan to build using CMake
17 $ [sudo] apt-get install cmake
20 If you are a contributor and plan to build and run tests, install the following as well:
22 $ # clang and LLVM C++ lib is only required for sanitizer builds
23 $ [sudo] apt-get install clang-5.0 libc++-dev
28 On a Mac, you will first need to
30 [Command Line Tools for Xcode](https://developer.apple.com/download/more/)
31 and then run the following command from a terminal:
34 $ [sudo] xcode-select --install
37 To build gRPC from source, you may need to install the following
38 packages from [Homebrew](https://brew.sh):
41 $ brew install autoconf automake libtool shtool
44 If you plan to build using CMake, follow the instructions from https://cmake.org/download/
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:
52 $ LIBTOOL=glibtool LIBTOOLIZE=glibtoolize make
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`)
64 # Clone the repository (including submodules)
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)
73 $ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc
75 $ git submodule update --init
81 > git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc
83 > git submodule update --init
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`).
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`.
95 ## Building with bazel (recommended)
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.
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.
104 From the grpc repository root
111 # Run all the C/C++ tests
112 $ bazel test --config=dbg //test/...
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).
118 ## Building with CMake
120 ### Linux/Unix, Using Make
122 Run from grpc directory after cloning the repo with --recursive or updating submodules.
124 $ mkdir -p cmake/build
130 If you want to build shared libraries (`.so` files), run `cmake` with `-DBUILD_SHARED_LIBS=ON`.
132 ### Windows, Using Visual Studio 2015 or 2017
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.
140 > @rem Run from grpc directory after cloning the repo with --recursive or updating submodules.
143 > cmake .. -G "Visual Studio 14 2015"
144 > cmake --build . --config Release
147 Using gRPC C++ as a DLL is not recommended, but you can still enable it by running `cmake` with `-DBUILD_SHARED_LIBS=ON`.
149 ### Windows, Using Ninja (faster build).
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.
154 > @rem Run from grpc directory after cloning the repo with --recursive or updating submodules.
158 > call "%VS140COMNTOOLS%..\..\VC\vcvarsall.bat" x64
159 > cmake ..\.. -GNinja -DCMAKE_BUILD_TYPE=Release
163 Using gRPC C++ as a DLL is not recommended, but you can still enable it by running `cmake` with `-DBUILD_SHARED_LIBS=ON`.
165 ### Windows: A note on building shared libs (DLLs)
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.
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
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
174 ### Dependency management
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.
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:
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.
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.
194 ### Install after build
196 Perform the following steps to install gRPC using CMake.
197 * Set `-DgRPC_INSTALL=ON`
198 * Build the `install` target
200 The install destination is controlled by the
201 [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) variable.
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)
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.
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
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.
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.
239 This toolchain file is specified to CMake by setting the `CMAKE_TOOLCHAIN_FILE`
242 $ cmake ../.. -DCMAKE_TOOLCHAIN_FILE=path/to/file
246 [Cross-compile example](test/distrib/cpp/run_distrib_test_raspberry_pi.sh)
248 ## Building with make on UNIX systems (deprecated)
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.
252 From the grpc repository root
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:
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
264 ### A note on `protoc`
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.
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