Getting started

This page summarizes how to obtain, build, run, and test Firefox / Gecko from this tree. The canonical reference is the Firefox Contributors' Quick Reference; this is a high-level orientation only.

Prerequisites

Platform	Requirements
Linux	Recent Clang, Rust (stable), Python 3.9+, Node.js, GCC libstdc++ headers, Mercurial or Git
macOS	Xcode CLT, Rust, Python 3.9+, Node.js
Windows	MozillaBuild + MSVC toolchain (the bootstrap installer handles this)
Android (GeckoView/Fenix)	Android SDK + NDK (provided via mach bootstrap --application-choice mobile_android)

The recommended way to install everything is ./mach bootstrap, which downloads pinned versions of toolchains into ~/.mozbuild/.

The mach driver

Every common task is exposed through the top-level mach script (mach, mach.cmd, mach.ps1). It is implemented in python/mach/ and discovers commands via mach_commands.py files scattered throughout the tree.

Common commands:

Command	Purpose
./mach bootstrap	Install toolchains and dependencies
./mach configure	Read moz.configure, write config.status
./mach build	Build the configured target (parallel)
./mach build faster	Skip C++/Rust, only rebuild JS/CSS/manifests
./mach run	Launch the built browser
./mach test <path>	Run any test by path; mach picks the right harness
./mach mochitest path/to/test.html	Mochitest specifically
./mach xpcshell-test path/to/test.js	xpcshell unit tests
./mach try	Push to TaskCluster try server
./mach lint	Run all linters (eslint, clang-format, ruff, …)
./mach clang-format	Format C++
./mach vendor rust	Refresh third_party/rust
./mach wpt path/to/test.html	Web platform tests

A .mozconfig file in the repo root (or pointed at via MOZCONFIG=) configures the build (debug vs opt, application choice, feature flags). Examples live under build/mozconfig.*.

Where things live (cheat sheet)

You're touching…	Look in
Browser chrome / UI	browser/, toolkit/
Android browser	mobile/android/
Web platform feature (DOM/Web API)	dom/ (often plus layout/ and gfx/)
CSS / layout	layout/, servo/components/style/
Graphics, compositor	gfx/
JS engine	js/src/
Networking	netwerk/
Security / TLS / certs	security/
DevTools	devtools/
Process model / IPC	ipc/, dom/ipc/
Build system	python/mozbuild/, build/, moz.build, moz.configure
CI configuration	taskcluster/
Tests	testing/
Telemetry / metrics	toolkit/components/telemetry/, toolkit/components/glean/

Running tests locally

Most tests can be run with ./mach test path/to/file. Specific harnesses include:

• Mochitest — browser-driven JS tests under dom/, browser/, toolkit/. Run with ./mach mochitest.
• xpcshell — headless JS unit tests, mostly for non-DOM code (netwerk/test/unit/*, services/). Run with ./mach xpcshell-test.
• Reftest / Crashtest — pixel-comparison tests under layout/reftests/ and similar.
• gtest — C++ unit tests via Google Test. Run with ./mach gtest.
• Web platform tests — testing/web-platform/. Run with ./mach wpt.
• Marionette / WebDriver — testing/marionette/, testing/geckodriver/.
• Talos / Raptor — performance tests under testing/talos/ and testing/raptor/.

Submitting a patch (the short version)

1. Make changes locally.
2. Run ./mach lint --outgoing.
3. Run relevant tests via ./mach test.
4. Commit with a Bug NNNNNN - description r=reviewer message.
5. Submit to Phabricator with moz-phab submit.
6. After review, the bot lands the patch via Lando into mozilla-central.
7. The change appears here in gecko-dev shortly after.

See How to contribute for the full workflow.