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/be/workspace.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
  29   load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps")
  30
  31   grpc_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 include(FetchContent)
  74 FetchContent_Declare(
  75   gRPC
  76   GIT_REPOSITORY https://github.com/grpc/grpc
  77   GIT_TAG        v1.25.0
  78 )
  79 FetchContent_MakeAvailable(gRPC)
  80
  81 add_executable(my_exe my_exe.cc)
  82 target_link_libraries(my_exe grpc++)
  83 ```
  84
  85 ### git submodule
  86 If you cannot use FetchContent, another approach is to add the gRPC source tree
  87 to your project as a
  88 [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
  89 You can then add it to your CMake project with `add_subdirectory()`.
  90 [Example](../../examples/cpp/helloworld/CMakeLists.txt)
  91
  92 ### Support system-installed gRPC
  93
  94 If your project builds gRPC you should still consider the case where a user
  95 wants to build your software using a previously installed gRPC. Here's a
  96 code snippet showing how this is typically done.
  97
  98 ```cmake
  99 option(USE_SYSTEM_GRPC "Use system installed gRPC" OFF)
 100 if(USE_SYSTEM_GRPC)
 101   # Find system-installed gRPC
 102   find_package(gRPC CONFIG REQUIRED)
 103 else()
 104   # Build gRPC using FetchContent or add_subdirectory
 105 endif()
 106 ```
 107
 108 [Full example](../../examples/cpp/helloworld/CMakeLists.txt)
 109
 110 ## pkg-config
 111
 112 If your project does not use CMake (e.g. you're using `make` directly), you can
 113 first install gRPC C++ using CMake, and have your non-CMake project rely on the
 114 `pkgconfig` files which are provided by gRPC installation.
 115 [Example](../../test/distrib/cpp/run_distrib_test_cmake_pkgconfig.sh)
 116
 117 ## make (deprecated)
 118
 119 The default choice for building on UNIX based systems used to be `make`, but we are no longer recommending it.
 120 You should use `bazel` or `cmake` instead.
 121
 122 To install gRPC for C++ on your system using `make`, follow the [Building gRPC C++](../../BUILDING.md)
 123 instructions to build from source and then install locally using `make install`.
 124 This also installs the protocol buffer compiler `protoc` (if you don't have it already),
 125 and the C++ gRPC plugin for `protoc`.
 126
 127 WARNING: After installing with `make install` there is no easy way to uninstall, which can cause issues
 128 if you later want to remove the grpc and/or protobuf installation or upgrade to a newer version.
 129
 130 ## Packaging systems
 131
 132 We do not officially support any packaging system for C++, but there are some community-maintained packages that are kept up-to-date
 133 and are known to work well. More contributions and support for popular packaging systems are welcome!
 134
 135 ### Install using vcpkg package
 136 gRPC is available using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
 137
 138 ```
 139 # install vcpkg package manager on your system using the official instructions
 140 git clone https://github.com/Microsoft/vcpkg.git
 141 cd vcpkg
 142 ./bootstrap-vcpkg.sh
 143 ./vcpkg integrate install
 144
 145 # install gRPC using vcpkg package manager
 146 vcpkg install grpc
 147 ```
 148
 149 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.
 150
 151
 152 ## Examples & Additional Documentation
 153
 154 You can find out how to build and run our simplest gRPC C++ example in our
 155 [C++ quick start](../../examples/cpp).
 156
 157 For more detailed documentation on using gRPC in C++ , see our main
 158 documentation site at [grpc.io](https://grpc.io), specifically:
 159
 160 * [Overview](https://grpc.io/docs/): An introduction to gRPC with a simple
 161   Hello World example in all our supported languages, including C++.
 162 * [gRPC Basics - C++](https://grpc.io/docs/tutorials/basic/c.html):
 163   A tutorial that steps you through creating a simple gRPC C++ example
 164   application.
 165 * [Asynchronous Basics - C++](https://grpc.io/docs/tutorials/async/helloasync-cpp.html):
 166   A tutorial that shows you how to use gRPC C++'s asynchronous/non-blocking
 167   APIs.
 168
 169
 170 # To start developing gRPC C++
 171
 172 For instructions on how to build gRPC C++ from source, follow the [Building gRPC C++](../../BUILDING.md) instructions.