envoyproxy/envoy

Build system

Envoy uses Bazel exclusively. The tree is intricate but consistent: every directory has a BUILD file, every binary or library is a Bazel target, every external dep is fetched and pinned. The full operator manual is at bazel/README.md. This page is a wiki-level overview.

Bazel files at the repo root

File	Purpose
`WORKSPACE`	Top-level Bazel workspace declaration.
`MODULE.bazel`	Modular Bazel (`bzlmod`) module declaration.
`.bazelrc`	Default flags and `--config=…` profiles.
`.bazelversion`	Pinned Bazel version (matches `tools/check_repositories.sh`).
`BUILD` (root)	Top-level package, with the rare cross-tree target.

The `bazel/` directory

bazel/ contains the build glue:

File	Purpose
`repository_locations.bzl`	Pinned third-party repos (~100 entries).
`repositories.bzl`	`envoy_dependencies()` macro that registers them.
`external/`	BUILD wrappers for external repos.
`foreign_cc/`	Wrappers for non-Bazel-native projects (CMake, autotools).
`envoy_build_system.bzl`, `envoy_library.bzl`, `envoy_binary.bzl`, `envoy_test.bzl`	Macros that wrap `cc_library` / `cc_binary` / `cc_test` with Envoy defaults (warnings, sanitisers, PCH, copts).
`envoy_internal.bzl`	Common copts, defines, sanitiser flags.
`envoy_select.bzl`	Conditional select expressions for platform / config.
`envoy_pch.bzl`	Precompiled headers.
`pch.bzl`, `pch/`	PCH definitions.
`platforms/`	OS / arch platform definitions.
`rbe/`	Remote Build Execution definitions.
`protoc/`, `wasm/`	Tool wrappers.
`repo.bzl`	Repository macros for cross-repo references.
`*.patch`	Patches applied to external sources.
`README.md`	The authoritative Bazel guide.
`DEVELOPER.md`	Maintainer notes for the build system itself.
`EXTERNAL_DEPS.md`	Adding / updating dependencies.
`PPROF.md`	Profiling with pprof.

Macros

Envoy targets use Envoy-specific macros, not raw cc_* rules. The most important ones:

envoy_cc_library(
    name = "my_thing_lib",
    srcs = ["my_thing.cc"],
    hdrs = ["my_thing.h"],
    deps = [
        "//envoy/foo:bar_interface",
        "//source/common/baz:baz_lib",
    ],
)

envoy_cc_extension(
    name = "config",
    srcs = ["config.cc"],
    hdrs = ["config.h"],
    extra_visibility = [...],
    deps = [...],
    extension_security_postures = ["robust_to_untrusted_downstream"],
)

envoy_cc_test(
    name = "my_test",
    srcs = ["my_test.cc"],
    deps = [
        "//source/common/foo:foo_lib",
        "//test/test_common:test_common_lib",
    ],
)

envoy_cc_extension is the one that registers extension status / security posture metadata.

Common targets

Target	What it builds
`//source/exe:envoy-static`	The canonical server binary.
`//contrib/exe:envoy-static`	The contrib server binary.
`//test/...`	All tests (unit + integration).
`//test/integration:integration_test`	Integration test suite.
`//tools/...`	Repo tooling (api compat checker, dependency validator, format check, …).
`//api/...`	Generated proto code.
`//mobile/library/...`	Envoy Mobile library targets.

Bazel configurations

.bazelrc defines named configs activated with --config=<name>:

Config	Effect
`clang`	Use clang and clang's libstdc++/libc++.
`gcc`	Use GCC.
`clang-asan`, `clang-tsan`, `clang-msan`	Sanitizer builds.
`clang-libc++`	Use libc++ instead of libstdc++.
`clang-cl`	Windows clang-cl (limited).
`compdb`	Generate `compile_commands.json` for clangd.
`coverage`	Build with coverage instrumentation.
`fuzzing`	Enable libfuzzer.
`mobile` (in `mobile/.bazelrc`)	Mobile-specific flags.
`remote-clang`	Remote build execution against EngFlow.
`release`	Release-quality build (`-c opt`, no symbols, hardened).

Extension toggles

source/extensions/extensions_build_config.bzl lists every extension; users can copy and trim it to build a slimmer Envoy. The contrib equivalent is contrib/contrib_build_config.bzl.

EXTENSIONS = {
    "envoy.filters.http.router": "//source/extensions/filters/http/router:config",
    "envoy.filters.http.health_check": "//source/extensions/filters/http/health_check:config",
    ...
}

The mapping is extension name → BUILD target. Removing a line strips the extension from the build.

Tests

bazel test //test/... runs everything. Common scopes:

bazel test //test/common/... — core unit tests.
bazel test //test/extensions/filters/http/... — HTTP filter tests.
bazel test //test/integration:integration_test — integration suite.
bazel test //test/per_file_coverage_test — coverage gate.

See testing for more.

Coverage

bazel/coverage/ and tools/code_coverage/ contain the coverage scripts. CI gates merges on coverage targets per directory.

Toolchains

Envoy uses pinned LLVM and the host's clang as fallback. The toolchains are configured in .bazelrc and bazel/toolchains.bzl. The mobile build uses rules_apple / rules_swift / rules_jvm_external for cross-platform output.

CI

GitHub Actions workflows live in .github/workflows/. The build matrix covers Linux x86_64, Linux aarch64, macOS, Windows (limited), with sanitiser + coverage variants. Most builds run on EngFlow remote build execution.