Skip to main content

​
Overview

Helium is available on all major desktop platforms, with platform-specific repositories handling builds, packaging, and distribution. Each platform repository contains the necessary configuration and build scripts tailored to that operating system.

​
Platform Repositories

Helium’s source code is organized across platform-specific repositories:

Helium for macOS

Universal binaries for Intel and Apple Silicon

Helium for Linux

AppImage builds for broad compatibility

Helium for Windows

Windows installers (auto-updates coming soon)

​
Architecture Overview

Helium’s build process follows this structure:
1

Core Repository

The main Helium repository contains:
  • Core patches in GNU Quilt format
  • Configuration files (flags.gn, downloads.ini)
  • Development and validation utilities
  • Shared build logic
2

Platform Repositories

Each platform repository includes:
  • Platform-specific patches
  • Build scripts and configurations
  • Packaging and distribution logic
  • CI/CD workflows
3

Build Process

Platform builds:
  1. Merge core patches with platform patches
  2. Download and prepare Chromium source
  3. Apply all patches
  4. Build with platform-specific flags
  5. Package for distribution

​
Download Locations

Users can download Helium from multiple sources:

​
Official Website

helium.computer

Automatically detects your OS and architecture, providing the correct build.

​
GitHub Releases

Direct downloads from each platform’s repository:
Repository: helium-macos/releasesFormats:
  • Universal DMG (Intel + Apple Silicon)
  • Auto-updates included
System Requirements:
  • macOS 11.0 (Big Sur) or later
  • Intel or Apple Silicon processor
Helium is still in beta. Unexpected issues may occur. We are not responsible for any damage caused by usage of beta software.

​
Working with Platform Patches

When developing features that require platform-specific modifications, use the platform patch utilities:

​
Merging Core Patches into Platform

The update_platform_patches.py utility helps merge Helium’s core patches into platform-specific patch sets: 
./devutils/update_platform_patches.py merge /path/to/platform/patches
What happens:
1

Backup creation

Creates series.orig - backup of the platform’s series file
2

Prepend marker

Creates series.prepend - copy of Helium’s core patches series
3

Merge operation

Prepends Helium patches to platform patches using GNU Quilt merge logic
4

Output generation

Generates series.merged - combined series file
Example workflow: 
# Clone platform repository
git clone https://github.com/imputnet/helium-macos.git
cd helium-macos

# Clone main Helium repository
git clone https://github.com/imputnet/helium.git helium-core

# Merge patches
./helium-core/devutils/update_platform_patches.py merge ./patches

# Now patches/series.merged contains combined patches

​
Unmerging After Development

After working with merged patches, extract changes back: 
./devutils/update_platform_patches.py unmerge /path/to/platform/patches
What happens:
1

Move patches back

Moves prepended Helium patches back to the core repository, preserving any modifications
2

Reconstruct series

Applies changes from series.merged back to the original series.orig format
3

Preserve comments

Maintains inline comments and formatting from the original series file
4

Cleanup

Removes intermediate files (series.merged, series.orig, series.prepend)
Only unmerge after successfully merging. The unmerge process requires series.orig, series.prepend, and series.merged files created during merge.

​
Building from Source

Each platform has its own build process. See the respective repository for detailed instructions:

​
macOS Build Process

1

Prerequisites

  • Xcode Command Line Tools
  • Python 3.8+
  • Depot Tools (Chromium build tools)
  • GNU Quilt
2

Clone and setup

git clone https://github.com/imputnet/helium-macos.git
cd helium-macos
# Follow repository-specific setup instructions
3

Download Chromium source

Platform repositories include scripts to download the correct Chromium version.
4

Apply patches

Patches are applied automatically using utilities from utils/ directory.
5

Build

# Build command varies by platform
# See platform repository README for specifics
6

Package

Automated packaging creates DMG with proper signing and notarization (macOS).

​
Linux Build Process

1

Prerequisites

  • Build essentials (gcc, g++, make)
  • Python 3.8+
  • Depot Tools
  • GNU Quilt
  • Additional dependencies per Chromium docs
2

Build AppImage

Linux builds create portable AppImage files that run on most distributions.
3

Test

chmod +x Helium-*.AppImage
./Helium-*.AppImage

​
Windows Build Process

1

Prerequisites

  • Visual Studio 2022
  • Windows 10 SDK
  • Python 3.8+
  • Depot Tools
