Install a Toolchain

A CHERI compiler is not a drop-in label for one universal target. The architecture, operating system, application binary interface (ABI), linker, and runtime libraries must agree. A compiler that understands Morello cannot automatically build a CHERIoT image, and a pure-capability library cannot be linked into an incompatible conventional ABI.

Use the installation route supplied by your platform rather than assembling unrelated binaries by hand.

What the toolchain contains

A practical CHERI software development kit (SDK) normally includes:

• a CHERI-aware Clang compiler
• LLVM optimisation and code-generation tools
• a linker that understands capability relocations
• an assembler and binary utilities
• target headers and libraries in a sysroot
• a debugger with capability-register support
• an emulator, simulator, or deployment tool
• build metadata for the selected operating system or board

A sysroot is a directory that represents the target system’s headers, libraries, and filesystem layout. Using the host sysroot by accident is a common cause of confusing build and link failures.

CheriBSD and CHERI-RISC-V

The recommended route is cheribuild, which builds compatible components from known source revisions.

git clone https://github.com/CTSRD-CHERI/cheribuild.git
cd cheribuild
./cheribuild.py --include-dependencies sdk-riscv64-purecap

For a full bootable environment, build and run the operating system target:

./cheribuild.py --include-dependencies run-riscv64-purecap

cheribuild can also create Morello and other supported SDKs. List current targets rather than guessing a name:

./cheribuild.py --list-targets

CHERIoT

The CHERIoT project recommends its development container because it keeps the compiler, build system, simulator, and auditing tools aligned.

git clone --recursive https://github.com/CHERIoT-Platform/cheriot-rtos.git
cd cheriot-rtos

Open the repository in an editor that supports development containers. Inside the container, /cheriot-tools is commonly used as the SDK path. Follow the current CHERIoT getting-started guide for the supported image and board identifiers.

For automated builds, pin the container image or repository revision. “Latest” is convenient for learning but makes results harder to reproduce.

CHERI Linux and commercial SDKs

CHERI Linux distributions and processor suppliers may publish complete SDKs or container images. Use their release notes to match:

• processor implementation and architecture version
• kernel and user-space branch
• pure-capability or hybrid ABI
• C library and dynamic linker
• emulator, FPGA image, or board revision

A vendor kernel and an unrelated user-space SDK should be combined only when their compatibility is documented.

Verify the compiler before use

Print the compiler identity and target:

clang --version
clang --print-target-triple

For a cross compiler, use the compiler path provided by the SDK and inspect its predefined macros:

clang --target=<documented-target> -dM -E - < /dev/null

Look for the architecture and capability-related definitions described by the platform. Macro names differ across environments, so do not use one platform’s macro as a universal CHERI test.

Compile a small source file to an object, then inspect the object with the SDK’s tools:

int answer(void) {
    return 42;
}

clang --target=<documented-target> -c answer.c -o answer.o
llvm-readelf -h answer.o

Confirm that the machine, class, and ABI match the intended target. The final proof is to link and run the program in the matching operating system or firmware environment.

Keep builds reproducible

Record these values in build logs or release metadata:

• SDK or container version
• compiler commit and version
• target triple and ABI
• sysroot location or identifier
• architecture and board version
• build-system configuration
• source revision of the operating system or real-time operating system (RTOS)

CHERI is a cross-layer architecture. Reproducible results require the layers to be named together.

Continue with Build Your First Application once the compiler and target have been verified.