> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
./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`.

<Note>
  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.
</Note>

## Building and running

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

```bash theme={null}
./script/run
```

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

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
cargo bundle --bin warp
```

## Running tests

Warp uses [cargo-nextest](https://nexte.st/) for parallel test execution. The full workspace test command is:

```bash theme={null}
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:

```bash theme={null}
# 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:

  ```rust theme={null}
  #[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.

<Tip>
  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.
</Tip>

## Linting and formatting

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

```bash theme={null}
./script/presubmit   # runs fmt, clippy, and tests in one command
```

You can also run each step individually:

```bash theme={null}
# 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 {} +
```

<Warning>
  `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.
</Warning>

## 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.