Getting Started¶
Tip
On ARM64 and AMD64 Linux and macOS hosts, we offer development shells that provide environments identical to or based on environments used in CI as an alternative to manual setup. The following instructions are for manual setup.
Installing Rust¶
Warning
Some platforms offer Rust through their package manager. Depending on the maintainer policy, this version may be
well out of date relative to stable. base-sdk is only validated against its specified minimum supported Rust
version (MSRV), its pinned nightly and stable.
Anything outside that set is untested and may result in unexpected behaviour.
It is recommended to use rustup to manage your Rust build environment. This guide assumes
that platform-specific instructions to install rustup have been followed and your $PATH variable has been
refreshed. Running it should print something like the following.
$ rustup --version
rustup 1.29.0 (28d1352db 2026-03-05)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: the currently active `rustc` version is `rustc 1.95.0-nightly (905b92696 2026-01-31)`
By default, rustup will read rust-toolchain.toml and download the necessary
components at the supported versions without further intervention. Should you want to use a different
version, please consult the vendor documentation for
RUSTUP_TOOLCHAIN (source).
Preparing the virtual environment¶
To avoid conflicting with your existing environment or with Python-based native packages managed by your host, it is recommended to create a fresh virtual environment.
Note
This guide presumes uv has already been installed on your host. Please refer to
your program of choice's documentation if using a different manager.
# Create .venv and install the versions uv.lock pins
uv sync --locked --extra dev
# Enter venv
source .venv/bin/activate
Warning
The minimum supported version is Python 3.11, support for prior versions are not expected. If you are running a more recent version of Python and are experiencing problems, please file an issue.
Installing dependencies¶
pyproject.toml supplies most but not all dependencies needed to run the lint suite, the following
packages need to be additionally sourced.
- cargo-deny
- cargo-nextest
- CodeQL 2.27 or higher
- Git
- just (task runner, see
Justfile) and optionally, its language server,just-lsp - Node.js 24 or higher (current LTS, source)
macOS (with Homebrew)¶
Note
Versioned formulae like node@24 are considered "keg-only", which may require additional steps in order to be
discoverable in PATH, see guidance from Homebrew
(source).
Linux/WSL¶
See manual installation steps for CodeQL from GitHub
(source),
you may need to update your shell to add your installation path to PATH so that codeql can be discovered by the
lint script.
Neither CodeQL nor taplo are available in official Debian or Fedora repositories and must be sourced per vendor
guidance. cargo-nextest and just-lsp are likewise best installed as Rust binary crates.
Installing taplo¶
Warning
.[dev] doesn't provide taplo, needed to run lint_cargo on Arm64 Linux. This is due to a release limitation at
PyPi (source). The following guidance is not necessary on AMD64 Linux
or macOS.
An alternative to procuring releases from the maintainers (source) is to install it as a Rust binary crate.
Debian¶
# Required because Debian trixie ships Node 20.x, deprecated in April 2026
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install git just nodejs -y
# `cargo-deny` is currently unavailable on Debian (https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=951368)
cargo install --locked cargo-deny