Skip to main content
This page documents the developer utilities available in the devutils/ directory. These scripts help validate configuration files, check patches, and maintain code quality during development.

​
Overview

The developer utilities are a collection of Python scripts designed to ensure the integrity and consistency of Helium’s build configuration. They validate patches, check configuration files, and help maintain platform-specific patches.

​
Configuration Validation

​
validate_config.py

Run comprehensive sanity checks on all configuration files. 
python3 devutils/validate_config.py
  • All patches exist and are referenced in patch order
  • No duplicate patches in series files
  • GN flags in flags.gn are sorted and not duplicated
  • downloads.ini conforms to its schema
This script is hardcoded to run over Helium’s config files in the repository root. Returns exit code 0 if no problems detected, 1 for warnings or errors.

​
check_gn_flags.py

Validate GN build flags for proper formatting. 
python3 devutils/check_gn_flags.py
​
-f, --flags-gn
path
default:"flags.gn"
Path to the GN flags file to check
Validation checks:
  • Flags are sorted alphabetically
  • No duplicate flag definitions
  • Proper key=value format

​
check_downloads_ini.py

Validate the downloads configuration file schema. 
python3 devutils/check_downloads_ini.py
​
-d, --downloads-ini
path[]
default:"downloads.ini"
List of downloads.ini files to validate
Verifies that all download configurations conform to the expected schema, including URL formats, hash specifications, and extractor settings.

​
Patch Validation

​
validate_patches.py

Validate that all patches apply cleanly against the Chromium source tree.
This script requires either a local unmodified source tree or the Python requests module to download files from Google.
python3 devutils/validate_patches.py \
  --local /path/to/chromium/src \
  --series patches/series \
  --patches patches/
​
-s, --series
path
default:"patches/series"
The series file listing patches to apply
​
-p, --patches
path
default:"patches"
The patches directory to read from
​
-l, --local
path
Use a local source tree (must be unmodified)
​
-r, --remote
boolean
Download required source files from Google
​
-c, --cache-remote
path
Store required remote files in a local directory (for debugging)
​
-v, --verbose
boolean
Enable verbose logging for detailed error information
  1. Loads all patches from the series file
  2. Parses Chromium’s DEPS file to understand repository structure
  3. Downloads or reads required source files
  4. Applies patches using unidiff to verify they match cleanly
  5. Reports any patches that fail validation

​
check_patch_files.py

Run sanity checks on patch files and series configuration. 
python3 devutils/check_patch_files.py
​
-p, --patches
path
default:"patches"
Path to the patches directory
Validation checks:
  • All patches are readable and parseable as unified diffs
  • All patches exist at specified paths
  • All patches are referenced by the series file
  • No duplicate patches in the series
  • No unused patches in the directory

​
check_files_exist.py

Quick validation that files in a list exist in the source tree. 
python3 devutils/check_files_exist.py /path/to/chromium/src pruning.list
​
root_dir
path
required
The directory to check files from
​
input_files
path[]
required
One or more file lists to validate
Useful for CI checks to quickly verify that pruning lists and domain substitution lists reference valid files.

​
Platform Patches

​
update_platform_patches.py

Merge ungoogled-chromium patches with platform-specific patches. 
python3 devutils/update_platform_patches.py \
  merge \
  /path/to/platform/patches
​
command
enum
required
merge - Prepend ungoogled-chromium patches to platform patches
unmerge - Undo the merge and preserve changes
​
platform_patches
path
required
Path to platform patches in GNU Quilt format
When merging:
  1. Creates series.orig backup of platform series
  2. Copies ungoogled-chromium series to series.prepend
  3. Merges patches and creates series.merged
  4. Prepends ungoogled-chromium patches to platform patches
When unmerging:
  1. Moves prepended patches back to original location
  2. Applies changes from series.merged to original series
  3. Preserves comments and inline annotations
  4. Removes intermediate files

​
List Management

​
update_lists.py

Automatically update binary pruning and domain substitution lists.
This script downloads and unpacks the source tree. It will not apply binary pruning or domain substitution, only update the lists.
python3 devutils/update_lists.py \
  --tree /path/to/chromium/src \
  --pruning pruning.list \
  --domain-substitution domain_substitution.list \
  --domain-regex domain_regex.list
​
-t, --tree
path
required
Path to the source tree to analyze
​
--pruning
path
default:"pruning.list"
Output path for pruning.list
​
--domain-substitution
path
default:"domain_substitution.list"
Output path for domain_substitution.list
​
--domain-regex
path
default:"domain_regex.list"
Path to domain_regex.list patterns
​
--processes
integer
Maximum worker processes (defaults to CPU count)
​
--domain-exclude-prefix
string
Additional exclusion prefix (can be specified multiple times)
​
--no-error-unused
boolean
Don’t treat unused patterns as errors
Binary Pruning:
  • Matches against include patterns (higher priority)
  • Matches against exclude patterns
  • Performs binary data detection on remaining files
  • Excludes safe file extensions (.png, .jpg, .txt, etc.)
Domain Substitution:
  • Matches files against include patterns (*.cc, *.h, *.py, etc.)
  • Excludes paths by prefix (test directories, licenses)
  • Searches file contents for domain patterns
  • Only includes files with actual domain matches

​
Code Quality

​
Pylint Scripts

Run pylint checks on different parts of the codebase. 
python3 devutils/run_devutils_pylint.py
These scripts ensure code quality and consistency across the Python utilities.

​
Exit Codes

All validation scripts follow a consistent exit code pattern:
​
0
success
No problems detected - all validation checks passed
​
1
error
Warnings or errors occurred during validation

​
Common Workflows

# Validate all configuration
python3 devutils/validate_config.py

# Check patches apply cleanly
python3 devutils/validate_patches.py --local /path/to/src

# Run code quality checks
python3 devutils/run_devutils_pylint.py

# Download/extract new Chromium source
# ...

# Update binary pruning and domain substitution lists
python3 devutils/update_lists.py --tree /path/to/chromium/src

# Validate the source tree has expected files
python3 devutils/check_files_exist.py /path/to/chromium/src \
  pruning.list domain_substitution.list

# Merge ungoogled-chromium patches with platform patches
python3 devutils/update_platform_patches.py merge /path/to/platform/patches

# Make platform-specific changes
# ...

# Unmerge and preserve changes
python3 devutils/update_platform_patches.py unmerge /path/to/platform/patches

​
See Also

Build Utilities

Core build utilities for patches, domain substitution, and binary pruning

Validation Tools

Testing and validation utilities for ensuring build integrity

Build docs developers (and LLMs) love

Get started for freeTalk to us