Skip to content

Getting Started

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.

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

brew install codeql git node@24

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.

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.

cargo install taplo-cli

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 nodejs -y

Fedora

sudo dnf install -y git nodejs24