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