Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Building Hone

Prerequisites

  • Bun – used as the test runner for most packages
  • Rust toolchain – required to build the Perry compiler and its runtime libraries
  • Perry compiler binary – compiles TypeScript to native binaries (no V8/Node.js at runtime)

Install Bun: https://bun.sh Install Rust: https://rustup.rs

Building Perry

Before compiling any Hone package to a native binary, you need a working Perry compiler.

# Build Perry (always disable LTO)
cd ../perry && CARGO_PROFILE_RELEASE_LTO=off cargo build --release -p perry

# Build Perry UI library (macOS)
cd ../perry && CARGO_PROFILE_RELEASE_LTO=off cargo build --release -p perry-ui-macos

# Rebuild Perry stdlib (after changing perry-runtime source)
cd ../perry && cargo clean -p perry-runtime --release && \
  CARGO_PROFILE_RELEASE_LTO=off cargo build --release -p perry-stdlib -p perry-ui-macos -p perry

Critical: Always set CARGO_PROFILE_RELEASE_LTO=off for all Perry Rust builds. Thin LTO produces bitcode that the macOS clang linker cannot read.

Running Tests

Each package has its own test suite. There is no monorepo-wide test runner.

cd hone-core && bun test              # 649+ tests
cd hone-editor && bun test            # 353 tests
cd hone-terminal && bun test          # 163 tests
cd hone-relay && bun test             # 48 tests
cd hone-build && bun test             # 21 tests
cd hone-themes && npm test            # 452 tests (Jest)
cd hone-extensions && npm test        # Vitest
cd hone-api && npm test               # Type-check only (tsc --noEmit)

Test runner rules:

  • hone-core, hone-editor, hone-terminal, hone-relay, and hone-build use bun test – not vitest, not npx.
  • hone-themes uses Jest.
  • hone-extensions uses Vitest.

Run a single test file:

bun test tests/buffer.test.ts

Type Checking

cd <package> && bun run typecheck
# or
cd <package> && npx tsc --noEmit

Compiling Native Binaries

Use the Perry compiler to produce platform-specific binaries from TypeScript entry points.

IDE

# macOS native binary
cd hone-ide && perry compile src/app.ts --output hone-ide

# iOS Simulator
cd hone-ide && perry compile src/app.ts --target ios-simulator --output Hone

# Web
cd hone-ide && perry compile src/app.ts --target web --output hone-ide.html

Services

cd hone-auth && perry compile src/app.ts --output hone-auth
cd hone-marketplace && perry compile src/app.ts --output hone-marketplace
cd hone-build && perry compile src/app.ts --output hone-build

UI Testing (macOS)

geisterhand screenshot --output /tmp/shot.png   # Take screenshot
geisterhand click x y                            # Click at coordinates

For iOS Simulator, use osascript (AppleScript) instead of geisterhand.