Skip to content

Brave Browser Build Deconstructed ‐ overview of the underlying tools

Jump to bottom
Gaetano Checinski edited this page Sep 16, 2025 · 3 revisions

Npm run init/sync

Under the hood npm run init performs several tasks:

  • downloads depot_tools including gclient - our git download manager
  • setups environment variables
  • creates a .gclient file
  • calls gclient sync - which downloads all chromium related dependencies and runs install hooks
  • applies patches

Notes:

  • npm run init does a few extra operations to also clone 3th party tools and is considered to only use when first setting things up.
  • npm run sync will consult various files eg. src/brave/*.patchinfo and /.gclient_entries to identify what has changed and perform a minimal sync

gclient sync

Gclient sync fetches (git clones) around 240 repositories and over ~60GB (decompressed). The dependencies are defined in DEPS files in our and chromiums projects and retrieved recursively and some are platform specific. Thus a chromium checkout may be specific to the target platform. Our npm run init/sync takes for that reason optional —-target_os –target_arch args.

The root manifest is defined in .gclient file in the root of your project. This file is currently generated by npm run init and reads as follows:

solutions = [{
    "name": "src",
    "managed": False, 
    "url": "https://github.com/brave/chromium",
    "custom_deps": {
      "src/testing/libfuzzer/fuzzers/wasm_corpus": None, 
      "src/third_party/chromium-variations": None
    },
    "custom_vars": {
      "checkout_pgo_profiles": False 
    }
  }, {
    "name": "src/brave",
    "managed": False, 
    "url": "https://github.com/brave/brave-core.git"
  }
]

target_os = [“linux"] # all options [“linux”, "mac", "win", "ios", "android" ]
target_cpu = ["x64"] # all options [“arm”, “arm64, “x64”]

With a gclient file in place we can then perform a

gclient sync [--no-history] [--verbose] --revision [email protected] --revision src/brave@master

Notes:

  • Managed = true/false should gclient reset the folders if they deviate from the requested commit
  • --no-history = whether to fetch only the requested version or the complete git history
  • custom_deps: allows us to opt-out from checking out deps or override them
  • checkout_pgo_profiles: we use those in release builds; we could fetch them too; especially if we share the snapashot with release builds too when doing this one needs to also set
  • target_os/target_cpu: gclient fetches for all platforms that are specified!

After a successful sync you can find a lock file in the root of the project .gclient_entries which lists out the exact versions that have been checked out.

Once everything is checked out patches from brave/patches are applied. The script that performs the patches keeps track of what has been patched and stores the information in brave/patches/*.patchinfo files

Brave Specific Environment Variables

Npm init also sets a few environment variables which affect the behaviour of gclient sync:

DEPOT_TOOLS_WIN_TOOLCHAIN=1 # whether to download the windows toolchain
USE_BRAVE_HERMETIC_TOOLCHAIN=1` # should we download win / mac toolchains
GYP_MSVS_HASH_68a20d6dee=6c25999c85 # overrides which gyp_msys version is fetched DEPOT_TOOLS_WIN_TOOLCHAIN_BASE_URL='https://vhemnu34de4lf5cj6bx2wwshyy0egdxk.lambda-url.us-west-2.on.aws/windows-hermetic-toolchain/'  # defines url from where to fetch toolchains
PYTHONUNBUFFERED=1 # makes sure python prints to stdout quicker
GSUTIL_ENABLE_LUCI_AUTH=0  # make sure gclient doens’t try to log into google ci service
PYTHONPATH

Other env variables

DEPOT_TOOLS_UPDATE=1/0 decides whether gclient should autoupdate depot_tools automatically (question: does this invalidate buildcache?) GIT_CACHE_PATH Highly recommended, defines a cache path for gclient to use NPM run build

NPM run build orchestrates the build process of brave. This is done by preparing the source code and using gn gen (generate ninja) to prepare the build folder.

Performing a multi-architecture checkout makes only sense on linux since it's currently the only platform that supports cross-platform builds.

NPM run build performs 2 actions:

  • configure environment variables and gn args for building the project by processing src/brave/.env, passed arguments and environment variables
  • setup a build directory for autoninja build

If you call

NPM run build – [Static|Component|Release] [–target_os=<>] [–target_arch=<>] [–target=brave:all]

The npm script will apply the patches, determine the configuration and call `gn gen src/out/_<target_platform> –list=gnArg1=value1 gnArg2=value2...```

And then start the build via

autoninja -C ../out/<buildType>_<target_platform> <target>

Where target=brave:all by default.

You can query what gn options are available and to what they are set via

gn args src/out/<buildType>_<target_platform> --list
Clone this wiki locally