Build Anywhere, Run Everywhere.

This guide demystifies hermetic cross-compilation with Bazel. Learn how to create reproducible builds for armv8a and x86_64 targets, no matter which machine you build on.

What is Hermeticity?

A build is hermetic if it's insensitive to the host machine's environment. It uses declared, version-pinned tools and dependencies, ensuring that the same source code always produces the exact same binary output.

Why Cross-Compile?

Develop on a powerful x86_64 machine and deploy to an efficient armv8a embedded device. Cross-compilation lets you build for a target architecture different from your host machine.

The Bazel Solution

Bazel's toolchain framework treats compilers and libraries as versioned dependencies. This allows for precise, reproducible, and hermetic builds across any host and target combination.

Understanding the Framework

Bazel uses a powerful system of platforms, constraints, and toolchains to select the right tools for your build. Click on each component to learn more.

Platform

(e.g., Target Machine)

Constraints

(e.g., CPU, OS)

Toolchain

(e.g., Compiler)

Select a Concept

Click on a component in the diagram to see its definition and role in cross-compilation.

Choose Your Toolchain Strategy

Your first big decision: use a community-maintained, pre-built toolchain for speed and simplicity, or build a custom one for maximum control.

Pre-built Toolchains

Get started quickly with a hermetic toolchain managed by the community.

uber/hermetic_cc_toolchain

A fully hermetic, drop-in toolchain using Zig/Clang. Excellent for reproducibility.

Hermeticity: Full

google-coral/crosstool

A semi-hermetic option that's easier to set up but relies on some host system packages.

Hermeticity: Partial

Custom-built Toolchains

For when you need absolute control over compiler versions, patches, and libc.

Complexity: High

Involves using tools like crosstool-NG to build your own cross-compiler and then meticulously integrating it into Bazel's CROSSTOOL and Starlark configurations.

Best for: specialized embedded targets, strict compliance, or unique compiler requirements.

Putting it into Practice

Explore the project structure and build files for a hermetic cross-compilation setup. Click on files in the left panel to view their content.

Project Configuration and Sample Code

Project Structure

  • 📄 README.md
  • 📦 MODULE.bazel
  • 📄 .bazelversion
  • ⚙️ .bazelrc
  • 📁 main/BUILD
  • 📝 main/hello-world.cc

Key Recommendations

Follow these best practices to ensure a smooth and successful cross-compilation setup.

Use Pre-built Toolchains

Start with a toolchain like `uber/hermetic_cc_toolchain`. It provides a strong hermetic foundation without the complexity of a custom build.

Define Granular Platforms

Be specific in your platform definitions. Include OS, CPU, and even libc variants to ensure Bazel makes the correct toolchain choice.

Use `.bazelrc` Configs

Create `--config` aliases for your targets. This simplifies commands and ensures consistency for everyone on your team.