diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 000000000000..90839f074586 --- /dev/null +++ b/BUILDING.md @@ -0,0 +1,321 @@ +# 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](https://rustup.rs/) +3. **Python 3**: Required for the build system + +### Linux (Ubuntu/Debian) + +```bash +# 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 + +```bash +# 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: + ```bash + 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 + +```bash +# 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: + +```bash +# Install browser build dependencies +./mach bootstrap --application-choice=browser +``` + +## Building Waterfox - Quick Development Builds + +For quick development builds, use the default `.mozconfig`: + +```bash +# 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: + +```bash +./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: + +```bash +# 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: + +```bash +# 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: + +```bash +# 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: + +```bash +# 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 + +```bash +./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: + +```bash +./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: + +```bash +echo "My Custom Version" > browser/config/version_display.txt +``` + +### Using sccache to Speed Up Builds + +To enable compiler caching (reduces rebuild times): + +```bash +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](https://github.com/BrowserWorks/Waterfox/issues) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000000..8217e5fbb263 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,181 @@ +# Contributing to Waterfox + +Thank you for your interest in contributing to Waterfox! This guide will help you understand our contribution process and how to effectively work with our codebase. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Pull Request Process](#pull-request-process) +- [Managing Upstream Changes](#managing-upstream-changes) +- [Contribution Guidelines](#contribution-guidelines) +- [Reporting Bugs](#reporting-bugs) +- [Suggesting Features](#suggesting-features) + +## Code of Conduct + +Don't be an ass. We are all human. + +## Getting Started + +Before contributing, please: + +1. Fork the repository +2. Set up your development environment following our [Build Guide](BUILDING.md) +3. Create a new branch for your changes +4. Make your changes +5. Test thoroughly + +## Pull Request Process + +We welcome pull requests but have a few important considerations: + +1. **Limited Review Bandwidth**: The core team has limited availability to review PRs. While we appreciate your contributions, please understand that it may take time for your PR to be reviewed and merged. + +2. **Not All PRs Will Be Accepted**: We maintain specific technical and design directions for Waterfox. Even well-implemented features might not be accepted if they don't align with this direction. Please don't be discouraged if your PR is declined. + +3. **PR Requirements**: + - Ensure your code follows our coding style + - Include tests where appropriate + - Update documentation to reflect any changes + - Keep PRs focused on a single issue/feature + - Provide a clear description explaining the purpose and implementation details + +4. **Review Process**: + - PRs require approval from at least one maintainer + - You may be asked to make changes before your PR is accepted + - Please respond to review comments in a timely manner + +## Managing Upstream Changes + +Waterfox is based on Firefox, and we maintain our changes as commits on top of the upstream codebase. This creates some complexity when working with the repository: + +### How Our Update Process Works + +1. We regularly pull in upstream changes from Firefox +2. We rebase our Waterfox-specific changes on top of these updates +3. This rebasing changes the commit hashes of our modifications +4. As a result, simple `git pull` operations can lead to significant merge conflicts + +### Keeping Your Fork in Sync + +If you're working on a contribution, follow these steps to avoid headaches: + +#### Before Starting New Work + +```bash +# Ensure you have the Waterfox repo as a remote +git remote add upstream https://github.com/BrowserWorks/Waterfox.git + +# Fetch the latest changes +git fetch upstream + +# Reset your main branch to match upstream +git checkout main +git reset --hard upstream/main + +# Create a new branch for your work +git checkout -b my-feature-branch +``` + +#### During Active Development (When Upstream Changes) + +If you're in the middle of development and the upstream Waterfox repository has changed: + +```bash +# Stash any uncommitted changes +git stash + +# Update your main branch +git checkout main +git fetch upstream +git reset --hard upstream/main + +# Rebase your feature branch +git checkout my-feature-branch +git rebase main + +# Resolve any conflicts that arise during rebase +# After resolving each file: +git add +git rebase --continue + +# Restore your stashed changes if needed +git stash pop +``` + +#### Alternative: Branch from Main and Cherry-Pick + +Sometimes a full rebase is too complex. In that case: + +```bash +# Create a new branch from updated main +git checkout main +git pull upstream main +git checkout -b my-feature-branch-new + +# Cherry-pick your commits from the old branch +git cherry-pick +# Resolve conflicts as needed + +# Once all commits are transferred, you can continue work on the new branch +``` + +### Identifying Your Changes After Upstream Updates + +After a major upstream update, finding your specific changes can be challenging. These approaches may help: + +1. **Use commit messages**: Maintain descriptive commit messages that clearly identify Waterfox-specific changes +2. **Create feature branches**: Keep work isolated in feature branches before submitting PRs +3. **Use git blame with caution**: The rebasing process changes commit hashes, so `git blame` might not show the original author + +## Contribution Guidelines + +### Code Style + +- Follow the existing code style in the files you're modifying +- For JavaScript/C++, we generally follow [Mozilla's coding style](https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html) +- Use meaningful variable names and add comments for complex logic + +### Commit Messages + +- Use clear, descriptive commit messages +- Start with a conventional commit type prefix: + - `fix:` for bug fixes + - `feat:` for new features + - `docs:` for documentation changes + - `style:` for formatting, missing semi-colons, etc. + - `refactor:` for code changes that neither fix bugs nor add features + - `perf:` for performance improvements + - `test:` for adding or correcting tests + - `chore:` for routine tasks, dependency updates, etc. + - `ci:` for CI/CD related changes +- After the prefix, provide a brief summary (50 chars or less) +- If needed, provide a more detailed explanation after a blank line +- **Important:** Do not reference issue numbers in commit messages to avoid notification spam during rebases + +### Documentation + +- Update documentation to reflect your changes +- Add comments to explain non-obvious code sections +- If adding new features, update relevant README or documentation files + +## Reporting Bugs + +When reporting bugs: + +1. Use the GitHub Issues tracker +2. Check if the issue already exists before creating a new one +3. Include detailed steps to reproduce +4. Provide system information (OS, Waterfox version, etc.) +5. Include screenshots or videos if applicable + +## Suggesting Features + +We welcome feature suggestions: + +1. First, check if the feature has already been suggested +2. Provide a clear description of the feature and its benefits +3. Understand that not all features will be implemented, based on our priorities and resources + +Thank you for contributing to Waterfox! diff --git a/README.md b/README.md index 01457dc06666..be6db664a3a2 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,55 @@ -![Firefox Browser](./docs/readme/readme-banner.svg) +# Waterfox -[Firefox](https://firefox.com/) is a fast, reliable and private web browser from the non-profit [Mozilla organization](https://mozilla.org/). +

