tubestation/BUILDING.md

Building Waterfox

This guide will walk you through the process of building Waterfox from source code.

Prerequisites

System Requirements

• RAM: At least 16GB (32GB recommended)
• Disk Space: At least 40GB free space
• CPU: Modern multi-core processor (8+ cores recommended)

Operating System

Waterfox can be built on:

• Linux: Ubuntu 22.04 or newer recommended
• macOS: macOS 15 Sonoma (ideally always the latest version)
• Windows: We strongly recommend using WSL2 (Windows Subsystem for Linux) with Ubuntu 24.04 instead of native Windows building

Development vs. Production Builds

Before starting, understand there are two main build types:

Development Builds

Purpose: Quick iteration, testing, and debugging

• Uses simpler configurations with fewer optimizations
• Faster build times
• Suitable for testing code changes and features

Production Builds

Purpose: Creating optimized, release-quality builds

• Uses aggressive optimizations (LTO, PGO)
• Much slower build times but produces faster executables
• Requires specific toolchain versions
• Uses the same process as our official releases

Setting Up the Build Environment

Common Dependencies

1. Git: For checking out the source code
2. Rust: Install via rustup
3. Python 3: Required for the build system

Linux (Ubuntu/Debian)

# Install build dependencies
sudo apt update
sudo apt install git python3 python3-pip nasm patchelf

# Set up Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install python3 nasm

# Set up Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Windows (via WSL2)

1. Install WSL2 with Ubuntu:

   wsl --install ubuntu
   

2. Open the Ubuntu terminal and install dependencies:

   sudo apt update
   sudo apt install git python3 python3-pip nasm
   
   # Set up Rust
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source $HOME/.cargo/env
   

Getting the Source Code

# Clone the repository
git clone https://github.com/BrowserWorks/Waterfox.git --recursive
cd Waterfox

# If you forgot the --recursive flag when cloning:
git submodule update --init

Understanding the Bootstrap Process

Waterfox uses Mozilla's bootstrap system which automatically downloads toolchain components. This is important to understand:

• The bootstrap system handles downloading compilers and tools
• For development builds, it downloads everything automatically
• For production builds, some components need manual installation

To manually bootstrap dependencies:

# Install browser build dependencies
./mach bootstrap --application-choice=browser

Building Waterfox - Quick Development Builds

For quick development builds, use the default .mozconfig:

# Start the build
./mach build

This will:

1. Download necessary toolchains via bootstrap
2. Build Waterfox with basic optimizations
3. Create a development-oriented build

After building, run your development build:

./mach run

Building Waterfox - Production Builds

Production builds require more setup and time, but produce optimized executables like our official releases.

Critical Notice: Version Alignment Required

When building production versions of Waterfox, the LLVM version used by Clang must match the LLVM version used by Rust. This is not optional - mismatched versions will cause build failures during Link Time Optimization (LTO).

Typical error with mismatched versions:

lld: error: Invalid attribute group entry

This happens because:

1. LTO requires compatible LLVM IR from both C/C++ (Clang) and Rust code
2. Each Rust version is built with a specific LLVM version
3. When these don't match, the linker cannot properly optimize across languages

Current Requirements

As of this writing:

• Rust 1.82-1.86: Uses LLVM 19, requiring Clang 19
• Rust 1.87+: Will use LLVM 20, requiring Clang 20

This is why we specify exact Clang versions in the production build instructions rather than using system-provided compilers.

For development builds, this alignment isn't necessary because we disable LTO to improve build times.

Step 1: Install LLVM/Clang manually

Production builds require specific LLVM/Clang versions:

# Download Mozilla's Clang 19 (pick appropriate platform)
mkdir -p $HOME/.mozbuild

# For Linux:
curl -L https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/gecko.cache.level-3.toolchains.v3.linux64-clang-19.latest/artifacts/public/build/clang.tar.zst -o clang.tar.zst
tar -xvf clang.tar.zst -C $HOME/.mozbuild

