src/cpp/README.md

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