Build system

Gecko's build system is a custom hybrid of Python (mach, mozbuild), declarative moz.build files, generated Makefiles, and make / cargo / gradle doing the actual work. This page describes the moving parts.

High-level pipeline

graph LR
    Cfg[.mozconfig] --> Configure[mach configure<br/>moz.configure]
    Configure --> Backend[mach build-backend<br/>reads moz.build]
    Backend --> MFiles[Makefiles + ninja files]
    MFiles --> Compile[clang / rustc / javac]
    Compile --> Link[linker]
    Link --> Package[mach package]

moz.build

A Python-syntax declarative file that lives in nearly every directory. Examples:

SOURCES += ["A.cpp"]
UNIFIED_SOURCES += ["B.cpp", "C.cpp"]
EXPORTS.mozilla.foo += ["Foo.h"]
EXTRA_JS_MODULES += ["Foo.sys.mjs"]
DIRS += ["sub1", "sub2"]
TEST_DIRS += ["test"]

XPIDL_MODULE = "myidl"
XPIDL_SOURCES += ["nsIMyThing.idl"]
WEBIDL_FILES += ["Foo.webidl"]
IPDL_SOURCES += ["PFoo.ipdl"]

with Files("**"):
    BUG_COMPONENT = ("Component", "Sub-component")

These are read once by mozbuild (python/mozbuild/) to produce per-directory backend.mk files in the objdir.

moz.configure

Configure-time logic in Python. Top-level moz.configure. Subsystems include their own under build/moz.configure/. Options become --enable-foo / --with-foo flags or ac_add_options lines in .mozconfig.

mach

python/mach/ is the command driver. Plugins (mach_commands.py files) register subcommands all over the tree. Common entrypoints:

• mach build, mach configure, mach build-backend
• mach test, mach mochitest, mach xpcshell-test, mach gtest
• mach lint, mach clang-format
• mach try (try server)
• mach vendor rust (Rust dependencies)

Cargo workspace

Top-level Cargo.toml declares ~25 workspace members (browser/app/nmhproxy, geckodriver, neqo_glue, security/manager/ssl/, toolkit/crashreporter/, …). The mach build invokes cargo build on these crates in the right order. Vendored Rust code lives under third_party/rust/.

Gradle (Android)

For --enable-application=mobile/android builds, the C++ build produces an AAR, then Gradle (build.gradle, settings.gradle) orchestrates Kotlin compilation, resource processing, and APK assembly under <objdir>/gradle/.

TaskCluster (CI)

taskcluster/ defines the Mozilla CI graph in YAML + Python:

• taskcluster/config.yml — global config.
• taskcluster/kinds/*.yml — task definitions per kind: build, test, l10n, perf-test, …
• taskcluster/gecko_taskgraph/ — generator that turns kinds into a DAG of TaskCluster tasks.
• taskcluster/android_taskgraph/ — Android-specific extensions.

./mach try uses the same generator with a filter to push subsets to the try branch.

Code generators

Input	Generator	Output
*.idl (XPIDL)	xpcom/idl-parser/	C++ headers, typelibs
*.webidl	dom/bindings/	C++ binding glue
*.ipdl	ipc/ipdl/	C++ actor classes
metrics.yaml (Glean)	toolkit/components/glean/	C++/JS metric APIs
StaticPrefList.yaml	modules/libpref/init/	C++ pref accessors
Rust UniFFI	toolkit/components/uniffi-bindgen-gecko-js/	JS-callable Rust bindings

Faster iteration

• ./mach build faster — skip C++/Rust; only refresh JS/CSS/manifests. Useful for chrome work.
• ./mach build <subdir> — incremental subdir build.
• --enable-artifact-builds in .mozconfig — fetch prebuilt platform binaries; only build chrome.

Related

• Tooling
• Patterns and conventions