Blame - src/cpp/README.md - external/github.com/grpc/grpc

blob: 43939580c068aac2fdd4adc0d1fcc2e199b40935 [file] [log] [blame] [view]

Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	1	# gRPC C++
Jayant Kolhe	80949e3	2015-02-19 19:27:07	[diff] [blame]	2
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	3	This directory contains the C++ implementation of gRPC.
Jayant Kolhe	80949e3	2015-02-19 19:27:07	[diff] [blame]	4
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	5	# To start using gRPC C++
Yuchen Zeng	341b5ab	2016-03-09 01:16:29	[diff] [blame]	6
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	7	This section describes how to add gRPC as a dependency to your C++ project.
				8
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	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
Yash Tibrewal	1040c1b	2021-08-17 20:58:35	[diff] [blame]	12	## Supported Platforms
				13
Esun Kim	b1b59eb	2022-06-30 20:22:59	[diff] [blame]	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
AJ Heller	f5b3a49	2021-10-05 02:05:52	[diff] [blame]	18	them.
Esun Kim	b1b59eb	2022-06-30 20:22:59	[diff] [blame]	19	.
Yash Tibrewal	1040c1b	2021-08-17 20:58:35	[diff] [blame]	20
Nathan Baulch	b2a05be	2024-10-10 22:35:34	[diff] [blame]	21	* Best Effort: We do not have continuous integration tests for these, but we are
AJ Heller	f5b3a49	2021-10-05 02:05:52	[diff] [blame]	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.
Yash Tibrewal	1040c1b	2021-08-17 20:58:35	[diff] [blame]	30
Esun Kim	8df210e	2025-06-04 19:47:06	[diff] [blame]	31	\| Operating System \| Architectures \| Support Level \|
				32	\|--------------------------------\|---------------\|----------------------\|
				33	\| Linux - Debian, Ubuntu, CentOS \| x86, x64 \| Officially Supported \|
				34	\| Windows 10+ \| x86, x64 \| Officially Supported \|
				35	\| MacOS \| x64, ARM64 \| Officially Supported \|
				36	\| Linux - Others \| x86, x64 \| 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 \|
