Where the dependency maintainer provides a tarball, prefer that over the automatically generated Github tarball. Github generated tarball SHA256 values can change when Github change their tar/gzip libraries breaking builds. Maintainer provided tarballs are more stable and the maintainer can provide the SHA256.
This is the preferred style of adding dependencies that use Bazel for their build process.
- Define a new Bazel repository in
bazel/repositories.bzl
, in theenvoy_dependencies()
function. - Reference your new external dependency in some
envoy_cc_library
via theexternal_deps
attribute. bazel test //test/...
This is the preferred style of adding dependencies that use CMake for their build system.
- Define a the source Bazel repository in
bazel/repositories.bzl
, in theenvoy_dependencies()
function. - Add a
cmake_external
rule tobazel/foreign_cc/BUILD
. This will reference the source repository in step 1. - Reference your new external dependency in some
envoy_cc_library
via the name bound in step 1external_deps
attribute. bazel test //test/...
This is the newer style of adding dependencies with no upstream Bazel configs. It wraps the dependency's native build tooling in a Bazel-aware shell script, installing to a Bazel-managed prefix.
The shell script is executed by Bash, with a few Bazel-specific extensions. See the Bazel docs for "genrule" for details on Bazel's shell extensions.
- Add a BUILD file in
bazel/external/
, using agenrule
target to build the dependency. Please do not add BUILD logic that replaces the dependency's upstream build tooling. - Define a new Bazel repository in
bazel/repositories.bzl
, in theenvoy_dependencies()
function. The repository may usegenrule_repository
frombazel/genrule_repository.bzl
to place large genrule shell commands into a separate file. - Reference your new external dependency in some
envoy_cc_library
via Y in theexternal_deps
attribute. bazel test //test/...
Dependencies between external libraries can use the standard Bazel dependency
resolution logic, using the $(location)
shell extension to resolve paths
to binaries, libraries, headers, etc.
- Update the corresponding entry in the repository locations file.
bazel test //test/...
An external dependency built by genrule repository or native Bazel could be overridden by
specifying Bazel option
--override_repository
to point to a local copy. The option can used multiple times to override multiple dependencies.
The name of the dependency can be found in
the repository locations file.
The path of the local copy has to be absolute path.
Usually Bazel downloads all dependencies during build time. But there is a
possibility to prefetch dependencies and point Bazel to them by using --distdir
option and providing a path to directory which contains tarballs with exactly
the same name and the same SHA256 sum that are defined in repositories
definitions.
For example, let's assume that your distdir location is $HOME/envoy_distdir
.
To prefetch boringssl
which is defined in bazel/repository_locations.bzl
as:
boringssl = dict(
# Use commits from branch "chromium-stable-with-bazel"
sha256 = "d1700e0455f5f918f8a85ff3ce6cd684d05c766200ba6bdb18c77d5dcadc05a1",
strip_prefix = "boringssl-060e9a583976e73d1ea8b2bfe8b9cab33c62fa17",
# chromium-70.0.3538.67
urls = ["https://github.com/google/boringssl/archive/060e9a583976e73d1ea8b2bfe8b9cab33c62fa17.tar.gz"],
),
$HOME/envoy_distdir
needs to contain 060e9a583976e73d1ea8b2bfe8b9cab33c62fa17.tar.gz
file.
Then Envoy needs to be built with the following command:
bazel build --distdir=$HOME/envoy_distdir //source/exe:envoy