Skip to main content
NativeLink can be built from source using three different approaches. Choose the method that best fits your development workflow.

​
Quick Comparison

Nix

Recommended
  • Reproducible builds
  • Matches CI environment
  • Cross-platform support
  • All tooling included

Bazel

Production
  • Primary build system
  • Remote execution ready
  • Strict caching
  • Advanced toolchains

Cargo

Development
  • Standard Rust workflow
  • Fast iteration
  • IDE integration
  • Direct dependencies

​
Prerequisites

Before building, ensure you have:
  • Git - For cloning the repository
  • Build tools - C++ compiler (Clang recommended)
  • Disk space - At least 10GB for build artifacts

​
Platform-Specific Requirements

  • Clang 11 or newer
  • OpenSSL development headers
  • pkg-config

​
Building with Nix

Nix provides the most reproducible builds and is the recommended method for development. It matches the CI environment closely.

​
Installation

1

Install Nix

Install Nix with flakes support using the experimental nix installer:
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
2

Install direnv (Recommended)

direnv automatically loads the development environment:
nix profile install nixpkgs#direnv
Add the hook to your shell (see direnv hook documentation).After restarting your terminal:
cd nativelink
direnv allow
Without direnv, run nix develop manually each time you enter the repository.
3

Install C++ Toolchain

The Nix environment doesn’t ship a full C++ toolchain yet. Install Clang:
# Via your package manager
# Ubuntu/Debian:
sudo apt install clang

# Arch:
sudo pacman -S clang

# Or via Nix:
nix profile install nixpkgs#clang
4

Verify Environment

Check that the Nix environment is active:
env | grep NIX
# Should show several *NIX_* environment variables

​
Building

1

Build NativeLink

# Build for your platform
nix build

# Run directly
./result/bin/nativelink --help
2

Build for Specific Platforms

# Linux x86_64 (musl)
nix build .#nativelink-x86_64-linux

# Linux aarch64 (musl)
nix build .#nativelink-aarch64-linux

# macOS builds (native compilation only)
nix build .#nativelink-x86_64-darwin  # On x86_64 macOS
nix build .#nativelink-aarch64-darwin # On aarch64 macOS
3

Build Docker Image

nix build .#nativelink-image

# Load into Docker
docker load < result

​
Development Tools in Nix

The Nix development shell includes:
  • Bazel - Build system
  • Rust - Stable toolchain with rust-analyzer
  • Pre-commit - Git hooks for code quality
  • git-cliff - Changelog generation
  • Cloud Tools - AWS CLI, Google Cloud SDK, kubectl, etc.
  • Debugging - dive, trivy for container inspection
See flake.nix:453 for the complete tool list.

​
Building with Bazel

Bazel is NativeLink’s primary build system. It provides hermetic builds with strict dependency management.

​
Installation

1

Install Bazelisk

Bazelisk automatically manages Bazel versions:
# Via Nix (recommended if using Nix environment)
nix profile install nixpkgs#bazelisk

# Via Homebrew (macOS)
brew install bazelisk

# Via npm
npm install -g @bazel/bazelisk

# Manual download
# See: https://github.com/bazelbuild/bazelisk/releases
2

Install Build Dependencies

# Clang/LLVM
# Ubuntu/Debian:
sudo apt install clang lld

# Arch:
sudo pacman -S clang lld

# macOS:
xcode-select --install

​
Building

1

Build Main Binary

bazel build //:nativelink

# Run the binary
./bazel-bin/nativelink --help
2

Build All Targets

bazel build //...
3

Build with Debug Symbols

bazel build --config=debug //:nativelink
4

Build Documentation

# All crate documentation
bazel build :docs

# Single crate
bazel build //nativelink-config:docs
See Development with Bazel for advanced usage.

​
Building with Cargo

Cargo provides the fastest iteration cycle for Rust development but requires manual dependency management.

​
Installation

1

Install Rust

Install Rust via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Ensure you have the minimum required version:
rustc --version
# Should be >= 1.87.0 (see Cargo.toml:12)
2

Install System Dependencies

# Ubuntu/Debian
sudo apt install pkg-config libssl-dev

# Arch
sudo pacman -S pkg-config openssl

# macOS
brew install openssl pkg-config

​
Building

1

Build Main Binary

cargo build --release

# Run the binary
./target/release/nativelink --help
2

Build All Workspace Members

cargo build --workspace --release
3

Build with Nix Features

cargo build --features nix
4

Build Documentation

cargo doc --workspace --no-deps

# Open in browser
cargo doc --workspace --no-deps --open
See Development with Cargo for advanced usage.

​
Verifying Your Build

Test that your build works correctly: 
# Check version
./result/bin/nativelink --version       # Nix
./bazel-bin/nativelink --version        # Bazel
./target/release/nativelink --version   # Cargo

# Run with example config
curl -O https://raw.githubusercontent.com/TraceMachina/nativelink/main/nativelink-config/examples/basic_cas.json5

./result/bin/nativelink basic_cas.json5       # Nix
./bazel-bin/nativelink basic_cas.json5        # Bazel
./target/release/nativelink basic_cas.json5   # Cargo

​
Build Artifacts

​
Nix Build Outputs

  • Binary: result/bin/nativelink
  • Docker Image: result (loadable tarball)
  • Coverage: result/index.html (from coverage builds)

​
Bazel Build Outputs

  • Binary: bazel-bin/nativelink
  • Documentation: bazel-bin/*/doc/
  • Test Results: bazel-testlogs/

​
Cargo Build Outputs

  • Debug: target/debug/nativelink
  • Release: target/release/nativelink
  • Documentation: target/doc/
  • Test Artifacts: target/debug/deps/

​
Troubleshooting

Enable flakes in your Nix configuration:
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
Install Clang/LLVM:
# Set the compiler explicitly
export CC=clang
bazel build //:nativelink
Install OpenSSL development headers:
# Ubuntu/Debian
sudo apt install libssl-dev

# Or use vendored OpenSSL
cargo build --features vendored-openssl
Clean build artifacts:
# Nix
nix-collect-garbage -d

# Bazel
bazel clean --expunge

# Cargo
cargo clean

​
Next Steps

Development with Nix

Deep dive into Nix development workflow

Development with Bazel

Learn Bazel build system features

Development with Cargo

Master Cargo development workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us