BrowserOS/docs/BUILD.md

Building BrowserOS

This guide will walk you through building BrowserOS from source.

Prerequisites

macOS

• macOS (tested on M4 Max)
• Xcode and Command Line Tools
• Python 3
• Git
• ~100GB of free disk space (for Chromium source)
• ~8GB RAM minimum (16GB+ recommended)

Linux

• Ubuntu 20.04+ or similar
• build-essential package
• Python 3
• Git
• ~100GB of free disk space
• ~8GB RAM minimum (16GB+ recommended)

Windows

• Windows 10/11
• Visual Studio 2022 with C++ workload
• Python 3
• Git
• ~100GB of free disk space
• ~16GB RAM minimum

Build Instructions

Step 1: Checkout Chromium

First, you need to get the Chromium source code. Follow the official Chromium instructions:

1. Visit the Chromium Get the Code guide
2. Follow the platform-specific instructions to set up depot_tools and fetch Chromium
3. Note the path to your chromium/src directory (you'll need it for building)

Step 2: Build BrowserOS

Navigate to the BrowserOS build system:

cd packages/browseros

Debug Build (for development):

# macOS
python build/build.py --config build/config/debug.macos.yaml --chromium-src /path/to/chromium/src --build

# Linux
python build/build.py --config build/config/debug.linux.yaml --chromium-src /path/to/chromium/src --build

# Windows
python build/build.py --config build/config/debug.windows.yaml --chromium-src /path/to/chromium/src --build

Release Build (for production):

# macOS
python build/build.py --config build/config/release.macos.yaml --chromium-src /path/to/chromium/src --build

# Linux
python build/build.py --config build/config/release.linux.yaml --chromium-src /path/to/chromium/src --build

# Windows
python build/build.py --config build/config/release.windows.yaml --chromium-src /path/to/chromium/src --build

Note: The build process typically takes 1-3 hours on modern hardware. Build times may vary based on your hardware specifications.

Step 3: Run BrowserOS

After the build completes successfully, you can run BrowserOS:

macOS Debug Build:

# ARM64 (Apple Silicon)
out/Default_arm64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev --user-data-dir=/tmp/test-profile

# x64 (Intel)
out/Default_x64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev --user-data-dir=/tmp/test-profile

macOS Release Build:

# ARM64 (Apple Silicon)
out/Default_arm64/BrowserOS.app/Contents/MacOS/BrowserOS --user-data-dir=/tmp/test-profile

# x64 (Intel)
out/Default_x64/BrowserOS.app/Contents/MacOS/BrowserOS --user-data-dir=/tmp/test-profile

Linux and Windows:

The built binary will be located in the out/Default_x64/ directory. Run it with the --user-data-dir flag to create an isolated test profile.

The --user-data-dir flag is useful for creating isolated test profiles during development.

Troubleshooting

Common Issues

1. Build fails with missing dependencies

   • Make sure you've followed all prerequisite steps from the Chromium build guide
   • Ensure Xcode is up to date

2. Out of disk space

   • Chromium requires significant disk space (~100GB)

Getting Help

If you encounter issues:

• Join our Discord for community support
• Check existing issues on GitHub
• Review the Chromium build documentation for platform-specific troubleshooting

Happy building! 🚀