Build Utilities Reference

This page documents the build utilities in the utils/ directory. These are the core tools used throughout the Helium build process for source tree preparation, patching, and packaging.

Overview

The build utilities provide essential functionality for:

Applying and managing patches in GNU Quilt format
Domain substitution to replace Google domains
Binary pruning to remove unwanted files
Source tree downloads and extraction
Portable package creation

Patch Management

patches.py

Apply and merge patches in GNU Quilt format.

python3 utils/patches.py apply \
  /path/to/source/tree \
  /path/to/patches

target

path

required

The directory tree to apply patches onto

patches

path[]

required

One or more directories containing patches in GNU Quilt format

--patch-bin

string

The GNU patch command to use (auto-detected if omitted)

--fuzz / --no-fuzz

boolean

default:true

Enable or disable fuzzy matching when applying patches

Patch detection order

The script finds the patch binary in this order:

Uses --patch-bin if specified
Checks PATCH_BIN environment variable
Searches for patch in PATH using which

Merging Patches

Combine multiple patch directories into a single directory.

python3 utils/patches.py merge \
  /path/to/destination \
  /path/to/source1 \
  /path/to/source2

destination

path

required

Directory to write merged patches (must not exist unless using —prepend)

source

path[]

required

GNU Quilt patch directories to merge

-p, --prepend

boolean

Prepend patches to existing destination directory

Merging will fail if any patches have conflicting paths between source directories.

Dry Run Checking

The module also exports dry_run_check() for programmatic patch validation:

from patches import dry_run_check

return_code, stdout, stderr = dry_run_check(
    patch_path=Path('my.patch'),
    tree_path=Path('/path/to/source'),
    patch_bin_path=None  # Auto-detect
)

Domain Substitution

domain_substitution.py

Replace Google domains with blockable placeholder strings.

Domain substitution makes it easier to identify and block Google services using hosts files or firewall rules.

python3 utils/domain_substitution.py apply \
  --regex domain_regex.list \
  --files domain_substitution.list \
  --cache domainsub.tar.gz \
  /path/to/source/tree

Apply Mode

Revert Mode

Domain Regex Format

The domain_regex.list file uses this format:

pattern#replacement
google\.com#PLACEHOLDER_GOOGLE_COM
chromium\.org#PLACEHOLDER_CHROMIUM_ORG

Pattern: Regular expression to match
Delimiter: # character
Replacement: String to replace matches with

Binary Pruning

prune_binaries.py

Remove binary files and unwanted directories from the source tree.

python3 utils/prune_binaries.py \
  /path/to/source/tree \
  pruning.list

Contingent Paths

Contingent paths are automatically pruned unless --keep-contingent-paths is specified:

Build tools and dependencies

CIPD packages (buildtools, third_party tools)
GCS downloads (sysroots, test data)
Google-specific build tools
JDK packages

Test data and fixtures

Web tests and browser tests
Performance test datasets
Fuzzer corpora
Test fonts and media files

Platform-specific

Android WebView
iOS sources
Chromecast
Native Client

Some files are always kept even in contingent paths: .gn, .gni, .grd, .grdp, .isolate, and .pydeps files.

Downloads Management

downloads.py

Download, verify, and extract required files into the source tree.

python3 utils/downloads.py retrieve \
  /path/to/downloads.ini \
  /path/to/download/directory

downloads_ini

path

required

Path to downloads.ini configuration

download_directory

path

required

Directory to store downloaded files

source_tree

path

Source tree path (for unpack command)

downloads.ini Format

The configuration file uses INI format:

[download_name]
url = https://example.com/file.tar.gz
download_filename = file.tar.gz
output_path = third_party/example
sha256 = abc123...
extractor = tar
strip_leading_dirs = 1

url

string

required

Download URL (supports {_chromium_version} variable)

download_filename

string

required

Filename to save as

output_path

string

required

Relative path in source tree for extraction

sha256

string

Expected SHA256 hash for verification

extractor

enum

tar - Use tar for extraction
7z - Use 7-Zip
winrar - Use WinRAR

strip_leading_dirs

integer

Number of leading directory components to strip during extraction

Hash verification

Supported hash algorithms:

MD5 (md5 key)
SHA1 (sha1 key)
SHA256 (sha256 key)
SHA512 (sha512 key)
Hash URLs (hash_url key with format: chromium|path|algorithm)

Multiple hashes can be specified for redundant verification.

Source Tree Cloning

clone.py

Clone a Chromium source tree from various sources.

python3 utils/clone.py \
  /path/to/destination \
  --downloads-ini downloads.ini

This utility handles downloading the Chromium source tarball and extracting it to the specified destination.

Packaging

filescfg.py

Create portable packages using FILES.cfg specifications.

python3 utils/filescfg.py archive \
  /path/to/FILES.cfg \
  /path/to/build_output \
  /path/to/output.tar.xz

cfg_path

path

required

Path to FILES.cfg specification

build_outputs

path

required

Directory containing build outputs

output_path

path

required

Output archive path (.tar.gz, .tar.xz, or .zip)

--timestamp

integer

Unix timestamp for reproducible archives

FILES.cfg format

FILES.cfg is a Python file that defines which files to include:

FILES = [
  {
    'filename': 'chrome',
    'buildtype': ['official'],
  },
  {
    'filename': '*.so',
    'buildtype': ['official'],
    'arch': ['64bit'],
  },
]

Each entry supports:

filename: Glob pattern
buildtype: List of build types (must include ‘official’)
arch: CPU architecture filter

Version Management

helium_version.py

Manage Helium version information.

python3 utils/helium_version.py \
  /path/to/source/tree \
  --set-version 1.2.3

This utility updates version strings throughout the source tree to maintain consistent branding.

Name Substitution

name_substitution.py

Replace product names throughout the source tree.

python3 utils/name_substitution.py \
  /path/to/source/tree \
  --product-name "Helium"

Used to rebrand Chromium references to Helium in source files.

Resource Generation

generate_resources.py

Generate resource files from templates.

python3 utils/generate_resources.py \
  /path/to/resources \
  /path/to/output

Processes resource templates and generates final resource files for the build.

Common Patterns

Complete source tree preparation

# 1. Clone source tree
python3 utils/clone.py /path/to/src --downloads-ini downloads.ini

# 2. Prune unwanted files
python3 utils/prune_binaries.py /path/to/src pruning.list

# 3. Apply domain substitution
python3 utils/domain_substitution.py apply \
  --regex domain_regex.list \
  --files domain_substitution.list \
  --cache domainsub.tar.gz \
  /path/to/src

# 4. Apply patches
python3 utils/patches.py apply /path/to/src patches/

Reverting changes for testing

# Revert patches
python3 utils/patches.py apply --reverse /path/to/src patches/

# Revert domain substitution
python3 utils/domain_substitution.py revert \
  --cache domainsub.tar.gz \
  /path/to/src

Module Imports

These utilities can also be imported as Python modules:

from patches import apply_patches, merge_patches, generate_patches_from_series
from domain_substitution import apply_substitution, revert_substitution  
from prune_binaries import prune_files, prune_dirs
from downloads import DownloadInfo
from filescfg import filescfg_generator

Developer Utilities

Validation and development tools for maintaining Helium

Build Process

Complete guide to building Helium from source

Building

Contributing

Utilities

Build Utilities Reference

Overview

Patch Management

patches.py

Merging Patches

Dry Run Checking

Domain Substitution

domain_substitution.py

Apply Mode

Revert Mode

Domain Regex Format

Binary Pruning

prune_binaries.py

Contingent Paths

Downloads Management

downloads.py

downloads.ini Format

Source Tree Cloning

clone.py

Packaging

filescfg.py

Version Management

helium_version.py

Name Substitution

name_substitution.py

Resource Generation

generate_resources.py

Common Patterns

Module Imports

See Also

Developer Utilities

Build Process

Build docs developers (and LLMs) love

Building

Contributing

Utilities

​Overview

​Patch Management

​patches.py

​Merging Patches

​Dry Run Checking

​Domain Substitution

​domain_substitution.py

​Apply Mode

​Revert Mode

​Domain Regex Format

​Binary Pruning

​prune_binaries.py

​Contingent Paths

​Downloads Management

​downloads.py

​downloads.ini Format

​Source Tree Cloning

​clone.py

​Packaging

​filescfg.py

​Version Management

​helium_version.py

​Name Substitution

​name_substitution.py

​Resource Generation

​generate_resources.py

​Common Patterns

​Module Imports

​See Also

Developer Utilities

Build Process

Build docs developers (and LLMs) love

Overview

Patch Management

patches.py

Merging Patches

Dry Run Checking

Domain Substitution

domain_substitution.py

Apply Mode

Revert Mode

Domain Regex Format

Binary Pruning

prune_binaries.py

Contingent Paths

Downloads Management

downloads.py

downloads.ini Format

Source Tree Cloning

clone.py

Packaging

filescfg.py

Version Management

helium_version.py

Name Substitution

name_substitution.py

Resource Generation

generate_resources.py

Common Patterns

Module Imports

See Also