# For macOS Intel:
# curl -L https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/gecko.cache.level-3.toolchains.v3.macosx64-clang-19.latest/artifacts/public/build/clang.tar.zst -o clang.tar.zst
# tar -xvf clang.tar.zst -C $HOME/.mozbuild

# For macOS ARM:
# curl -L https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/gecko.cache.level-3.toolchains.v3.macosx64-aarch64-clang-19.latest/artifacts/public/build/clang.tar.zst -o clang.tar.zst
# tar -xvf clang.tar.zst -C $HOME/.mozbuild

Step 2: Select appropriate platform configuration

Link the configuration for your platform:

# For Linux:
ln -sf .mozconfig-x86_64-pc-linux-gnu .mozconfig

# For macOS Intel:
# ln -sf .mozconfig-x86_64-apple-darwin .mozconfig

# For macOS ARM64:
# ln -sf .mozconfig-aarch64-apple-darwin .mozconfig

# For Windows (in WSL):
# ln -sf .mozconfig-x86_64-pc-windows-msvc .mozconfig

Step 3: Choose release type

Decide if you're building a release or beta version:

# For a stable release build:
export WFX_RELEASE=1

# For a beta/pre-release build:
# export WFX_PRE_RELEASE=1

Step 4: Build with Profile Guided Optimization (PGO)

PGO creates faster executables by optimizing based on actual usage patterns. This is a two-stage process:

# Stage 1: Generate instrumented build
export GEN_PGO=1
./mach build
./mach package

# Run profile collection
./mach python build/pgo/profileserver.py --binary ./obj-*/dist/waterfox/waterfox

# Stage 2: Build with collected profile data
./mach clobber
unset GEN_PGO
export USE_PGO=1
./mach build
./mach package

The final package will be in the obj-*/dist/ directory.

Step 5: Create package

./mach package

Understanding Build Configuration Files

Waterfox includes several platform-specific config files:

• .mozconfig: Simple version for development builds
• .mozconfig-x86_64-pc-linux-gnu: Linux x64 production build
• .mozconfig-x86_64-apple-darwin: macOS Intel production build
• .mozconfig-aarch64-apple-darwin: macOS ARM64 production build
• .mozconfig-x86_64-pc-windows-msvc: Windows x64 production build

Key differences between development and production configs:

1. Compiler optimization levels:

   • Development: -Os -w (size optimization)
   • Production: -O3 -w with CPU-specific tuning flags

2. Link Time Optimization (LTO):

   • Development: Disabled for faster build times
   • Production: Enabled with --enable-lto=full

3. Rust optimization:

   • Development: Default level
   • Production: Maximum (RUSTC_OPT_LEVEL=3)

4. Profile-Guided Optimization:

   • Development: Not used
   • Production: Two-stage process as described above

5. Bootstrap settings:

   • Development: Full bootstrap (--enable-bootstrap)
   • Production: Partial bootstrap (--enable-bootstrap=-clang,-sccache)

6. Mozilla official flags:

   • Development: Not set
   • Production: Sets MOZILLA_OFFICIAL=1

Advanced Topics

Multi-locale Build

To build with multiple language packs:

./mach package-multi-locale --locales ar cs da de el en-GB en-US es-ES es-MX fr hu id it ja ko lt nl nn-NO pl pt-BR pt-PT ru sv-SE th vi zh-CN zh-TW

Custom Version Display

To set a custom version for display:

echo "My Custom Version" > browser/config/version_display.txt

Using sccache to Speed Up Builds

To enable compiler caching (reduces rebuild times):

cargo install sccache
# Make sure your .mozconfig includes:
# ac_add_options --with-ccache=sccache

Troubleshooting

Common Issues

• Bootstrap failures: Check internet connection and try ./mach bootstrap again
• Out of memory errors: Increase available RAM or reduce parallel jobs
• Rust errors: Run rustup update and add required targets
• Slow builds: Enable sccache and ensure adequate disk space
• Signature verification failures: Set MOZ_REQUIRE_SIGNING=0

Getting Help

If you encounter issues not covered here:

• Check our GitHub issues