Getting Started

Getting Started

Prerequisites

Dependency	Notes
CMake ≥ 3.16	Build system
LLVM + Clang, same major version	16 to 20 are supported
C++20 compiler	Required by the project
Python 3	Smoke and integration scripts

CI builds everything with LLVM 20 on Linux, macOS and Windows, and additionally builds compilerlib and cc with LLVM 16 on Ubuntu 22.04, which is the floor the project keeps working.

macOS

brew install cmake llvm@20

Ubuntu/Debian

wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 20
sudo apt install -y cmake llvm-20-dev libclang-20-dev clang-20

Build

Quick helper script

build.sh expects to be run from the build/ directory.

git clone https://github.com/CoreTrace/coretrace-compiler.git
cd coretrace-compiler
mkdir -p build && cd build
../build.sh

Output binary: build/cc.

macOS

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_DIR=$(brew --prefix llvm)/lib/cmake/llvm \
  -DClang_DIR=$(brew --prefix llvm)/lib/cmake/clang \
  -DUSE_SHARED_LIB=OFF
cmake --build build --config Release

Linux

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_DIR=/usr/lib/llvm-${LLVM_VERSION}/lib/cmake/llvm \
  -DClang_DIR=/usr/lib/llvm-${LLVM_VERSION}/lib/cmake/clang \
  -DCLANG_LINK_CLANG_DYLIB=ON \
  -DLLVM_LINK_LLVM_DYLIB=ON \
  -DUSE_SHARED_LIB=OFF
cmake --build build -j"$(nproc)"

Windows

A native build produces cc.exe under dist/windows/bin:

powershell -ExecutionPolicy Bypass -File .\scripts\build-windows.ps1 `
  -LLVMDir "C:\LLVM\lib\cmake\llvm" `
  -LoggerSourceDir "C:\path\to\coretrace-log" `
  -Configuration Release

CI builds this job on windows-2022 against a pinned LLVM 20.1.0 archive. See Windows Support for what the runtime does and does not cover there.

Building without the instrumentation runtime

A tool that only embeds compilerlib to produce LLVM IR can skip the runtime entirely:

cmake -S . -B build -DCORETRACE_COMPILER_BUILD_RUNTIME=OFF

The runtime and its logger, coretrace-log, are then neither fetched, built nor installed; compilerlib, cc and the compilerlib unit tests still build. --instrument then links a runtime built elsewhere, from the directory CT_RUNTIME_LIB_DIR names, and otherwise fails with instrumentation runtime archives not found.

Install

cmake --install build --prefix /opt/coretrace
/opt/coretrace/bin/cc --version

The prefix contains bin/cc, lib/libct_instrument_runtime.a, lib/libcoretrace_logger.a and include/.

The install is relocatable: cc finds the runtime archives relative to its own location, so the prefix can be moved. Overrides:

Variable	Purpose
CT_RUNTIME_LIB_DIR	Directory holding both runtime archives
CT_CLANG	clang executable to drive
CT_CLANG_RESOURCE_DIR	clang resource directory

test/examples/test_install_layout.py checks the installed layout.

Useful CMake options

Option	Default	Purpose
CORETRACE_COMPILER_BUILD_RUNTIME	ON	Build the native instrumentation runtime
CORETRACE_BUILD_UNIT_TESTS	ON	Build the GoogleTest unit tests (top-level builds only)
ENABLE_DEBUG_ASAN	OFF	Debug symbols + AddressSanitizer
USE_SHARED_LIB	platform-dependent	Build/link compilerlib_shared
CLANG_RESOURCE_DIR	auto	Override the detected clang resource dir
CLANG_LINK_CLANG_DYLIB	platform-dependent	Link the clang-cpp shared library
LLVM_LINK_LLVM_DYLIB	platform-dependent	Link the monolithic LLVM shared library

Verify the build

./build/cc --help
./build/cc --version        # CoreTrace Compiler <version> (LLVM <llvm version>)

echo 'int main(){return 0;}' > /tmp/ct_smoke.c
./build/cc /tmp/ct_smoke.c -o /tmp/ct_smoke
/tmp/ct_smoke && echo OK

Run the tests

ctest --test-dir build --output-on-failure   # GoogleTest unit tests (1.17.0, fetched at configure time)
python3 test/examples/test_smoke.py          # compiler smoke tests (needs coretrace-testkit)
bash test/run_autofree_tests.sh              # auto-free fixtures
bash test/run_runtime_tests.sh               # alloc, new/delete, shadow, bounds and vtable fixtures

Both shell runners take an output directory as first argument and read CC_BIN to point at another compiler binary. Details in Testing and Validation.

Next

• CLI Reference
• Architecture
• Instrumentation
• Testing and Validation