Installation¶

Prerequisites¶

Before building Crucible, ensure the following tools are installed:

Tool	Version	Purpose
Go	1.23.0 module minimum	Build Crucible CLI tools
clang	14+	Compile libFuzzer harnesses
cmake	3.14+	Build llama.cpp
AFL++	(optional)	Alternative fuzzing engine
make	any	Build orchestration

The module declares Go 1.23.0 as its minimum. This walkthrough was checked with Go 1.27.1; the minimum version was not separately retested here.

AFL++ is optional

You only need AFL++ if you plan to use the AFL fuzzing engine. The default workflow uses libFuzzer, which ships with clang.

macOS: use Homebrew LLVM

Apple clang does not include -fsanitize=fuzzer. Install LLVM via Homebrew and use it instead:

brew install llvm
export CC=$(brew --prefix llvm)/bin/clang
export CXX=$(brew --prefix llvm)/bin/clang++

Install from source¶

Clone the repository and build all binaries:

git clone https://github.com/professor-moody/crucible.git
cd crucible
make build

make build produces exactly three binaries in the project root. These are the supported public tools:

Binary	What it does	Reference
`crucible`	Main CLI: environment checks, corpus work, campaigns, triage	crucible
`crucible-gen`	Synthetic GGUF seed generator	crucible-gen
`crucible-triage`	Crash triage and report generation	crucible-triage

If you would rather choose the output directory, build each one by name:

mkdir -p bin
go build -o bin/crucible       ./cmd/crucible
go build -o bin/crucible-gen   ./cmd/crucible-gen
go build -o bin/crucible-triage ./cmd/crucible-triage

Build these three by name, not the whole cmd/ tree

cmd/ also holds mutator archives, experiment drivers and fixture tools that are developer-only: they are not part of the supported surface, several are not CLIs at all, and one is a CGo archive with no argv interface. Building the tree with a wildcard produces binaries with no documentation and no stability expectation. make build and the three commands above are the supported set.

What is supported, and what is not¶

Every capability in the documentation carries one of these labels. If a page does not say otherwise, treat it as stable.

Label	Meaning
Stable	Built by `make build`, documented under CLI Reference, covered by `make test`
Advanced	Shipped and supported, but narrow, evolving, or needing background to interpret
Developer-only	Present in `cmd/` or `tools/`, not built by `make build`, no stability expectation
Target-dependent	Needs a local upstream source checkout and a compiled native harness
Not publicly shipped	Work in the tree that is not part of the public tool and is not documented as if it were

Nothing outside the three binaries above is part of the public tool today.

Building harnesses¶

Target-dependent

Everything in this section needs a local checkout of the upstream project you intend to test. The Quick start runs end to end without it.

Crucible ships harness source that links against llama.cpp to exercise the GGUF parsing paths. Building a harness requires a local llama.cpp checkout.

1. Clone llama.cpp:

git clone https://github.com/ggml-org/llama.cpp.git ~/src/llama.cpp

2. Build the instrumented llama.cpp library:

The harness links against llama.cpp static libraries built with ASan, UBSan, and fuzzer-no-link. Update the target checkout to current upstream HEAD and record its commit. Pass that commit explicitly because the recipe's default pin is historical. This step produces build-fuzz/ inside the llama.cpp tree:

TARGET_COMMIT=$(git -C ~/src/llama.cpp rev-parse HEAD)
make -C targets/llamacpp build-fuzz LLAMA_CPP=~/src/llama.cpp \
  LLAMA_CPP_VERSION="$TARGET_COMMIT"

Use a clean checkout and a fresh build directory or one with a matching build-fuzz/.crucible-commit marker. The recipe rejects an existing unmarked build because its objects cannot be tied to the recorded commit.

3. Build the libFuzzer harness:

make harness-libfuzzer LLAMA_CPP=~/src/llama.cpp

This compiles crucible-libfuzzer, a standalone binary instrumented with libFuzzer coverage feedback.

AFL++ harness

To build the AFL++ harness instead, run:

make harness-afl LLAMA_CPP=/path/to/llama.cpp

See Configuration: Makefile targets for the full list of build targets.

Docker¶

There is no canonical project image. Containers can be useful for reproducible Linux toolchains, but the image must still pin the target source, compiler, sanitizer runtimes, architecture, build flags, and runtime limits. A container tag by itself is not provenance.

scripts/build-linux.sh is a starting point for Linux builds; read and record the actual commands for the target being tested.

Verify installation¶

After building, confirm that the tools are available:

./crucible --help

The command list changes as capabilities are added, so the live output is authoritative. It should include environment checks (doctor), campaign controls (harness-smoke, preflight), analysis and live regression (regress, validate-oracle), and capability preservation (capability-capture, capability).

Then run the environment check:

./crucible doctor

You can also verify the other binaries:

./crucible-gen --help
./crucible-triage --help

Next: Quick start to generate a synthetic corpus, inspect it, and mutate it, with no target checkout required.