Building from source
Prerequisites, toolchains and make targets for building Airpost, and running the desktop app against your own engine.
Development happens on macOS and Linux, and the Makefile needs bash. On Windows the engine only has to compile; CI checks that.
Prerequisites
- git, Python 3, and the Node major version in
.node-version(currently 22).make setupchecks it. - Rust through rustup.
rust-toolchain.tomlpins the version (1.92, with rustfmt and clippy), and rustup installs it on first use. - A C/C++ toolchain and
make: the Xcode Command Line Tools on macOS,build-essentialon Debian and Ubuntu.npm cirebuilds better-sqlite3 against Electron. cargo install --locked cargo-deny, formake lint.- Docker, optionally.
make stackand the engine harness’s Docker tier use it.
Build and run
git clone https://github.com/airpost-mail/airpost.git
cd airpost
make setup # npm ci for apps/desktop and apps/web, Python deps in .venv, debug Rust builds
make desktop # the desktop on a sandbox profile in .dev/profile, with the debug engine
make help # every target
make desktop never touches your real profile. It builds the debug binaries, symlinks airpost-engine, airpost, airpost-mcp and airpost-gateway from target/debug/ into apps/desktop/, and starts the app with --config-dir-path=.dev/profile.
Make targets
| Target | Does |
|---|---|
make setup | Checks tools, installs JS and Python dependencies, and builds the Rust binaries |
make build | Debug builds of airpost-engine, airpost, airpost-mcp, airpost-gateway, airpost-backend and the sample service |
make release | Release builds of the same |
make desktop | The desktop on .dev/profile with the debug engine |
make airpost ARGS="status" | The debug CLI against the dev desktop’s engine |
make web | Vite dev server for apps/web on an in-browser mock engine |
make mail | Fake IMAP and SMTP accounts without Docker |
make stack | Local stack in Docker: fake mail, plus the backend with PROFILE=backend |
make stack-down / make stack-reset | Stop the stack, keeping or deleting its data |
make test | Rust workspace tests and the engine harness quick tier |
make test-desktop | The desktop’s Jasmine specs; SPEC=<regex> picks spec files |
make lint | rustfmt, clippy, cargo deny, the npm licence check, and the desktop and web linters |
make gate | The merge gate: lint, tests, release builds, and the harness on a serve engine |
Test mail accounts
make mail runs fake IMAP and SMTP servers without Docker, with two accounts: alice@airpost.test and bob@airpost.test, password airpostpass. make stack runs the same servers in Docker. make stack PROFILE=backend also starts the backend at http://127.0.0.1:5101 with the user alice@airpost.test (password airpostpass).
Running the desktop against the engine
The desktop needs an engine binary at apps/desktop/airpost-engine. make desktop links the debug one. To work on the desktop alone:
cd apps/desktop
npm ci
npm start
npm start runs Electron with --dev on the Airpost-dev profile (~/Library/Application Support/Airpost-dev on macOS, ~/.config/Airpost-dev on Linux, %APPDATA%\Airpost-dev on Windows). Pass --config-dir-path to pick another profile, and --lang to force a language:
npm start -- --lang=de
Use npm ci or npm install in apps/desktop, never a bare npm rebuild: that rebuilds better-sqlite3 for Node’s ABI instead of Electron’s. npm run check:native checks it.
While the app is running:
- Developer > Toggle Developer Tools opens the console, where
$mismailspring-exports. - Developer > Reload (
Cmd+Option+Lon macOS,Ctrl+Alt+Lon Linux,Ctrl+Shift+Ron Windows) reloads the window and picks up renderer changes. Main-process code (src/main,src/engine/supervisor) needs a restart. - Developer > Open Engine Logs opens the folder with the engine’s logs.
To run the CLI against the same engine, use make airpost ARGS="...", which sets AIRPOST_CONFIG_DIR to .dev/profile. See CLI commands.
Desktop scripts
From apps/desktop:
| Command | Does |
|---|---|
npm run lint | ESLint with Prettier, fixing what it can (lint:check only reports) |
npm run typecheck | tsc on src/, plugins/, themes/ and tests/, then the plugin API .d.ts check |
npm test | All Jasmine specs; npm test -- --spec-file-pattern='calendar' for a subset |
npm run build | Production build |
In apps/web: npm test, npm run lint and npm run typecheck.
Engine harness
make test runs the Rust tests and the harness quick tier (fake servers, no Docker, a few minutes). To run one harness case:
AIRPOST_ENGINE_BIN=target/debug/airpost-engine \
.venv/bin/python -m pytest apps/engine/test -n 0 -k <name>
python3 -m pytest apps/engine/test --all runs both tiers against every server kind. apps/engine/test/README.md describes the tiers.
Release builds of the engine exit with status 2 unless the lowercased program name contains airpost. Debug builds skip the check.
Debugging the engine
Engine logs, protocol logging, watching deltas, raw RPC calls and running the engine under a debugger are covered in Contributing. The engine’s crates, protocol and task pipeline are in Architecture.
Nix
The repository is a flake that packages airpost, airpost-engine, airpost-mcp and airpost-gateway (with the web client) for x86_64 and aarch64 Linux and macOS. The package is packaging/nix/package.nix.
nix build .#airpost # from a checkout
nix run github:airpost-mail/airpost -- status
The flake builds the command-line programs only, not the desktop app, and skips the workspace tests (they need the Python harness). For installing released builds, see Installing the CLI.