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