1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
# gRPC C++
This directory contains the C++ implementation of gRPC.
# To start using gRPC C++
This section describes how to add gRPC as a dependency to your C++ project.
In the C++ world, there's no universally accepted standard for managing project dependencies.
Therefore, gRPC supports several major build systems, which should satisfy most users.
## Supported Platforms
* Officially Supported: These platforms are officially supported. We test our
code on these platform and have automated continuous integration tests for
them.
* Best Effort: We do not have continous integration tests for these, but we are
fairly confident that gRPC C++ would work on them. We will make our best
effort to support them, and we welcome patches for such platforms, but we
might need to declare bankruptcy on some issues.
* Community Supported: These platforms are supported by contributions from the
open source community, there is no official support for them. Breakages on
these platforms may go unnoticed, and the community is responsible for all
maintenance. Unmaintained code for these platforms may be deleted.
| Operating System | Architectures | Versions | Support Level |
|------------------|---------------|----------|---------------|
| Linux - Debian, Ubuntu, CentOS | x86, x64 | clang 4+, GCC 5.1+ | Officially Supported |
| Windows 10+ | x86, x64 | Visual Studio 2015+ | Officially Supported |
| MacOS | x86, x64 | XCode 7.2+ | Officially Supported |
| Linux - Others | x86, x64 | clang 4+, GCC 5.1+ | Best Effort |
| Linux | ARM | | Best Effort |
| iOS | | | Best Effort |
| Android | | | Best Effort |
| Asylo | | | Best Effort |
| FreeBSD | | | Community Supported |
| OpenBSD | | | Community Supported |
| AIX | | | Community Supported |
| Solaris | | | Community Supported |
| NaCL | | | Community Supported |
| Fuchsia | | | Community Supported |
## Bazel
Bazel is the primary build system used by the core gRPC development team. Bazel
provides fast builds and it easily handles dependencies that support bazel.
To add gRPC as a dependency in bazel:
1. determine commit SHA for the grpc release you want to use
2. Use the [http_archive](https://docs.bazel.build/versions/master/repo/http.html#http_archive) bazel rule to include gRPC source
```
http_archive(
name = "com_github_grpc_grpc",
urls = [
"https://github.com/grpc/grpc/archive/YOUR_GRPC_COMMIT_SHA.tar.gz",
],
strip_prefix = "grpc-YOUR_GRPC_COMMIT_SHA",
)
load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps")
grpc_deps()
load("@com_github_grpc_grpc//bazel:grpc_extra_deps.bzl", "grpc_extra_deps")
grpc_extra_deps()
```
## 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 the Android platform.
To build gRPC C++ from source, follow the [BUILDING guide](../../BUILDING.md).
### find_package
The canonical way to discover dependencies in CMake is the
[`find_package` command](https://cmake.org/cmake/help/latest/command/find_package.html).
```cmake
find_package(gRPC CONFIG REQUIRED)
add_executable(my_exe my_exe.cc)
target_link_libraries(my_exe gRPC::grpc++)
```
[Full example](../../examples/cpp/helloworld/CMakeLists.txt)
`find_package` can only find software that has already been installed on your
system. In practice that means you'll need to install gRPC using cmake first.
gRPC's cmake support provides the option to install gRPC either system-wide
(not recommended) or under a directory prefix in a way that you can later
easily use it with the `find_package(gRPC CONFIG REQUIRED)` command.
The following sections describe strategies to automatically build gRPC
as part of your project.
### FetchContent
If you are using CMake v3.11 or newer you should use CMake's
[FetchContent module](https://cmake.org/cmake/help/latest/module/FetchContent.html).
The first time you run CMake in a given build directory, FetchContent will
clone the gRPC repository and its submodules. `FetchContent_MakeAvailable()`
also sets up an `add_subdirectory()` rule for you. This causes gRPC to be
built as part of your project.
```cmake
cmake_minimum_required(VERSION 3.15)
project(my_project)
include(FetchContent)
FetchContent_Declare(
gRPC
GIT_REPOSITORY https://github.com/grpc/grpc
GIT_TAG RELEASE_TAG_HERE # e.g v1.28.0
)
set(FETCHCONTENT_QUIET OFF)
FetchContent_MakeAvailable(gRPC)
add_executable(my_exe my_exe.cc)
target_link_libraries(my_exe grpc++)
```
Note that you need to
[install the prerequisites](../../BUILDING.md#pre-requisites)
before building gRPC.
### git submodule
If you cannot use FetchContent, another approach is to add the gRPC source tree
to your project as a
[git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
You can then add it to your CMake project with `add_subdirectory()`.
[Example](../../examples/cpp/helloworld/CMakeLists.txt)
### Support system-installed gRPC
If your project builds gRPC you should still consider the case where a user
wants to build your software using a previously installed gRPC. Here's a
code snippet showing how this is typically done.
```cmake
option(USE_SYSTEM_GRPC "Use system installed gRPC" OFF)
if(USE_SYSTEM_GRPC)
# Find system-installed gRPC
find_package(gRPC CONFIG REQUIRED)
else()
# Build gRPC using FetchContent or add_subdirectory
endif()
```
[Full example](../../examples/cpp/helloworld/CMakeLists.txt)
## pkg-config
If your project does not use 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)
**Note for CentOS 7 users**
CentOS-7 ships with `pkg-config` 0.27.1, which has a
[bug](https://bugs.freedesktop.org/show_bug.cgi?id=54716) that can make
invocations take extremely long to complete. If you plan to use `pkg-config`,
you'll want to upgrade it to something newer.
## make (deprecated)
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`.
This also installs the protocol buffer compiler `protoc` (if you don't have it already),
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.
## 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
and are known to work well. More contributions and support for popular packaging systems are welcome!
### Install using vcpkg package
gRPC is available using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
```
# install vcpkg package manager on your system using the official instructions
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
# Bootstrap on Linux:
./bootstrap-vcpkg.sh
# Bootstrap on Windows instead:
# ./bootstrap-vcpkg.bat
./vcpkg integrate install
# install gRPC using vcpkg package manager
./vcpkg install grpc
```
The gRPC port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
## Examples & Additional Documentation
You can find out how to build and run our simplest gRPC C++ example in our
[C++ quick start](../../examples/cpp).
For more detailed documentation on using gRPC in C++ , see our main
documentation site at [grpc.io](https://grpc.io), specifically:
* [Overview](https://grpc.io/docs): An introduction to gRPC with a simple
Hello World example in all our supported languages, including C++.
* [gRPC Basics - C++](https://grpc.io/docs/languages/cpp/basics):
A tutorial that steps you through creating a simple gRPC C++ example
application.
* [Asynchronous Basics - C++](https://grpc.io/docs/languages/cpp/async):
A tutorial that shows you how to use gRPC C++'s asynchronous/non-blocking
APIs.
# To start developing gRPC C++
For instructions on how to build gRPC C++ from source, follow the [Building gRPC C++](../../BUILDING.md) instructions.
|
