Getting Started¶

This page covers how to set up a development environment for building with Soil.

Prerequisites¶

You need the following installed on your system:

Rust (stable toolchain, latest version recommended)
C compiler and linker (gcc, clang, or equivalent)
System libraries required by RocksDB and networking: libssl-dev, pkg-config, libclang-dev, protobuf-compiler

Ubuntu / Debian¶

sudo apt update
sudo apt install -y build-essential git clang curl libssl-dev \
    pkg-config libclang-dev protobuf-compiler

Install Rust¶

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Soil targets the stable Rust toolchain. The Wasm runtime compilation uses the wasm32-unknown-unknown target, which is added automatically by the build scripts when needed.

Clone and Build¶

git clone https://github.com/soil-rs/soil.git
cd soil/soil
cargo build --release

Build times

A full release build of the entire workspace can take a while on the first run, since the workspace includes many crates and their dependencies. Subsequent builds are incremental and much faster.

For a quicker compilation-only check (no linking or test binaries):

cargo check --all --tests

Run the Test Suite¶

cargo test --all --release

Warning

The full test suite takes 30+ minutes. During development, run tests for individual crates instead:

cargo test -p subsoil --release
cargo test -p topsoil-core --release
cargo test -p plant-balances --release

Project Structure at a Glance¶

After cloning, the workspace lives under soil/:

soil/
├── main/           # Core framework crates (subsoil, topsoil, soil-*)
├── runtime/        # Pallets (plant-*)
├── contrib/        # Optional / contributed pallets
├── harness/        # Test utilities and mock runtimes
├── library/        # Standalone tools (subkey, wasm-builder)
├── Cargo.toml      # Workspace root
└── README.md

See Architecture for a detailed explanation of each directory.

Next Steps¶

Once your environment is set up, continue to Building a Minimal Node for a guided walkthrough of assembling a working blockchain node from Soil crates.