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:
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:
This is the recommended way to develop locally. Alternatively, you can invoke Cargo directly:
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:
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
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.
./script/presubmit # runs fmt, clippy, and tests in one command
# 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 |
