Getting Started

Getting Started

Prerequisites

Dependency	Notes
CMake >= 3.16	Build system
LLVM + Clang (same major version)	Project is developed/tested with LLVM 20
C++20 compiler	Required by the project
Python 3	Needed for smoke/integration scripts (optional)

macOS

brew install cmake llvm@20

Ubuntu/Debian

# Install LLVM repository helper
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 20

# Install build dependencies
sudo apt install -y cmake llvm-20-dev libclang-20-dev clang-20

Build

Quick helper script (macOS-oriented)

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.

Manual build (recommended for reproducibility)

macOS

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_DIR=$(brew --prefix llvm@20)/lib/cmake/llvm \
  -DClang_DIR=$(brew --prefix llvm@20)/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-20/lib/cmake/llvm \
  -DClang_DIR=/usr/lib/llvm-20/lib/cmake/clang \
  -DCLANG_LINK_CLANG_DYLIB=ON \
  -DLLVM_LINK_LLVM_DYLIB=ON \
  -DUSE_SHARED_LIB=OFF
cmake --build build -j"$(nproc)"

Useful CMake options

Option	Default	Purpose
BUILD_TESTS	OFF	Build optional C++ test executable if present
ENABLE_DEBUG_ASAN	OFF	Build with ASan + debug flags
CLANG_RESOURCE_DIR	auto	Override detected clang resource dir
CLANG_LINK_CLANG_DYLIB	platform-dependent	Link clang-cpp shared library
LLVM_LINK_LLVM_DYLIB	platform-dependent	Link monolithic LLVM shared library

Verify the build

./build/cc --help

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 tests

Platform compile scripts

# macOS
bash test/scripts/macos_compile.sh

# Linux
bash test/scripts/linux_compile.sh

Python smoke scripts

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install git+https://github.com/CoreTrace/coretrace-testkit.git
python test/examples/test_smoke.py
python test/examples/test_help_smoke.py
python test/examples/test_extern_project.py

Docker validation (Linux)

docker build -f test/docker/Dockerfile .

Next

• CLI Reference
• Architecture
• Testing and Validation