API Reference

API Reference

Public headers are under include/compilerlib/.

Core API (compilerlib/compiler.h)

OutputMode

enum class OutputMode
{
    ToFile,
    ToMemory,
};

CompileResult

struct CompileResult
{
    bool success;
    std::string diagnostics;
    std::string llvmIR;
};

compile()

CompileResult compile(
    const std::vector<std::string>& args,
    OutputMode mode = OutputMode::ToFile,
    bool instrument = false
);

Behavior summary:

• ToFile: compile/link outputs on disk
• ToMemory: return LLVM IR in CompileResult::llvmIR (single-job constraint)
• instrument=true: run instrumentation pipeline and runtime linking for link jobs

compile_c()

int compile_c(int argc, const char** argv, char* output_buffer, int buffer_size);

Notes:

• Parses --in-mem and --instrument similarly to CLI.
• Writes diagnostics text into output_buffer.
• Returns 1 on success, 0 on failure.

Toolchain API (compilerlib/toolchain.hpp)

DriverConfig

struct DriverConfig
{
    std::string clang_path;
    std::string resource_dir;
    std::string sysroot;
    bool add_resource_dir = false;
    bool add_sysroot = false;
    bool force_cxx_driver = false;
};

resolveDriverConfig()

bool resolveDriverConfig(
    const std::vector<std::string>& args,
    DriverConfig& out,
    std::string& error
);

Use this when embedding and you need toolchain decisions independent of full compile execution.

RuntimeArchives / resolveRuntimeArchives()

struct RuntimeArchives
{
    std::string runtime;   // libct_instrument_runtime
    std::string logger;    // libcoretrace_logger
};

bool resolveRuntimeArchives(RuntimeArchives& out, std::string& error);

Locates the instrumentation runtime archives linked into instrumented programs. This is what makes an installed prefix relocatable: nothing is baked in as an absolute path.

Search order:

1. CT_RUNTIME_LIB_DIR
2. <executable dir>/../lib — the installed layout
3. the executable's own directory
4. the build-tree paths recorded at configure time

A directory is accepted only when it holds both archives. A directory with just one is skipped rather than half-used, which is what turns a partial install into a clear instrumentation runtime archives not found instead of a confusing link error.

With -DCORETRACE_COMPILER_BUILD_RUNTIME=OFF no archive is built or installed, so only step 1 can succeed — see Runtime Library.

Instrumentation config API (compilerlib/instrumentation/config.hpp)

RuntimeConfig

struct RuntimeConfig
{
    bool shadow_enabled = false;
    bool shadow_aggressive = false;
    bool bounds_no_abort = false;
    bool trace_enabled = true;
    bool alloc_enabled = true;
    bool bounds_enabled = true;
    bool vtable_enabled = false;
    bool vcall_trace_enabled = false;
    bool vtable_diag_enabled = false;
    bool autofree_enabled = false;
    bool alloc_trace_enabled = true;
    bool bounds_without_alloc = false;
    bool optnone_enabled = false;
};

extractRuntimeConfig()

void extractRuntimeConfig(
    const std::vector<std::string>& input,
    std::vector<std::string>& filtered,
    RuntimeConfig& config
);

• consumes/removes --ct-* options from filtered
• fills config with effective runtime/instrumentation behavior

emitRuntimeConfigGlobals()

void emitRuntimeConfigGlobals(llvm::Module& module, const RuntimeConfig& config);

Emits weak globals consumed by runtime startup (ct_runtime_env.cpp).

Linking targets

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

See Integration Guide for full setup.