Building from Source

Build NativeLink from source using Nix, Bazel, or Cargo

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

Linux

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

macOS

• Xcode Command Line Tools
• Homebrew (optional but recommended)

Windows

• Windows 10/11 with WSL2
• Visual Studio 2019+ Build Tools (for native builds)

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

Nix build fails with 'experimental features not enabled'

Enable flakes in your Nix configuration:

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Bazel fails with 'Cannot find C++ compiler'

Install Clang/LLVM:

# Set the compiler explicitly
export CC=clang
bazel build //:nativelink

Cargo fails with OpenSSL errors

Install OpenSSL development headers:

# Ubuntu/Debian
sudo apt install libssl-dev

# Or use vendored OpenSSL
cargo build --features vendored-openssl

Out of disk space during build

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