Skip to content

building.md

Latest commit

 

History

History
132 lines (100 loc) · 4.55 KB

building.md

File metadata and controls

132 lines (100 loc) · 4.55 KB

Building from Source

Prerequisites

  • Rust toolchain (stable): rustup.rs
  • System C compiler (cc on macOS/Linux, MSVC on Windows)

Build

git clone https://github.com/skelpo/perry.git
cd perry

# Build all crates (release mode recommended)
cargo build --release

The binary is at target/release/perry.

Build taxonomy (dev / release / dist)

Perry has three build profiles, each tuned for a different job (#5422):

Goal Command Profile
Fastest correctness feedback cargo check -p perry —
Optimized local development cargo build --profile perry-dev -p perry perry-dev
Release-compatible build cargo build --release release
Official distribution artifacts cargo build --profile dist ... dist
  • perry-dev inherits release but disables the expensive distribution settings (lto = false, codegen-units = 16, opt-level = 1, incremental = true, no strip) so the edit/build loop stays short. Output is at target/perry-dev/perry.
  • dist mirrors release exactly (ThinLTO, codegen-units = 1, opt-level = 3, strip) and is the explicit, named profile the release workflows use for shipped artifacts. Output is at target/dist/.

After a --timings build, scripts/cargo_timing_summary.py prints the slowest units so build-time regressions are visible.

Build Specific Crates

# Runtime only (must rebuild stdlib too!)
cargo build --release -p perry-runtime -p perry-stdlib

# The .a static archives are emitted by separate wrapper crates (#5422), so a
# plain `cargo build` no longer produces them as a side effect. Build them
# explicitly when you need libperry_runtime.a / libperry_stdlib.a (e.g. to link
# compiled programs without the auto-optimize rebuild):
cargo build --release -p perry-runtime-static -p perry-stdlib-static

# Codegen only
cargo build --release -p perry-codegen

Important: When rebuilding perry-runtime, you must also rebuild perry-stdlib because libperry_stdlib.a embeds perry-runtime as a static dependency.

Slim developer CLI

The default build is the full official CLI. For compiler work you can build a slimmer CLI that omits the publish / mobile / updater / native / audit commands and the non-native codegen backends (#5422):

cargo build -p perry --no-default-features --features dev-cli

dev-cli keeps compile / run / check / types / cache / dev. Disabled commands drop out of --help, and disabled --target backends report a clear "built without the <feature> feature" error. See crates/perry/Cargo.toml for the full feature list (full-cli, publish-cli, backend-wasm, …).

Run Tests

# All tests (exclude iOS crate on non-iOS host)
cargo test --workspace --exclude perry-ui-ios

# Specific crate
cargo test -p perry-hir
cargo test -p perry-codegen-llvm

Compile and Run TypeScript

# Compile a TypeScript file
cargo run --release -- hello.ts -o hello
./hello

# Debug: print HIR
cargo run --release -- hello.ts --print-hir

Development Workflow

  1. Make changes to the relevant crate
  2. cargo build --release to build
  3. cargo test --workspace --exclude perry-ui-ios to verify
  4. Test with a real TypeScript file: cargo run --release -- test.ts -o test && ./test

Project Structure

perry/
├── crates/
│   ├── perry/              # CLI driver
│   ├── perry-parser/       # SWC TypeScript parser
│   ├── perry-types/        # Type definitions
│   ├── perry-hir/          # HIR and lowering
│   ├── perry-transform/    # IR passes
│   ├── perry-codegen-llvm/ # LLVM native codegen
│   ├── perry-codegen-wasm/ # WebAssembly codegen (--target web / --target wasm)
│   ├── perry-codegen-js/   # JS minifier (formerly the web target's codegen)
│   ├── perry-codegen-swiftui/ # Widget codegen
│   ├── perry-runtime/      # Runtime library
│   ├── perry-stdlib/       # npm package implementations
│   ├── perry-ui/           # Shared UI types
│   ├── perry-ui-macos/     # macOS AppKit UI
│   ├── perry-ui-ios/       # iOS UIKit UI
│   └── perry-jsruntime/    # QuickJS integration
├── docs/                   # This documentation (mdBook)
├── CLAUDE.md               # Detailed implementation notes
└── CHANGELOG.md            # Version history

Next Steps

  • Architecture — Crate map and pipeline overview
  • See CLAUDE.md for detailed implementation notes and pitfalls