gRPC depends on several third-party libraries, their source code is available (usually as a git submodule) in this directory.
-
IMPORTANT: whenever possible, try to only update to a stable release of a library (= not to master / random commit). Depending on unreleased revisions makes gRPC installation harder for users, as it forces them to always build the dependency from source and prevents them from using more convenient installation channels (linux packages, package managers etc.)
-
bazel BUILD uses a different dependency model - whenever updating a submodule, also update the revision in
grpc_deps.bzl
so that bazel and non-bazel builds stay in sync (this is actually enforced by a sanity check in some cases)
-
gRPC C++ needs to stay buildable/installable even if the submodules are not present (e.g. the tar.gz archive with gRPC doesn't contain the submodules), assuming that the dependencies are already installed. This is a requirement for being able to provide a reasonable install process (e.g. using cmake) and to support package managers for gRPC C++.
-
Adding a new dependency is a lot of work (both for us and for the users). We currently support multiple build systems (BAZEL, cmake, make, ...) so adding a new dependency usually requires updates in multiple build systems (often not trivial). The installation process also needs to continue to work (we do have distrib tests to test many of the possible installation scenarios, but they are not perfect). Adding a new dependency also usually affects the installation instructions that need to be updated. Also keep in mind that adding a new dependency can be quite disruptive for the users and community - it means that all users will need to update their projects accordingly (for C++ projects often non-trivial) and the community-provided C++ packages (e.g. vcpkg) will need to be updated as well.
READ THIS BEFORE YOU ADD A NEW DEPENDENCY
-
Make sure you understand the hidden costs of adding a dependency (see section above) and that you understand the complexities of updating the build files. Maintenance of the build files isn't for free, so expect to be involved in maintenance tasks, cleanup and support (e.g resolving user bugs) of the build files in the future.
-
Once your change is ready, start an adhoc run of artifact - packages - distribtests flow and make sure everything passes (for technical reasons, not all the distribtests can run on each PR automatically).
-
Check the impact of the new dependency on the size of our distribution packages (compare BEFORE and AFTER) and post the comparison on your PR (it should not be approved without checking the impact sizes of packages first). The package sizes AFTER can be obtained from the adhoc package build from bullet point above.
Usually the process is
- update the submodule to selected commit (see guidance above)
- update the dependency in
grpc_deps.bzl
to the same commit - update
tools/run_tests/sanity/check_submodules.sh
to make the sanity test pass - (when needed) run
tools/buildgen/generate_projects.sh
to regenerate the generated files - populate the bazel download mirror by running
bazel/update_mirror.sh
Updating some dependencies requires extra care.
- 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 intemplates/gRPC-C++.podspec.template
andtemplates/gRPC-Core.podspec.template
.
- Running
- You can see an example of previous upgrade.
- Update the
third_party/boringssl-with-bazel
submodule to the latestmaster-with-bazel
branch
git submodule update --init # just to start in a clean state
cd third_party/boringssl-with-bazel
git fetch origin # fetch what's new in the boringssl repository
git checkout origin/master-with-bazel # checkout the current state of master-with-bazel branch in the boringssl repo
# Note the latest commit SHA on master-with-bazel-branch
cd ../.. # go back to grpc repo root
git status # will show that there are new commits in third_party/boringssl-with-bazel
git add third_party/boringssl-with-bazel # we actually want to update the changes to the submodule
git commit -m "update submodule boringssl-with-bazel with origin/master-with-bazel" # commit
-
Update boringssl dependency in
bazel/grpc_deps.bzl
to the same commit SHA as master-with-bazel branch- Update
http_archive(name = "boringssl",
section by updating the sha instrip_prefix
andurls
fields. - Also, set
sha256
field to "" as the existing value is not valid. This will be added later once we know what that value is.
- Update
-
Update
tools/run_tests/sanity/check_submodules.sh
with the same commit -
Commit these changes
git commit -m "update boringssl dependency to master-with-bazel commit SHA"
-
Run
tools/buildgen/generate_projects.sh
to regenerate the generated files- Because
sha256
inbazel/grpc_deps.bzl
was left empty, you will get a DEBUG msg like this one:
- Because
Rule 'boringssl' indicated that a canonical reproducible form can be obtained by modifying arguments sha256 = "SHA value"
- Commit the regenrated files `git commit -m "regenerate files"`
- Update `bazel/grpc_deps.bzl` with the SHA value shown in the above debug msg. Commit again `git commit -m "Updated sha256"`
-
Run
tools/distrib/generate_boringssl_prefix_header.sh
- Commit again
git commit -m "generate boringssl prefix headers"
- Commit again
-
Increment the boringssl podspec version number in
templates/src/objective-c/BoringSSL-GRPC.podspec.template
andtemplates/gRPC-Core.podspec.template
. example- Commit again
git commit -m "Increment podspec version"
- Commit again
-
Run
tools/buildgen/generate_projects.sh
(yes, again)- Commit again
git commit -m "Second regeneration"
- Commit again
-
Create a PR with all the above commits.
-
Run
bazel/update_mirror.sh
to update GCS mirror.
See http://go/grpc-third-party-protobuf-update-instructions (internal only)