A privacy-focused, performance-oriented browser based on Firefox.

-### Contributing +

+ Website + Build Status + License: MPL 2.0 + Reddit +

-To learn how to contribute to Firefox read the [Firefox Contributors' Quick Reference document](https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html). +## About Waterfox -We use [bugzilla.mozilla.org](https://bugzilla.mozilla.org/) as our issue tracker, please file bugs there. +Waterfox is an open-source, privacy-focused browser based on the popular open source browser with a red panda as a mascot. It is designed to be a drop-in replacement for said browser that offers enhanced privacy features, performance improvements, and customizability while maintaining compatibility with existing extensions. -### Resources +### Key Features -* [Firefox Source Docs](https://firefox-source-docs.mozilla.org/) is our primary documentation repository -* Nightly development builds can be downloaded from [Firefox Nightly page](https://www.mozilla.org/firefox/channel/desktop/#nightly) +- **Privacy-focused**: Removal of telemetry and tracking, with bare minimum of data collection for operation. +- **Performance-oriented**: Optimized for modern systems +- **Customizable**: Support for classic and modern extensions +- **Cross-platform**: Available for Windows, macOS, Linux and Android +- **Modern**: Regular updates to stay current with web standards -If you have a question about developing Firefox, and can't find the solution -on [Firefox Source Docs](https://firefox-source-docs.mozilla.org/), you can try asking your question on Matrix at -chat.mozilla.org in the [Introduction channel](https://chat.mozilla.org/#/room/#introduction:mozilla.org). +## Getting Started + +### Download + +You can download the latest stable version of Waterfox from our [official website](https://www.waterfox.net/download). + +### Building from Source + +For instructions on how to build Waterfox from source, please see our [Build Guide](BUILDING.md). + +## Contributing + +We welcome contributions from the community! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started. + +## Documentation + +- [Source Directory Structure](https://firefox-source-docs.mozilla.org/contributing/directory_structure.html) +- [Quick Reference for Contributors](https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html) +- [Build Documentation](BUILDING.md) + +## Community + +- [Official Website](https://www.waterfox.net) +- [Reddit](https://www.reddit.com/r/waterfox/) + +## Developer Information + +The core development team is typically available 9:00 🕘 → 17:00 🕔, Monday → Friday (UK time). This does not include [UK bank holidays](https://www.gov.uk/bank-holidays) or annual leave. + +## License + +Waterfox is licensed under the [Mozilla Public License 2.0](LICENSE).