Development setup

This page takes you from a fresh clone of the Apollo Download Manager repository to a running development window on Windows, Linux or macOS. If something fails, see TROUBLESHOOTING.md.

Quick start

After installing the prerequisites below:

pnpm check:prereqs            # checks Node.js, pnpm, Rust and the platform libraries; prints the fix for anything missing
pnpm install --frozen-lockfile
pnpm dev                      # builds the Rust shell and opens the app with hot reload

The first pnpm dev compiles every Rust dependency and takes several minutes (see Build times). Later runs reuse the build.

You should see a window titled Apollo Download Manager (dev). The first time, it asks where downloads should go. After that, it opens on the downloads, with the navigation and the status bar (UI_ARCHITECTURE.md):

The same window in the dark theme:

To try the app without touching your own development data, point it at another folder: VELOCITY_V2_DATA_DIR=<folder> pnpm dev (COEXISTENCE.md).

The same build on Linux (Ubuntu 24.04 under WSL2/WSLg):

Prerequisites

pnpm check:prereqs checks all of these. It only reads your system; it never installs or changes anything.

pnpm

Use one of the routes from the pnpm installation docs:

• Corepack (bundled with the Node.js releases we support): run corepack enable once. Corepack then runs the exact pnpm version pinned in package.json.

• npm: npx get-pnpm (needs Node.js 22.13 or newer). pnpm's docs recommend this route on Windows, because Windows Defender may block the standalone installer.

Note that pnpm setup and pnpm doctor are built-in pnpm commands, which is why the prerequisite check is named check:prereqs.

Windows 10/11

Requirements from the Tauri prerequisites:

1. Microsoft C++ Build Tools with the Desktop development with C++ workload: https://visualstudio.microsoft.com/visual-cpp-build-tools/.

2. WebView2 Runtime. It is preinstalled on Windows 10 (1803 and later) and Windows 11; otherwise install the Evergreen Bootstrapper from https://developer.microsoft.com/microsoft-edge/webview2/.

3. Rust: winget install --id Rustlang.Rustup, and choose the MSVC toolchain (x86_64-pc-windows-msvc) as the default host. Open a new terminal afterwards.

4. Node.js LTS from https://nodejs.org/, then pnpm as described above.

Linux (Debian/Ubuntu)

sudo apt update
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

Then install Node.js and pnpm. Fedora and Arch package lists are in the Tauri prerequisites.

macOS

xcode-select --install
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

Then install Node.js and pnpm.

Everyday commands

Run pnpm check:fast before every pull request. TESTING.md describes each level, how check:pr picks checks, and the build settings that keep feedback fast.

Running beside the original Velocity Download Manager

The app is named Apollo Download Manager (ADR-0018), and runs beside V1, during development and after release:

The bundle identifier, not the name, keeps the apps apart: it decides the data directory and the single-instance lock. Tests in velocity-core and src-tauri fail if Apollo Download Manager's identifier, data folder, pipe name, native host name or dev port ever matches V1's. The identity lives in branding.json; COEXISTENCE.md has the details. Apollo Download Manager keeps its own identity after release too (ADR-0003): the installer offers to remove V1 (#81), and importing V1 data is a separate decision (#24).

Build times

The two tables below were measured on 2026-10-21, before the #3 profile change (check timings has the current figures).

Windows 11 (build 26200), Intel Core i7-13620H (16 logical CPUs), 15.7 GiB RAM, NVMe SSD, Rust 1.99.1, Node.js 24.12.0, pnpm 12.14.0:

Linking the desktop executable dominates incremental rebuilds. Issue #3 tuned this (see check timings).

Linux: Ubuntu 24.04.4 LTS under WSL2 (kernel 6.6.87.2) on the same PC, limited to 2 vCPUs and 1.9 GiB RAM, with the same tool versions:

Check timings

Measured 2026-10-21 for #3 on the two machines above. Each figure is the median of node scripts/check-fast.mjs wall time after one warm-up run. "One-file change" means appending a comment line to crates/velocity-core/src/lib.rs before each run. That rebuilds the core and the desktop shell that depends on it.

• Windows: 5 runs on each side, with the same scripts and only the Cargo.toml profile change reverted for "before". A first measurement on main's scripts, with 3 runs, gave 7.5 s and 25.8 s.

• Linux: 3 runs before, on main, and 5 runs after.

• Where the time goes: in a no-op run, mostly ESLint (about 4.5 s on Windows, 3 s on Linux). After a Rust change, mostly cargo test, which re-links the desktop shell. Before tuning, that link wrote a staticlib of about 660 MB on Linux; it is now about 140 MB. Under WSL's 1.9 GiB of memory, the link time varied a lot.

pnpm check:full on Windows: 249 s, of which the Rust release build took 232 s. Linux (WSL2): 224 s across the checks, of which the Rust release build took 215 s.

Repository layout