Skip to main content
Firedancer currently only supports Linux and requires a relatively new kernel (at least v4.18) to build.

​
System Requirements

​
Golden Configuration

The most reliable system configuration for development is:
  • Kernel version: Linux 4.18 or newer
  • Operating system: RHEL 8 or Ubuntu 22.04 (or Fedora/Debian equivalents)
  • Compiler versions: GCC 12 or Clang 15
  • CPU: Icelake Server or Epyc 2 (or newer)
  • Memory: 2 gigantic pages (2x1 GiB) per core, reserved via fd_shmem_cfg
While Firedancer aims to support tests on a wide variety of hosts (including architectures other than x86), the above configuration is what the Firedancer team uses internally. It also helps eliminate system noise such as page table walks, page faults, allocation failures, and OOM kills.

​
Supported Platforms

As of 2024, Firedancer builds on GNU/Linux sysroots with:
  • GCC 8.5 or newer
  • Clang (also supported)
  • CBMC (also supported)
The main build target (fdctl) only targets x86_64 with a Haswell-like minimum feature set (AVX2, FMA). Experimental support exists for:
  • musl Linux, macOS, FreeBSD, Solana (SVM) C programs
  • arm64, ppc64le, sBPFv1, sBPFv2

​
Initial Setup

1

Clone the repository

Clone the Firedancer repository with all submodules:
git clone --recurse-submodules https://github.com/firedancer-io/firedancer.git
cd firedancer
2

Install dependencies

Run the dependency installation script with the +dev flag to install development dependencies:
./deps.sh +dev
This script will:
  • Detect your operating system and distribution
  • Install required system packages
  • Fetch and build external dependencies into the opt/ directory
  • Use sudo for privileged operations if needed
Firedancer aims to have zero out-of-tree library dependencies. The deps.sh script fetches and builds large external dependencies, then installs includes and static libraries into a custom prefix (opt directory).
3

Configure huge pages

Allocate huge pages for optimal performance:
sudo src/util/shmem/fd_shmem_cfg alloc 2 gigantic 0
For detailed large page and NUMA configuration:
src/util/shmem/fd_shmem_cfg --help
If your MEMLOCK limit is low, increase it with:
sudo prlimit --pid $$ --memlock=$((2*1024*1024*1024))
4

Build and run

Build and run the development validator:
make -j run
The make run target runs the fddev dev command, which will:
  • Ensure your system is configured correctly
  • Create a genesis block
  • Generate keys and set up a faucet
  • Start a validator on the local machine
fddev will use sudo to make privileged changes to system configuration where needed. If sudo is not available, you may need to run the command as root.

​
Development Cluster

By default, fddev creates a new development cluster. To join this cluster with other validators:
  1. Define [rpc.entrypoints] in the configuration file
  2. Point it at your first validator
  3. Run fddev dev again

​
Dependency Management

The deps.sh script supports several commands: 
./deps.sh help
# Prints usage information

​
Build Configuration

Firedancer uses GNU Make with machine-specific configurations. The compiler discovers dependencies via: 
-isystem ./opt/include -L./opt/lib
No need for pkg-config or complex configure scripts.

​
Next Steps

Once your environment is set up:

Build docs developers (and LLMs) love

Get started for freeTalk to us