Managing Chromium CI Builds with the tools/mb Directory

This article explains the function of the tools/mb directory within the Chromium web browser project. It covers how the Meta-Build wrapper (MB) manages and standardizes build configurations across continuous integration (CI) bots, decouples build arguments from external infrastructure code, and allows developers to easily reproduce complex automated builds on their local machines.

What is the Meta-Build Wrapper (MB)?

In the Chromium source tree, tools/mb houses the Meta-Build wrapper, a Python-based tool originally created to manage the project's transition from the legacy GYP build system to the modern GN (Generate Ninja) build system. Today, GYP is gone, but MB remains a critical piece of infrastructure. It acts as a unified interface between Chromium's automated testing infrastructure (LUCI) and the GN build tool.

When a CI bot needs to compile Chromium, it does not invoke GN directly with a hardcoded list of flags. Instead, the bot calls the mb.py script inside tools/mb and simply passes its own bot name. MB then determines the exact build flags required for that specific bot.

Centralizing Configurations with mb_config.pyl

The core of the tools/mb directory is the mb_config.pyl file (along with its associated Starlark configuration files). This file acts as a massive lookup table that maps every CI bot and trybot in the Chromium ecosystem to a specific set of GN arguments.

To avoid repetition across thousands of bots, MB uses a system called "mixins." A mixin is a reusable snippet of build configurations. For example:

  • An asan mixin enables AddressSanitizer.
  • A debug mixin sets is_debug = true.
  • An android mixin sets target_os = "android".

In mb_config.pyl, a specific bot is defined simply by chaining these mixins together. When the bot runs, MB reads the configuration file, combines the specified mixins into a final args.gn file, and invokes GN to generate the Ninja build files.

Benefits of Source-Side Configuration

The primary reason tools/mb exists inside the Chromium source repository—rather than inside the separate continuous integration infrastructure repository—is to enable source-side configuration.

Storing build configurations directly alongside the source code provides three major advantages:

  1. Atomic Changes: If a developer changes how a build flag works in the C++ code, they can update the flag in tools/mb in the exact same commit. There is no need to synchronize changes across separate code and infrastructure repositories.
  2. Branching Support: Because tools/mb is part of the source tree, it gets branched automatically when a new Chrome release milestone is cut. If a build configuration changes on the main branch, older release branches keep their original, compatible configurations without breaking.
  3. Security and Auditing: Changes to bot configurations go through the exact same code review and continuous integration testing process as regular Chromium code changes.

Key Commands and Developer Workflow

Beyond running on CI bots, tools/mb is heavily used by Chromium developers to replicate bot environments locally. When a patch fails on a specific trybot, a developer does not need to guess which build flags the bot used. They can use MB to interact with the configurations directly:

  • mb.py lookup: Prints the exact GN arguments that a specific bot uses. A developer can run this command, pass the failing bot's name, and immediately see the flags required to reproduce the issue.
  • mb.py gen: Generates a local build directory configured identically to a specified CI bot.
  • mb.py isolate: Generates the .isolate files needed to package compiled binaries and data dependencies so they can be sent to the Swarming test execution bots.
  • mb.py run: Compiles a specific test target and immediately runs it inside an isolated environment, mimicking how the test is executed on the CI infrastructure.