Skip to main content

​
Overview

Helium uses GNU Quilt-formatted patches to modify Chromium’s source code. Patches are the primary mechanism for implementing privacy features, removing bloat, and customizing the browser experience.

​
Patch Organization

Patches are organized in the patches/ directory with two main categories:
Patches inherited from ungoogled-chromium that:
  • Remove Google integration
  • Disable telemetry and tracking
  • Add privacy-enhancing features
  • Customize browser behavior
Examples:
  • disable-google-host-detection.patch
  • disable-crash-reporter.patch
  • add-ipv6-probing-option.patch

​
Setting Up Your Environment

Before developing patches, configure your environment for GNU Quilt: 
# Source the quilt configuration
source ./devutils/set_quilt_vars.sh
This sets up essential environment variables:
  • QUILT_PATCHES - Points to the patches directory
  • QUILT_DIFF_ARGS - Formatting options for diffs
  • QUILT_REFRESH_ARGS - Options for refreshing patches
  • LC_ALL=C - Ensures consistent sorting
The alias quilt='quilt --quiltrc -' fixes issues with absolute paths and preserves color output.

​
Creating a New Patch

1

Navigate to the Chromium source tree

cd /path/to/chromium/src
2

Create a new patch

quilt new patches/your-category/descriptive-name.patch
Choose an appropriate category:
  • ungoogled-chromium/ - Privacy and debloating patches
  • upstream-fixes/ - Backported fixes
3

Add files to the patch

quilt add path/to/file1.cc
quilt add path/to/file2.h
4

Make your changes

Edit the files as needed to implement your feature or fix.
5

Refresh the patch

quilt refresh
This generates the patch file with proper formatting.
6

Update the series file

Add your patch to patches/series in the appropriate location:
# Privacy features
ungoogled-chromium/your-new-patch.patch

​
Patch Best Practices

​
Naming Conventions

  • Use descriptive, kebab-case names
  • Prefix with category or purpose
  • For upstream patches, include revision number (e.g., r1570045-)
Examples:
  • disable-google-host-detection.patch
  • add-flag-to-hide-tab-close-buttons.patch
  • r1570045-improve-dragging-between-groups.patch

​
Patch Structure

All patch files must end with a newline character. The validation script will fail patches that don’t.
Each patch should:
  • Be focused on a single change or feature
  • Include context lines for clarity
  • Use unified diff format (-p ab format)
  • Have no trailing whitespace
  • Be as small as possible while remaining functional

​
Writing Patch Headers

Include descriptive headers in your patches: 
--- a/chrome/browser/some_file.cc
+++ b/chrome/browser/some_file.cc
@@ -123,6 +123,7 @@
 // Brief description of what this change does
 // and why it's necessary for Helium
 
 void SomeFunction() {
+  // Your modification
   ...
 }

​
Validating Patches

Before submitting patches, run comprehensive validation:

​
Check Patch Files

./devutils/check_patch_files.py
This validates:
  • All patches exist and are referenced in series
  • No duplicate patches in the series file
  • All patches are readable and properly formatted

​
Validate Patch Application

./devutils/validate_patches.py --remote \
  --series patches/series \
  --patches patches/
Downloads required files from Google and validates patches apply cleanly.
Requires the requests Python module.

​
Run Complete Validation

./devutils/validate_config.py
Validates:
  • All patches exist and apply correctly
  • No duplicate patches in series
  • GN flags are sorted and not duplicated
  • downloads.ini conforms to schema

​
Updating Platform Patches

When working with platform-specific repositories (macOS, Linux, Windows), use the platform patch utility:

​
Merge Patches

./devutils/update_platform_patches.py merge /path/to/platform/patches
This:
  1. Creates series.orig (backup of platform series)
  2. Creates series.prepend (copy of Helium patches)
  3. Merges Helium patches into platform patches
  4. Generates series.merged

​
Unmerge Patches

./devutils/update_platform_patches.py unmerge /path/to/platform/patches
This:
  1. Moves prepended patches back to original location
  2. Applies changes from series.merged to series.orig
  3. Preserves comments and formatting
  4. Cleans up intermediate files
Only unmerge after you’ve successfully merged. The unmerge process requires series.orig, series.prepend, and series.merged files.

​
Debugging Patch Failures

​
Enable Verbose Output

./devutils/validate_patches.py --remote --verbose
Provides detailed error information including:
  • Exact lines that failed to match
  • Context from the source file
  • Output from patch --dry-run

​
Common Issues

Cause: The Chromium source has changed since the patch was created.Solution:
  1. Refresh the patch against the current Chromium version
  2. Resolve conflicts manually
  3. Re-validate the patch
Cause: Patch file doesn’t end with a newline.Solution:
echo >> patches/your-patch.patch
Cause: The same patch is listed multiple times in patches/series.Solution: Remove duplicate entries from the series file.
Cause: The file being patched doesn’t exist in the Chromium source.Solution:
  • Verify the Chromium version matches
  • Check if the file was moved or removed upstream
  • Update the patch to reflect current source structure

​
Testing Your Patches

After creating or modifying patches:
1

Validate syntax and format

./devutils/check_patch_files.py
2

Validate application

./devutils/validate_patches.py --remote
3

Build Helium with your patches

Apply patches to Chromium source and build to ensure no compilation errors.
4

Test functionality

Manually test that your patch achieves the desired behavior without breaking existing features.

​
Contributing Patches

When submitting patches:
  1. Document the purpose - Explain what the patch does and why it’s needed
  2. Reference sources - For upstream patches, include the Chromium revision number
  3. Test thoroughly - Validate on multiple platforms if possible
  4. Follow guidelines - See Contributing for full requirements
Patches are the heart of Helium’s privacy features. Well-crafted patches make the browser better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us