diff options
Diffstat (limited to 'src/cpp/README.md')
| -rw-r--r-- | src/cpp/README.md | 64 |
1 files changed, 56 insertions, 8 deletions
diff --git a/src/cpp/README.md b/src/cpp/README.md index ac76bf74ed..f16cab1f44 100644 --- a/src/cpp/README.md +++ b/src/cpp/README.md @@ -1,13 +1,62 @@ # Overview -This directory contains source code for C++ implementation of gRPC. +A C++ implementation of gRPC -To install gRPC for C++ on your system, follow the instructions to build from source -[here](../../INSTALL.md). This also installs the protocol buffer compiler -`protoc` (if you don't have it already), and the C++ gRPC plugin for `protoc`. +# To start using gRPC C++ -# Documentation +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. + +## bazel + +We recommend using Bazel for projects that use gRPC as it will give you the best developer experience +(easy handling of dependencies that support bazel & fast builds). + +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/be/workspace.html#http_archive) bazel rule to include gRPC source + ``` + http_archive( + name = "grpc", + urls = [ + "https://github.com/grpc/grpc/archive/YOUR_GRPC_COMMIT_SHA.tar.gz", + ], + strip_prefix = "grpc-YOUR_GRPC_COMMIT_SHA", + ) + ``` + +NOTE: currently bazel is only supported for building gRPC on Linux. + +## make + +Currently the default choice for building on UNIX based systems is `make`. + +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. + +## cmake + +`cmake` is the default build option on Windows, but also works on Linux, MacOS. `cmake` has good +support for crosscompiling and can be used for targeting Android platform. + +If your project is using cmake, there are several ways to add gRPC dependency. +- install gRPC via cmake first and then locate it with `find_package(gRPC CONFIG)`. [Example](../../examples/cpp/helloworld/CMakeLists.txt) +- via cmake's `ExternalProject_Add` using a technique called "superbuild". [Example](../../examples/cpp/helloworld/cmake_externalproject/CMakeLists.txt) +- add gRPC source tree to your project (preferrably as a git submodule) and add it to your cmake project with `add_subdirectory`. [Example](../../examples/cpp/helloworld/CMakeLists.txt) + +## Packaging systems + +There's no standard packaging system for C++. We've looked into supporting some (e.g. Conan and vcpkg) but we are not there yet. +Contributions and community-maintained packages for popular packaging systems are welcome! + + +## Examples & Additional Documentation You can find out how to build and run our simplest gRPC C++ example in our [C++ quick start](../../examples/cpp). @@ -25,7 +74,6 @@ documentation site at [grpc.io](https://grpc.io), specifically: APIs. -# Examples +# To start developing gRPC C++ -Code examples for gRPC C++ live in this repository's -[examples/cpp](../../examples/cpp) directory. +For instructions on how to build gRPC C++ from source, follow the [Building gRPC C++](../../BUILDING.md) instructions. |