corysanin/tubestation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add build guide, README, contribution guide

Browse Source
This commit is contained in:
Alex Kontos
2022-01-04 10:38:02 +00:00
parent d5d069b56d
commit 58f52a838b
3 changed files with 550 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

321
BUILDING.md Normal file
View File

@@ -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)

181
CONTRIBUTING.md Normal file
View File

@@ -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 <resolved-file>
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 <commit-hash>
# 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!

59
README.md
View File

@@ -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/).
<p align="center">A privacy-focused, performance-oriented browser based on Firefox.</p>
### Contributing
<p align="center">
<a href="https://www.waterfox.net"><img src="https://img.shields.io/website?url=https://www.waterfox.net" alt="Website"></a>
<a href="https://github.com/BrowserWorks/Waterfox/actions/workflows/pipeline.yml"><img src="https://github.com/BrowserWorks/Waterfox/actions/workflows/pipeline.yml/badge.svg" alt="Build Status"></a>
<a href="https://opensource.org/licenses/MPL-2.0"><img src="https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg" alt="License: MPL 2.0"></a>
<a href="https://www.reddit.com/r/waterfox/"><img src="https://img.shields.io/reddit/subreddit-subscribers/waterfox?style=social" alt="Reddit"></a>
</p>
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).