Compiling from source

Penumbra is written in Rust (opens in a new tab). To build it, you will need a recent stable version of Rust, as well as a few OS-level dependencies. We don't support building on Windows. If you need to use Windows, consider using WSL (opens in a new tab) instead.

This page aims to describe the steps necessary to work on Penumbra when setting up the build environment manually. If you want an easy-to-use setup, see the docs on developer environments, which uses Nix (opens in a new tab).

Installing the Rust toolchain

This requires that you install a recent (>= 1.75) stable version of the Rust compiler, installation instructions for which you can find here (opens in a new tab). Don't forget to reload your shell so that cargo is available in your $PATH!

You can verify the rust compiler version by running rustc --version which should indicate version 1.75 or later. The project uses a rust-toolchain.toml file, which will ensure that your version of rust stays current enough to build the project from source.

Installing build prerequisites

You must install some additional packages in order to build the Penumbra software, depending on your distribution.

xcode-select --install
brew install git-lfs
git lfs install

Cloning the repository

Once you have installed the above packages, you can clone the repository:

git clone https://github.com/penumbra-zone/penumbra

To build the versions of pcli, pd, etc. compatible with the current network, navigate to the penumbra/ folder, fetch the latest from the repository, and check out the latest tag from the releases page (opens in a new tab). Currently, that tag is v1.0.1. Substitute that value for <TAG> below:

cd penumbra && git fetch && git checkout <TAG>

If you want to build the most recent version compatible with the "preview" environment, then run git checkout main instead.

Building the binaries

Then, build all the project binaries using cargo:

cargo build --release

Linking Against RocksDB (Optional)

Development builds can avoid the cost of recompiling RocksDB for storage libraries in the Cargo workspace. This manifests as a librocksdb-sys(build) message when building or testing crates in the monorepo.

Building librocksdb.a from source

First, clone the rocksdb repository:

# Clone the repository, and enter that directory.
git clone git@github.com:facebook/rocksdb.git && cd rocksdb
 
# Checkout the version of rocksdb used in `librocksdb-sys`.
git checkout 6a43615
 
# Add an environment variable pointing to this repository:
ROCKSDB_LIB_DIR=`pwd`
 
# Compile the static `librocksdb.a` library to link against:
make static_lib

Building libsnappy.a from source

next, clone the snappy repository and follow the instructions (opens in a new tab) to build it:

# Clone the repository, and enter that directory.
git clone git@github.com:google/snappy.git && cd snappy

# Checkout the version of snappy used in `librocksdb-sys`.
git checkout 2b63814

# Initialize the submodules.
git submodule update --init

# Build snappy using cmake.
mkdir build
cd build && cmake ../ -DSNAPPY_BUILD_BENCHMARKS=OFF && make

# Add an environment variable pointing to the build/ directory.
SNAPPY_LIB_DIR=`pwd`

Building Penumbra

Once you've built rocksdb and set the environment variable, the librocksdb-sys crate will search in that directory for the compiled librocksdb.a static library when it is rebuilt.