Building from Source

Building base/base from source means cloning the repository and compiling one or more workspace targets with Just or Cargo. Install all prerequisites before continuing.

Clone the Repository

git clone https://github.com/base/base.git
cd base

How the Build Recipes Are Organised

Build work sits in a Just module rather than in top-level recipes. You reach it by naming the module first, then the recipe:

just build release

Running just build on its own prints the recipe list instead of compiling anything. That is the module default. To see what is available:

just build

Standard Release Build

This is the usual command. It produces an optimized binary for every binary target in the workspace:

just build release

It wraps cargo build --workspace --release, and the results land in target/release/.

release is the only production profile the workspace defines. An earlier maxperf profile was removed, so there is no separate “maximum performance” build to reach for — release is what the published ghcr.io/base/node image is compiled with. Its settings are listed under build profiles.

Building Individual Targets

To compile only the node binary:

just build node

Be aware that this recipe is a debug build — it maps to cargo build --bin base-reth-node with no profile flag. For an optimized single binary, call Cargo yourself:

cargo build --release --bin base-reth-node

That writes to target/release/base-reth-node.

Building Solidity Test Contracts

Some crates need compiled Solidity contracts before their tests will run. Build them with:

just build contracts

The recipe changes into crates/utilities/test-utils/contracts, pulls dependencies with forge soldeer install, and runs forge build. Foundry must be installed first.

Debug Build (All Targets)

For an unoptimized build of every target in the workspace, including tests and benches:

just build all-targets

This one depends on contracts and elfs, so both are built for you first. Compilation is much quicker than a release build and the binaries are correspondingly slower. Reach for it while iterating.

CI-Profile Builds

Two recipes mirror what continuous integration does. Both use the ci profile, which is tuned for fast GitHub Actions runs and small target directories:

# Every target in the workspace
just build ci

# Only the crates affected by your branch
just build affected-ci

affected-ci compares against main by default. Pass another ref to compare against it instead — just build affected-ci origin/develop. When nothing is affected it reports so and exits without building.

SP1 ELF Builds

Proving work needs its SP1 ELFs compiled:

just build elfs

This delegates to just succinct build-elfs.

Build Artifacts

Command	Profile	Output
just build release	release	target/release/*
just build node	debug	target/debug/base-reth-node
just build all-targets	debug	target/debug/*
just build ci	ci	target/ci/*
just build affected-ci	ci	target/ci/* (affected crates only)
just build contracts	N/A (Foundry)	Solidity artifacts in crates/utilities/test-utils/contracts/out/
just build elfs	N/A (SP1)	Compiled SP1 ELFs

Troubleshooting

Linker errors mentioning clang or llvm — Install libclang-dev (Debian/Ubuntu) or make sure Xcode Command Line Tools are installed (macOS).

Out of memory during linking — Release builds use link-time optimization, which can consume a lot of RAM. Close other memory-heavy applications or add swap space. You can also reduce parallelism:

CARGO_BUILD_JOBS=2 just build release

Stale Solidity artifacts — If contract tests fail after pulling new changes, re-run just build contracts to recompile.

just build did nothing — That prints the module’s recipe list. Name a recipe after it, such as just build release.

Once the build completes, continue to Running the Node or Docker Builds.