Skip to content

development.md

Latest commit

 

History

History
131 lines (94 loc) · 5.13 KB

development.md

File metadata and controls

131 lines (94 loc) · 5.13 KB
Raw

Development Guide

This document describes how to build Dao Browser from source.

Prerequisites

  • macOS (initial target platform)
  • Xcode and Command Line Tools
  • depot_tools installed and in PATH
  • Node.js >= 22.19.0
  • ~100 GB free disk space for Chromium source + build

Setting up depot_tools

depot_tools is a collection of tools built by the Chromium team for managing the Chromium source code. It provides gclient (dependency management), gn (build file generation), autoninja (parallel build), and other utilities required to fetch and build Chromium-based projects.

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

# Add to your shell profile (~/.zshrc or ~/.bash_profile)
export PATH="$PATH:/path/to/depot_tools"

After adding to PATH, restart your terminal and verify:

gclient --version

Note: On first run, depot_tools will automatically bootstrap the required Python environment. Ensure you have a working internet connection.

Quick Start

npm install
npm run setup     # download chromium + apply patches
npm run rebuild   # re-import tracked sources and build Dao Browser

Commands

Command Description
npm run download Fetch Chromium source at the version specified in dao.json
npm run import Apply patches and copy Dao code into the Chromium tree
npm run export -- <file> Export one explicitly scoped Chromium file into its patch
npm run build Build Dao Browser (gn gen + autoninja)
npm run package Package into a .dmg for distribution
npm run package:zip Package into a .zip for distribution
npm run setup download + import (first-time setup)
npm run rebuild import + build (iterative development)
npm run docs:check Validate maintained documentation commands, links, and Dao URLs
npm run engine:cache:refresh Refresh the local .dao/engine warm cache for Git worktree workers
npm run setup:worktree Initialize an externally-created Git worktree for agent work
npm run archive:worktree Archive current worktree engine or dry-run stale primary copies
npm run worktree:create -- <name> Create a Git worktree with a private copy-on-write cloned engine/

Development Workflow

  1. Run npm run setup to fetch Chromium and apply all patches.
  2. Make Dao-owned changes in src/dao/ and Chromium integration changes in the matching file under src/patches/.
  3. Run npm run import to synchronize the tracked sources into engine/src.
  4. Run npm run rebuild after the related edits are complete.

src/dao/ and src/patches/ are the source of truth. Do not edit engine/ directly during routine development. When an explicitly scoped Chromium patch debugging task requires engine-first iteration, export only the intentional file with npm run export -- <file>; never run bare npm run export.

Project Structure

dao-browser/
├── dao.json          # Core config (Chromium version, branding)
├── scripts/          # TypeScript build toolchain (CLI)
├── src/
│   ├── patches/      # Patch files against Chromium (mirrors Chromium dir structure)
│   └── dao/          # Dao's own code (copied into engine/ on import)
├── configs/          # GN build arguments
└── branding/         # Brand assets (icons, logos)

Packaging

After building, create a distributable package:

npm run package       # creates dist/dao-browser-<version>-mac-arm64.dmg
npm run package:zip   # creates dist/dao-browser-<version>-mac-arm64.zip

Options:

  • --zip — produce a .zip instead of .dmg
  • --sign — apply ad-hoc code signature (off by default)

Architecture

Chromium source lives in engine/ (gitignored). Only patch files and Dao's own code are version-controlled. This follows the Zen Browser approach of maintaining a clean separation between upstream and custom code.

For a full inventory of features Dao Browser adds on top of Chromium, see features.md.

Installation Notes (Unsigned Builds)

Dao Browser is currently distributed without Apple notarization. macOS Gatekeeper will block the first launch. Use one of the following methods to open it:

Method 1 — Right-click to open (simplest)

  1. Right-click (or Control-click) on Dao Browser.app
  2. Select Open from the context menu
  3. In the dialog that appears, click Open

You only need to do this once.

Method 2 — System Settings

  1. Double-click the app (it will be blocked)
  2. Open System Settings → Privacy & Security
  3. Scroll down and click Open Anyway next to the Dao Browser message

Method 3 — Terminal (recommended)

xattr -cr /Applications/Dao\ Browser.app

This removes the quarantine attribute entirely. Run it once after each update.

Note: On macOS Sequoia (15+), Method 1 may not work. Use Method 2 or 3 instead.