Yash Tibrewal	1040c1b	2021-08-17 20:58:35	[diff] [blame]	48
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	49	## Bazel
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	50
Esun Kim	8df210e	2025-06-04 19:47:06	[diff] [blame]	51	Bazel is the gRPC core development team's main build system.
				52	It offers speedy builds and effortlessly manages dependencies that already support Bazel.
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	53
Esun Kim	8df210e	2025-06-04 19:47:06	[diff] [blame]	54	To add gRPC as a Bazel dependency:
				55
				56	1. Find your desired gRPC version on the
				57	[Bazel Central Registry](https://registry.bazel.build/modules/grpc).
				58	2. Then, use [bazel_dep](https://bazel.build/rules/lib/globals/module#bazel_dep)
				59	to add the gRPC dependency to your `MODULE.bazel` file.
				60
				61	```
				62	bazel_dep(name = "grpc", version = "1.72.0")
				63	```
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	64
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	65	## CMake
Jan Tattermusch	48b1f8d	2019-11-28 14:42:44	[diff] [blame]	66
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	67	`cmake` is your best option if you cannot use bazel. It supports building on Linux,
				68	MacOS and Windows (official support) but also has a good chance of working on
				69	other platforms (no promises!). `cmake` has good support for crosscompiling and
				70	can be used for targeting the Android platform.
Jan Tattermusch	48b1f8d	2019-11-28 14:42:44	[diff] [blame]	71
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	72	To build gRPC C++ from source, follow the [BUILDING guide](../../BUILDING.md).
Jan Tattermusch	48b1f8d	2019-11-28 14:42:44	[diff] [blame]	73
Esun Kim	02fb4b5	2025-01-10 20:48:18	[diff] [blame]	74	To ensure all libraries in your CMake project compile with the same C++ version
				75	(e.g., C++17), explicitly specify the standard:
				76
				77	```cmake
				78	set(CMAKE_CXX_STANDARD 17)
				79	set(CMAKE_CXX_STANDARD_REQUIRED ON)
				80	```
				81
				82	This configuration enforces the use of C++17 for all targets and avoids potential
				83	inconsistencies or errors due to different C++ versions being used.
				84
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	85	### find_package
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	86
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	87	The canonical way to discover dependencies in CMake is the
				88	[`find_package` command](https://cmake.org/cmake/help/latest/command/find_package.html).
				89
				90	```cmake
				91	find_package(gRPC CONFIG REQUIRED)
				92	add_executable(my_exe my_exe.cc)
				93	target_link_libraries(my_exe gRPC::grpc++)
				94	```
				95	[Full example](../../examples/cpp/helloworld/CMakeLists.txt)
				96
				97	`find_package` can only find software that has already been installed on your
				98	system. In practice that means you'll need to install gRPC using cmake first.
				99	gRPC's cmake support provides the option to install gRPC either system-wide
				100	(not recommended) or under a directory prefix in a way that you can later
				101	easily use it with the `find_package(gRPC CONFIG REQUIRED)` command.
				102
				103	The following sections describe strategies to automatically build gRPC
				104	as part of your project.
				105
				106	### FetchContent
				107	If you are using CMake v3.11 or newer you should use CMake's
				108	[FetchContent module](https://cmake.org/cmake/help/latest/module/FetchContent.html).
				109	The first time you run CMake in a given build directory, FetchContent will
				110	clone the gRPC repository and its submodules. `FetchContent_MakeAvailable()`
				111	also sets up an `add_subdirectory()` rule for you. This causes gRPC to be
				112	built as part of your project.
				113
				114	```cmake
Esun Kim	a49d450	2024-09-30 17:52:26	[diff] [blame]	115	cmake_minimum_required(VERSION 3.16)
Zack Galbreath	79f1a07	2020-03-06 19:56:01	[diff] [blame]	116	project(my_project)
				117
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	118	include(FetchContent)
				119	FetchContent_Declare(
				120	gRPC
				121	GIT_REPOSITORY https://github.com/grpc/grpc
Jan Tattermusch	d99b541	2020-03-17 09:53:37	[diff] [blame]	122	GIT_TAG RELEASE_TAG_HERE # e.g v1.28.0
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	123	)
Zack Galbreath	79f1a07	2020-03-06 19:56:01	[diff] [blame]	124	set(FETCHCONTENT_QUIET OFF)
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	125	FetchContent_MakeAvailable(gRPC)
				126
				127	add_executable(my_exe my_exe.cc)
				128	target_link_libraries(my_exe grpc++)
				129	```
				130
Zack Galbreath	79f1a07	2020-03-06 19:56:01	[diff] [blame]	131	Note that you need to
				132	[install the prerequisites](../../BUILDING.md#pre-requisites)
				133	before building gRPC.
				134
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	135	### git submodule
				136	If you cannot use FetchContent, another approach is to add the gRPC source tree
				137	to your project as a
				138	[git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
				139	You can then add it to your CMake project with `add_subdirectory()`.
				140	[Example](../../examples/cpp/helloworld/CMakeLists.txt)
				141
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	142	### Support system-installed gRPC
				143
				144	If your project builds gRPC you should still consider the case where a user
				145	wants to build your software using a previously installed gRPC. Here's a
				146	code snippet showing how this is typically done.
				147
				148	```cmake
				149	option(USE_SYSTEM_GRPC "Use system installed gRPC" OFF)
				150	if(USE_SYSTEM_GRPC)
				151	# Find system-installed gRPC
				152	find_package(gRPC CONFIG REQUIRED)
				153	else()
				154	# Build gRPC using FetchContent or add_subdirectory
				155	endif()
				156	```
				157
				158	[Full example](../../examples/cpp/helloworld/CMakeLists.txt)
				159
				160	## pkg-config
				161
				162	If your project does not use CMake (e.g. you're using `make` directly), you can
				163	first install gRPC C++ using CMake, and have your non-CMake project rely on the
				164	`pkgconfig` files which are provided by gRPC installation.
				165	[Example](../../test/distrib/cpp/run_distrib_test_cmake_pkgconfig.sh)
				166
Esun Kim	a4b43cc	2021-07-15 16:45:01	[diff] [blame]	167	Note for CentOS 7 users
				168
				169	CentOS-7 ships with `pkg-config` 0.27.1, which has a
				170	[bug](https://bugs.freedesktop.org/show_bug.cgi?id=54716) that can make
				171	invocations take extremely long to complete. If you plan to use `pkg-config`,
				172	you'll want to upgrade it to something newer.
				173
Zack Galbreath	684aa48	2019-12-12 18:55:02	[diff] [blame]	174	## make (deprecated)
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	175
Jan Tattermusch	48b1f8d	2019-11-28 14:42:44	[diff] [blame]	176	The default choice for building on UNIX based systems used to be `make`, but we are no longer recommending it.
				177	You should use `bazel` or `cmake` instead.
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	178
				179	To install gRPC for C++ on your system using `make`, follow the [Building gRPC C++](../../BUILDING.md)
				180	instructions to build from source and then install locally using `make install`.
				181	This also installs the protocol buffer compiler `protoc` (if you don't have it already),
				182	and the C++ gRPC plugin for `protoc`.
				183
				184	WARNING: After installing with `make install` there is no easy way to uninstall, which can cause issues
				185	if you later want to remove the grpc and/or protobuf installation or upgrade to a newer version.
				186
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	187	## Packaging systems
				188
Jan Tattermusch	942e468	2019-10-29 17:04:16	[diff] [blame]	189	We do not officially support any packaging system for C++, but there are some community-maintained packages that are kept up-to-date
				190	and are known to work well. More contributions and support for popular packaging systems are welcome!
				191
				192	### Install using vcpkg package
				193	gRPC is available using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
				194
				195	```
				196	# install vcpkg package manager on your system using the official instructions
				197	git clone https://github.com/Microsoft/vcpkg.git
				198	cd vcpkg
Yan Reznikov	39d007e	2021-06-11 09:21:49	[diff] [blame]	199
				200	# Bootstrap on Linux:
Jan Tattermusch	942e468	2019-10-29 17:04:16	[diff] [blame]	201	./bootstrap-vcpkg.sh
Yan Reznikov	39d007e	2021-06-11 09:21:49	[diff] [blame]	202	# Bootstrap on Windows instead:
				203	# ./bootstrap-vcpkg.bat
				204
Jan Tattermusch	942e468	2019-10-29 17:04:16	[diff] [blame]	205	./vcpkg integrate install
				206
				207	# install gRPC using vcpkg package manager
Yan Reznikov	39d007e	2021-06-11 09:21:49	[diff] [blame]	208	./vcpkg install grpc
Jan Tattermusch	942e468	2019-10-29 17:04:16	[diff] [blame]	209	```
				210
				211	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.
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	212
				213
				214	## Examples & Additional Documentation
Yuchen Zeng	341b5ab	2016-03-09 01:16:29	[diff] [blame]	215
Yuchen Zeng	798b0dc	2016-03-09 20:00:09	[diff] [blame]	216	You can find out how to build and run our simplest gRPC C++ example in our
Yuchen Zeng	d85ef06	2016-03-18 18:05:25	[diff] [blame]	217	[C++ quick start](../../examples/cpp).
Yuchen Zeng	341b5ab	2016-03-09 01:16:29	[diff] [blame]	218
Yuchen Zeng	798b0dc	2016-03-09 20:00:09	[diff] [blame]	219	For more detailed documentation on using gRPC in C++ , see our main
Mehrdad Afshari	bb3d95b	2017-07-10 22:24:28	[diff] [blame]	220	documentation site at [grpc.io](https://grpc.io), specifically:
Yuchen Zeng	798b0dc	2016-03-09 20:00:09	[diff] [blame]	221
Patrice Chalin	b8514ea	2020-03-14 01:47:06	[diff] [blame]	222	* [Overview](https://grpc.io/docs): An introduction to gRPC with a simple
Yuchen Zeng	798b0dc	2016-03-09 20:00:09	[diff] [blame]	223	Hello World example in all our supported languages, including C++.
Patrice Chalin	5ac3aa7	2020-06-16 12:47:24	[diff] [blame]	224	* [gRPC Basics - C++](https://grpc.io/docs/languages/cpp/basics):
Yuchen Zeng	798b0dc	2016-03-09 20:00:09	[diff] [blame]	225	A tutorial that steps you through creating a simple gRPC C++ example
				226	application.
Patrice Chalin	5ac3aa7	2020-06-16 12:47:24	[diff] [blame]	227	* [Asynchronous Basics - C++](https://grpc.io/docs/languages/cpp/async):
Yuchen Zeng	798b0dc	2016-03-09 20:00:09	[diff] [blame]	228	A tutorial that shows you how to use gRPC C++'s asynchronous/non-blocking
				229	APIs.
				230
				231
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	232	# To start developing gRPC C++
Yuchen Zeng	798b0dc	2016-03-09 20:00:09	[diff] [blame]	233
Jan Tattermusch	f389e52	2018-06-12 15:26:31	[diff] [blame]	234	For instructions on how to build gRPC C++ from source, follow the [Building gRPC C++](../../BUILDING.md) instructions.