From f5b1557e59f716a99216360f9a2a2628e786be36 Mon Sep 17 00:00:00 2001 From: Esun Kim Date: Tue, 19 Jan 2021 16:42:11 -0800 Subject: [PATCH] Add docs for Abseil --- third_party/ABSEIL_MANUAL.md | 30 ++++++++++++++++++++++++++++++ third_party/README.md | 8 ++++++++ 2 files changed, 38 insertions(+) create mode 100644 third_party/ABSEIL_MANUAL.md diff --git a/third_party/ABSEIL_MANUAL.md b/third_party/ABSEIL_MANUAL.md new file mode 100644 index 00000000000..71e941dd248 --- /dev/null +++ b/third_party/ABSEIL_MANUAL.md @@ -0,0 +1,30 @@ +# Abseil in gRPC + +This document explains how to use Abseil throughout gRPC. Note that this isn't +supposed to explain general usage of Abseil. + +## The version of Abseil + +gRPC is inteded to use the LTS versions of Abseil only because it simplfies +dependency management. Abseil is being distributed via package distribution +systems such as vcpkg and cocoapods. If gRPC depends on the certain version +that aren't registered, gRPC in that system wouldn't build or work. +Therefore, gRPC will use the LTS version only, preferably the latest one. + +## Libraries that are not ready to use + +Most of Abseil libraries are okay to use but there are some exceptions +because they're not going well yet on some of our test machinaries or +platforms it supports. Following is targets that are NOT ready to use. + +- `absl/synchronization:*`: This will be ready from the LTS version in 2021. +- `absl/random`: [WIP](https://github.com/grpc/grpc/pull/23346). +- `absl/types:variant`: [WIP](https://github.com/grpc/grpc/pull/22961). + +## Implemetation only + +You can use Abseil in gRPC Core and gRPC C++. But you cannot use it in +the public interface of gRPC C++ because i) it doesn't gurantee no breaking +API changes like gRPC C++ does and ii) it may make users change their build +system to address Abseil. + \ No newline at end of file diff --git a/third_party/README.md b/third_party/README.md index 9bf04831bcb..473b5426449 100644 --- a/third_party/README.md +++ b/third_party/README.md @@ -48,6 +48,14 @@ Usually the process is Updating some dependencies requires extra care. +### Updating third_party/abseil-cpp + +- Two additional steps should be done before running `generate_projects.sh` above. + - Running `src/abseil-cpp/preprocessed_builds.yaml.gen.py`. + - Updating `abseil_version =` scripts in `templates/gRPC-C++.podspec.template` and + `templates/gRPC-Core.podspec.template`. +- You can see an example of previous [upgrade](https://github.com/grpc/grpc/pull/24270). + ### Updating third_party/boringssl-with-bazel - Update the `third_party/boringssl-with-bazel` submodule to the latest [`master-with-bazel`](https://github.com/google/boringssl/tree/master-with-bazel) branch