Skip to content

Build a Linux Executable

Tom Barber edited this page Nov 5, 2026 · 1 revision

Build a Linux executable

A process target runs an existing Linux x86-64 program under Hermit, so the command must point at something that machine can execute. This page is the short version of docs/guides/build-a-linux-executable.md. Each language's status is whatever the support matrix says; nothing here changes it. Check the machine first: Is-My-Machine-Suitable.

Every build below was run on an Apple silicon Mac, or in a linux/amd64 Ubuntu 24.04 container on Docker Desktop on that Mac. Nothing was run under Hermit.

  • Build for Linux on x86-64. A Mac executable will not run.
  • Use the distribution you will run on. Ubuntu 24.04 is the measured one (glibc 2.39, as ldd --version printed in the container). A dynamically linked program uses the machine's own libc, and a recording is tied to the loader and libc.
  • Use an absolute path in command, and keep it the same for recording and replay.
Language From a Mac On Linux Run?
Go CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o prog ., then file prog the same without GOOS and GOARCH Mac cross-build run; file: ELF 64-bit LSB executable, x86-64, ... statically linked
Rust in a linux/amd64 container (below) rustup target add x86_64-unknown-linux-musl, then cargo build --release --target x86_64-unknown-linux-musl Run in a container; file: static-pie linked
C in a linux/amd64 container (below) make -C sdks/c lib BUILD=/tmp/csdk, then cc -O1 -pthread -static -Isdks/c/include prog.c /tmp/csdk/libhairspring.a -o prog Run in a container; file: statically linked
C++ the same container the same with g++ -std=c++17 ... prog.cc ... Run in a container
Java the jar is built with make -C sdks/java jar; the target runs java Not run: needs Hermit. See the matrix for the configuration measured
Python Not supported on this build (matrix). Not tried
.NET Not supported on this build (matrix). Not tried

Go is the only one that cross-compiles from a Mac without a container. The longer form with GOAMD64=v1 -trimpath -buildvcs=false -ldflags=-buildid= is what the repository's fixture uses and is shown in Running-Your-Own-Software.

Rust from a Mac. Homebrew's Rust has no rustup and no musl standard library, so build in a container. Run as one command, with the repository mounted at /hairspring and a Cargo.toml whose dependency is hairspring-sdk = { path = "/hairspring/sdks/rust" }:

docker run --rm --platform linux/amd64 -v /path/to/hairspring:/hairspring:ro -v "$PWD":/src -w /src ubuntu:24.04 sh -c '
  apt-get update -qq && apt-get install -y -qq build-essential curl ca-certificates &&
  curl -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal &&
  . /root/.cargo/env && rustup target add x86_64-unknown-linux-musl &&
  cargo build --release --target x86_64-unknown-linux-musl'

It exited 0, and file on the Mac reported static-pie linked. Without the target the build stops with error[E0463]: can't find crate for `std` and the hint to run rustup target add.

C and C++ from a Mac. Same idea:

docker run --rm --platform linux/amd64 -v /path/to/hairspring:/hairspring:ro -v "$PWD":/src -w /src ubuntu:24.04 sh -c '
  apt-get update -qq && apt-get install -y -qq build-essential &&
  make -C /hairspring/sdks/c lib CC=cc BUILD=/tmp/csdk &&
  cc -O1 -pthread -static -I/hairspring/sdks/c/include demo.c /tmp/csdk/libhairspring.a -o demo'

The SDK must be linked into the executable itself, not into a shared object. The repository's own C and C++ fixtures link the SDK archive into an ordinary dynamically linked executable; a fully static glibc build was built and checked here but not run under Hermit, and the matrix result is for the fixtures' build.

The full page has the Java target shape, the outputs and the table of what was not run.

Next: Testing-a-Service, Guest-SDKs-by-Language.

Clone this wiki locally