2

Build environment

Windows builds require specific Visual Studio components and SDK versions.
3

Create installer

Packaging creates a standard Windows installer executable.
Detailed build instructions are maintained in each platform repository’s README to ensure they stay current with platform-specific requirements.

​
Platform-Specific Considerations

​
macOS

macOS builds must be signed with an Apple Developer certificate to avoid Gatekeeper warnings.Requirements:
  • Apple Developer account
  • Valid Developer ID certificate
  • Configured signing identity
macOS 10.15+ requires notarization:
  • Submit to Apple’s notary service
  • Staple ticket to DMG
  • Automated in CI/CD pipeline
Helium for macOS is built as a universal binary:
  • Single DMG works on Intel and Apple Silicon
  • Optimized for each architecture
  • Tested on both platforms
macOS builds include Sparkle framework:
  • Checks for updates periodically
  • Downloads and installs automatically
  • Maintains user data and settings

​
Linux

AppImage provides maximum compatibility:
  • Single file, no installation needed
  • Works on most distributions
  • Includes all dependencies
  • Desktop integration available
AppImage bundles essential libraries:
  • Graphics libraries (Mesa, etc.)
  • Audio subsystem
  • Font rendering
  • Excludes base system libraries (glibc, etc.)
Tested on both display servers:
  • Wayland support with XWayland fallback
  • Native X11 support
  • Automatic detection
AppImage updates via AppImageUpdate:
  • Delta updates for efficiency
  • Optional automatic checks
  • Manual update available

​
Windows

Windows installer features:
  • System-wide or per-user installation
  • Start menu shortcuts
  • File associations
  • Uninstaller
Unsigned builds may trigger SmartScreen:
  • Code signing recommended for distribution
  • Users may need to approve first run
  • Reputation builds over time
Installer can set Helium as default browser:
  • HTML files
  • HTTP/HTTPS protocols
  • PDF files (optional)
Windows auto-updates are in development:
  • Will use Chromium’s update mechanism
  • Background downloads
  • Seamless installation

​
Distribution Pipeline

Helium uses GitHub Actions for automated building and distribution:
1

Trigger

  • Push to main branch
  • New version tag
  • Manual workflow dispatch
2

Build

  • Download Chromium source
  • Apply patches
  • Build browser
  • Run validation tests
3

Package

  • Create platform-specific packages
  • Sign and notarize (macOS)
  • Generate checksums
4

Release

  • Upload to GitHub Releases
  • Update latest release
  • Trigger update checks

​
Testing Platform Builds

Before releasing, test on each platform:
Intel Testing:
  • Clean install on Intel Mac
  • Verify signature and notarization
  • Test core functionality
  • Check auto-update
Apple Silicon Testing:
  • Clean install on M-series Mac
  • Verify native ARM performance
  • Test Rosetta 2 compatibility (if needed)
  • Validate universal binary

​
Contributing to Platform Packaging

When contributing platform-specific changes:
  1. Open an issue - Discuss the change with maintainers
  2. Test locally - Build and test on the target platform
  3. Update documentation - Document platform-specific requirements
  4. Submit PR - To the appropriate platform repository
  5. Cross-platform check - Ensure changes don’t break other platforms

Platform Maintainers

Each platform repository may have dedicated maintainers familiar with platform-specific requirements. Reach out in issues or PRs for guidance.
Helium’s ecosystem includes supporting repositories:

helium-services

Backend services for Helium features

helium-onboarding

Onboarding page shown at helium://setup

ublock-origin-crx

Packaging for uBlock Origin extension

​
Troubleshooting

Solution:
  • Verify Developer ID certificate is installed
  • Check Keychain Access for certificate validity
  • Ensure signing identity is correctly configured
Solution:
  • Make executable: chmod +x Helium-*.AppImage
  • Check FUSE availability: fusermount --version
  • Try extraction mode: ./Helium-*.AppImage --appimage-extract-and-run
Solution:
  • This is normal for unsigned builds
  • Click “More info” → “Run anyway”
  • For distribution, use code signing certificate
Solution:
  • Verify Chromium version matches
  • Check patch merge was successful
  • Run ./devutils/validate_patches.py --local /path/to/src
Platform packaging is complex and platform-specific. When in doubt, refer to the official documentation in each platform repository and don’t hesitate to ask for help in issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us