Installation

Installation

This is not a git clone && cargo run. The project vendors FlyByWire's systems crates as a pinned submodule and builds them natively, then layers a Python binding, a CLI, an MCP server, and a benchmark harness on top. Install only the layers you need — each builds on the one before it.

Commands below are PowerShell (the project is Windows-primary), but everything works on Linux/macOS with the obvious shell equivalents.

Prerequisites

Tool	Version	Needed for
Rust	1.93.0 (auto-installed by rust-toolchain.toml)	the core, the bindings
Python	≥ 3.10	the MCP server (its SDK floor); the CLI/bindings work on ≥ 3.9
Git	any recent	the pinned FlyByWire submodule
C++ build tools	MSVC (Windows)	rustup's default MSVC target

Install Rust if you don't have it:

winget install Rustlang.Rustup

On Windows, rustup uses the MSVC target. If the Visual Studio Build Tools (C++) are missing, rustup tells you during install (winget install Microsoft.VisualStudio.2022.BuildTools). The exact Rust toolchain (1.93.0) auto-installs on the first build thanks to rust-toolchain.toml.

1. Vendor FlyByWire (pinned submodule)

The FBW systems crates are a pinned submodule at core-rs/vendor/aircraft. A helper does an efficient blob-filtered + sparse clone:

.\scripts\bootstrap-vendor.ps1

The pin (13bce4b) is part of the benchmark's identity and only moves with a recorded decision — see Design-Decisions.

2. Build and run the core spike

cd core-rs
cargo run

The first build takes several minutes — it compiles the FBW monorepo's dependencies. The spike (core-rs/src/main.rs) drives the electrical slice and injects a TR / APU-GEN failure; it is also the CI smoke test.

To build and test the core (filtering vendored-code noise, this is what the /compilar-core skill runs):

cd core-rs
cargo check --all-targets
cargo test

3. Python bindings (a320_sim)

The bindings compile the Rust core into a Python extension via maturin, so this step needs both toolchains. Everything above the core (CLI, MCP, bench) imports this module.

python -m venv .venv
.\.venv\Scripts\Activate.ps1

pip install -e bindings/    # builds the Rust core into the a320_sim extension
python bindings\tests\test_smoke.py

import a320_sim now exposes the Sim class. See Controls-and-Variables and Architecture.

4. CLI (a320-cli)

The human REPL. Install it into the same environment as the bindings:

pip install -e cli/
a320-cli            # or: python -m a320_cli

On Windows this also pulls pyreadline3 (provides the readline tab-completion cmd.Cmd uses). On Linux/macOS CPython ships readline, so nothing extra is needed. Full command list: CLI-Reference.

5. MCP server (a320-mcp)

The LLM's frontend. Needs Python ≥ 3.10:

pip install -e mcp/
a320-mcp                        # cold & dark (default)
a320-mcp --start apu-running    # APU running and feeding the AC network

The server speaks stdio, so a client normally launches it — you don't run it by hand. See MCP-Server.

6. Benchmark harness (a320-bench)

The Phase-5 harness. run needs the [providers] extra (litellm); score needs nothing beyond the package:

pip install -e mcp/          # a320_mcp (START_STATES, create_server)
pip install -e bench/
# for the real-model path:
pip install -e "bench/[providers]"

See Running-the-Benchmark.

Troubleshooting

• cannot import the 'a320_sim' extension — the bindings aren't built into the active environment. Run pip install -e bindings/ in the venv you're using.
• The build pulls msfs, systems_wasm, wasm-bindgen, or anything WASM — that is a decoupling bug, never something to install. The native build must not touch FBW's WASM target. The guard is cargo tree --prefix none -e normal,build (must not list those crates). See Design-Decisions (D-005).
• Submodule directory is empty / vendor/aircraft missing — re-run .\scripts\bootstrap-vendor.ps1; the crates won't compile without it.
• Tab-completion missing in the CLI on Windows — pyreadline3 didn't install; re-run pip install -e cli/. The REPL still runs without it, just without completion.