Skip to content

BUILDING.md

Latest commit

 

History

History
321 lines (222 loc) · 8.82 KB

BUILDING.md

File metadata and controls

321 lines (222 loc) · 8.82 KB

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: