Build and run Warp from source

Set up your Rust toolchain, run the bootstrap script, build Warp with Cargo, and execute the full test and lint suite before opening a PR.

Warp is built in Rust with a custom UI framework called WarpUI. The repository is a Cargo workspace with 34+ member crates. This page walks through everything you need to go from a fresh checkout to a running local build, including platform-specific setup, the test suite, and the presubmit checks required before every PR.

Prerequisites

You need a working Rust toolchain. The exact toolchain version is pinned in rust-toolchain.toml at the repository root — rustup will automatically download the correct version when you run any Cargo command.

Additional platform-specific dependencies (C compilers, system libraries, bundler tools) are installed by the bootstrap script described below.

Bootstrap

The ./script/bootstrap script performs all platform-specific setup in one step. Run it once after cloning the repository:

./script/bootstrap

Internally, bootstrap delegates to a platform-specific script:

• macOS — ./script/macos/bootstrap
• Linux — ./script/linux/bootstrap
• Windows — ./script/windows/bootstrap

It also calls ./script/install_cargo_build_deps to install the Cargo build-time tooling (cargo-bundle, etc.) and ./script/install_cargo_test_deps to install testing dependencies such as cargo-nextest.

Re-running bootstrap is safe. If dependencies are already installed, the script skips them. Run it again after pulling a major update if you see unexpected build errors.

Building and running

Use ./script/run to build and launch Warp in a single step:

./script/run

This is the recommended way to develop locally. Alternatively, you can invoke Cargo directly:

cargo run

Connecting to a local server

If you are also running warp-server locally, use the with_local_server feature flag to connect the client to it:

# Connect to the default port (8080)
cargo run --features with_local_server

# Connect to a custom port
SERVER_ROOT_URL=http://localhost:8082 \
  WS_SERVER_URL=ws://localhost:8082/graphql/v2 \
  cargo run --features with_local_server

Environment variable	Default	Purpose
SERVER_ROOT_URL	http://localhost:8080	HTTP endpoint for the Warp server
WS_SERVER_URL	ws://localhost:8080/graphql/v2	WebSocket endpoint for GraphQL subscriptions

Bundling

To produce a bundled application (macOS .app, Linux package, etc.) use:

cargo bundle --bin warp

Running tests

Warp uses cargo-nextest for parallel test execution. The full workspace test command is:

cargo nextest run --no-fail-fast --workspace --exclude command-signatures-v2

The command-signatures-v2 crate is excluded because it requires a separate build step. For most development you can also run tests for a single package:

# Run tests for a specific crate with optional features
cargo nextest run -p warp_completer --features v2

# Run standard Cargo tests (slower, no parallelism)
cargo test

# Run doc tests
cargo test --doc

Where tests live

• Unit tests are in separate files following the convention ${filename}_tests.rs or mod_test.rs, included at the end of their corresponding module:

  #[cfg(test)]
  #[path = "panel_test.rs"]
  mod tests;
  

• Integration tests live under crates/integration/ and cover end-to-end user-facing flows. The bar for integration tests is high: if a flow is worth shipping, it is usually worth an integration test.

Bug fixes should include a regression test that would have caught the bug. Algorithmic or non-trivial logic needs unit tests. User-facing flows should have integration test coverage when the behavior can be exercised that way.

Linting and formatting

All of the following must pass before opening or updating a PR:

./script/presubmit   # runs fmt, clippy, and tests in one command

You can also run each step individually:

# Format Rust code
cargo fmt

# Run Clippy (warnings are errors)
cargo clippy --workspace --all-targets --all-features --tests -- -D warnings

# Format C/C++/Obj-C code (used in WarpUI native layer)
./script/run-clang-format.py -r --extensions 'c,h,cpp,m' \
  ./crates/warpui/src/ ./app/src/

# Check WGSL shader formatting
find . -name "*.wgsl" -exec wgslfmt --check {} +

cargo fmt and cargo clippy must pass completely before you create or update a pull request. CI will block merges on lint failures, so fixing them after pushing wastes review cycles.

Changelog entries

When your PR introduces user-visible changes, add a changelog entry at the bottom of the PR description using one of these prefixes:

Prefix	When to use
CHANGELOG-NEW-FEATURE:	New, relatively sizable features
CHANGELOG-IMPROVEMENT:	New functionality on an existing feature
CHANGELOG-BUG-FIX:	Fixes for known bugs or regressions

Leave changelog lines blank or omit them entirely for docs-only or refactoring changes.