Quickstart

📦 Installing with Cargo

Install or Update Rust

Install

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Update

rustup update

cargo install --git https://github.com/TraceMachina/nativelink --tag v0.3.0

⚙️ Configuration

The nativelink executable reads a JSON file as it's only parameter, --config. See the configuration docs for more details and examples.

To grab the example in your current working directory, run:

curl -O https://raw.githubusercontent.com/TraceMachina/nativelink/main/nativelink-config/examples/basic_cas.json

🚀 Start NativeLink

nativelink basic_cas.json

🧪 Evaluating NativeLink

note

If Bazel is not installed follow the instructions below based on your machine.

Linux

apt install -y gcc g++ lld python3 curl

sudo apt update && sudo apt install bazel

# Verify the installation.
bazel --version

Docker-ARM

# The commands for creating docker containers can fill up space very quickly when run frequently.
# If `apt update` throws an out of space error you can run `docker system prune`
# to free up space. Be careful to make sure it's not removing any containers/images you want to keep.
docker run -it --name=NL -v $(pwd):/nativelink ubuntu:latest

# If above has already been run or trying to start in new terminal:
docker exec -it NL sh

apt update

apt install apt-transport-https curl gnupg

# Download the Bazel binary for ARM Linux.
curl -LO https://github.com/bazelbuild/bazel/releases/download/6.4.0/bazel-6.4.0-linux-arm64

# Make the binary executable.
chmod +x bazel-6.4.0-linux-arm64

# Move the binary to a directory in your PATH.
mv bazel-6.4.0-linux-arm64 /usr/local/bin/bazel

# Verify the installation.
bazel --version

Docker-x86

# The commands for creating docker containers can fill up space very quickly
# when run frequently. If `apt update` throws an out of space error you can
# run `docker system prune` to free up space. Be careful to make sure it's
# not removing any containers/images you want to keep.
docker run -it --name=NL -v $(pwd):/nativelink ubuntu:latest

# If above has already been run or trying to start in new terminal:
docker exec -it NL sh

apt update

apt install apt-transport-https curl gnupg

# Download the Bazel binary for x86 Linux.
curl -LO https://github.com/bazelbuild/bazel/releases/download/6.4.0/bazel-6.4.0-linux-x86_64

# Make the binary executable.
chmod +x bazel-6.4.0-linux-x86_64

# Move the binary to a directory in your PATH.
mv bazel-6.4.0-linux-x86_64 /usr/local/bin/bazel

# Verify the installation.
bazel --version

MacOS

# It is recommended to use x86 Docker for Intel Macs and ARM Docker for Silicon Macs.
/bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install bazel

# Verify the installation.
bazel --version

Once you've built NativeLink and have an instance running with the basic_cas.json configuration, launch a separate terminal session and run the following command to connect the running server launched above to Bazel or another RBE client:

bazel test //... \
  --remote_instance_name=main \
  --remote_cache=grpc://127.0.0.1:50051 \
  --remote_executor=grpc://127.0.0.1:50051 \
  --remote_default_exec_properties=cpu_count=1

For Windows sh;

bazel test //... `
  --remote_instance_name=main `
  --remote_cache=grpc://127.0.0.1:50051 `
  --remote_executor=grpc://127.0.0.1:50051 `
  --remote_default_exec_properties=cpu_count=1

This causes Bazel to run the commands through an all-in-one CAS, scheduler and worker.

🎉 Tada 🎉 NativeLink is working.

🌱 Building with Bazel

Build requirements:

• Bazel 6.4.0+
• A recent C++ toolchain with LLD as linker

tip

This build supports Nix/direnv which provides Bazel but no C++ toolchain (yet).

The following commands place an executable in ./bazel-bin/nativelink and start the service:

# Unoptimized development build on Unix
bazel run nativelink -- ./nativelink-config/examples/basic_cas.json

# Optimized release build on Unix
bazel run -c opt nativelink -- ./nativelink-config/examples/basic_cas.json

# Unoptimized development build on Windows
bazel run --config=windows nativelink -- ./nativelink-config/examples/basic_cas.json

# Optimized release build on Windows
bazel run --config=windows -c opt nativelink -- ./nativelink-config/examples/basic_cas.json

note

The --release flag causes link-time-optmization to be enabled, which can take a while to compile, but will result in a much faster binary.

warning

The Rust compiler (rustc) generates numerous artifacts during compilation, including dependencies, macros, and intermediate files. When compiling programs from source, be mindful of the associated files' impact on your disk usage in the bazel-bin/ directory. This directory can grow substantially in size.

If the facing issues due to this, run the following command to clear cache files:

bazel clean --expunge

📦 Building with Cargo

Build requirements:

• Cargo 1.74.0+
• A recent C++ toolchain with LLD as linker

tip

This build supports Nix/direnv which provides Cargo but no C++ toolchain/stdenv (yet).

# Unoptimized development build
cargo run --bin nativelink -- ./nativelink-config/examples/basic_cas.json

# Optimized release build
cargo run --release --bin nativelink -- ./nativelink-config/examples/basic_cas.json

warning

The Rust compiler (rustc) generates numerous artifacts during compilation, including dependencies, macros, and intermediate files. When compiling programs from source, be mindful of the associated files' impact on your disk usage in the target/ directory. This directory can grow substantially in size.

If the facing issues due to this, run the following command to clear cache files:

cargo clean

❄️ Installing with Nix

Installation requirements:

• Nix with flakes enabled

This build does not require cloning the repository, but you need to provide a config file, for instance the one at nativelink-config/examples/basic_cas.json.

The following command builds and runs NativeLink in release (optimized) mode:

nix run github:TraceMachina/nativelink ./basic_cas.json

For use in production pin the executable to a specific revision:

nix run github:TraceMachina/nativelink/<revision> ./basic_cas.json

# Get the tag for the latest commit
export LATEST=$(nix eval github:TraceMachina/nativelink#image.imageTag --raw)

# Verify the signature
cosign verify ghcr.io/tracemachina/nativelink:${LATEST} \
    --certificate-identity=https://github.com/TraceMachina/nativelink/.github/workflows/image.yaml@refs/heads/main \
    --certificate-oidc-issuer=https://token.actions.githubusercontent.com

For use in production pin the executable to a specific revision:

nix run github:TraceMachina/nativelink/<revision> ./basic_cas.json