Integration Guide

Integration Guide

CoreTrace Compiler can be embedded as a library from CMake.

FetchContent integration (recommended)

include(FetchContent)

FetchContent_Declare(cc
  GIT_REPOSITORY https://github.com/CoreTrace/coretrace-compiler.git
  GIT_TAG        main
)
FetchContent_MakeAvailable(cc)

target_link_libraries(my_app PRIVATE cc::compilerlib_static)
# or: cc::compilerlib_shared

Required configure variables

macOS

cmake -S . -B build \
  -DLLVM_DIR=$(brew --prefix llvm@20)/lib/cmake/llvm \
  -DClang_DIR=$(brew --prefix llvm@20)/lib/cmake/clang

Linux

cmake -S . -B build \
  -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

Minimal embedding example

#include "compilerlib/compiler.h"
#include <iostream>
#include <vector>

int main()
{
    std::vector<std::string> args = {"hello.c", "-o", "hello"};
    auto r = compilerlib::compile(args, compilerlib::OutputMode::ToFile, false);
    if (!r.success)
    {
        std::cerr << r.diagnostics << '\n';
        return 1;
    }
    return 0;
}

Instrumented embedding example

std::vector<std::string> args = {
    "hello.c",
    "-o", "hello_inst",
    "--ct-modules=trace,alloc,bounds",
    "--ct-autofree"
};
auto r = compilerlib::compile(args, compilerlib::OutputMode::ToFile, true);

ToMemory embedding example

std::vector<std::string> args = {"hello.c", "-emit-llvm"};
auto r = compilerlib::compile(args, compilerlib::OutputMode::ToMemory, false);
if (r.success)
{
    std::cout << r.llvmIR;
}

Local development trick

When testing an external consumer against your local checkout:

cmake -S extern-project -B extern-project/.build-python \
  -DFETCHCONTENT_SOURCE_DIR_CC=/absolute/path/to/coretrace-compiler

This pattern is used by test/examples/test_extern_project.py.

Available CMake targets

Target	Alias	Type
compilerlib_static	cc::compilerlib_static	static
compilerlib_shared	cc::compilerlib_shared	shared
ct_instrument_runtime	none	static runtime, not built with -DCORETRACE_COMPILER_BUILD_RUNTIME=OFF

Embedding without the instrumentation runtime

A consumer that only embeds compilerlib to produce LLVM IR does not need the runtime, and building it costs a coretrace-log fetch and a compile:

set(CORETRACE_COMPILER_BUILD_RUNTIME OFF CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(cc)

Neither the runtime nor coretrace-log is then fetched, built or installed; compilerlib, cc and the compilerlib unit tests still build. Instrumented compilation then needs a runtime built elsewhere, named through CT_RUNTIME_LIB_DIR — see Runtime Library and API Reference for the archive resolution order.

Pinning a version

The example above tracks main. Pin a tag for a reproducible build:

FetchContent_Declare(cc
  GIT_REPOSITORY https://github.com/CoreTrace/coretrace-compiler.git
  GIT_TAG        v0.8.0
)