Project: Envoy (Orchestration & Management / Service Proxy)
File: EXTERNAL_DEPS.md

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 , in the `envoy_dependencies()` function. Reference your new external dependency in some `envoycclibrary` via the `external_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 , in the `envoy_dependencies()` function. Add an `envoy_cmake` rule to . This will reference the source repository in step 1. Reference your new external dependency in some `envoycclibrary` via the name bound in step 1 `external_deps` attribute. `bazel test //test/...` Python dependencies should be added via `pip` and `rules_python`. The process is: Define a `pip_install()` pointing at your target `requirements.txt` in Add a `requirements("<package name>")` in the `BUILD` file that depends on this package. You can use as an example for this flow. See also the documentation for further references. Update the corresponding entry in `bazel test //test/...` An external dependency built by genrule repository or native Bazel could be overridden by specifying Bazel option 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 path of the local copy has to be absolute path. For repositories built by `envoycmake()` in `bazel/foreigncc/BUILD`, it is necessary to populate the local copy with some additional Bazel machinery to support `--override_repository`: Place an empty `WORKSPACE` in the root. Place a `BUILD` file with `filegroup(name = "all", srcs = glob([""]), visibility = ["//visibility:public"])` in the root. For all external dependencies, overriding with a local copy as described in the previous section is a useful tool. Below we describe specific tips for obtaining additional debug for specific dependencies: `libevent`: add `"EVENTENABLEVERBOSEDEBUG": "on",` to `cache_entries` in the `event` target in `bazel/foreign_cc/BUILD` for verbose tracing of libevent processing. `nghttp2`: set `ENVOYNGHTTP2TRACE` in the environment and run at `-l trace`. `QUICHE`: set `ENVOYQUICHEVERBOSITY=n` in the environment to display verbose logs up to level `n`. 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( sha256 = "d1700e0455f5f918f8a85ff3ce6cd684d05c766200ba6bdb18c77d5dcadc05a1", strip_prefix = "boringssl-060e9a583976e73d1ea8b2bfe8b9cab33c62fa17", 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 ```