Architecture

Architecture

CoreTrace Compiler is structured as a thin CLI layer over a reusable compilation library. The design goal is fidelity to Clang driver behavior while allowing controlled in-process interception for instrumentation.

High-level components

Component	Location	Responsibility
CLI parsing	src/cli/	Parse --help, --instrument, --in-mem; forward the rest
Compile orchestration	src/compilerlib/compiler.cpp	Build args, create driver, execute jobs
Toolchain resolution	src/compilerlib/toolchain.cpp	Resolve clang path, resource dir, sysroot, C++ mode
Instrumentation passes	src/compilerlib/instrumentation/	Transform LLVM modules
Frontend customization	src/compilerlib/frontend/	OptNoneAction wrapper
Runtime library	src/runtime/	Implement __ct_* runtime hooks

Execution model

1. Input normalization and config extraction

ArgBuilder:

• extracts runtime config from --ct-* flags,
• normalizes -o= / -x= syntax,
• resolves toolchain and injects -resource-dir/-isysroot when needed,
• appends runtime library and platform link flags for instrumented link jobs.

2. Driver compilation graph

DriverSession builds a Clang Compilation, then CoreTrace splits jobs into:

• cc1 jobs
• non-cc1 jobs (assembler/linker/etc.)

3. Path selection

• Fast path: non-instrumented ToFile and no --ct-optnone
  • delegates directly to Driver::ExecuteCompilation.
• Managed path: instrumentation, ToMemory, or optnone injection
  • runs cc1 jobs in-process (Cc1Runner),
  • runs non-cc1 jobs via Linker.

Why this architecture

• Driver fidelity: still uses Clang driver for job planning and most execution decisions.
• Controlled interception: only cc1 is intercepted when needed.
• Separation of concerns:
  • toolchain detection is isolated,
  • argument shaping is centralized,
  • runtime behavior is configured through explicit globals/env.

Key internal structures

Type	Purpose
CompileContext	Per-invocation state container
RuntimeConfig	Parsed --ct-* behavior flags
DriverConfig	Resolved toolchain settings
JobPlan	Split of cc1 vs other driver jobs

Build targets

Target	Type	Notes
cc	executable	CLI binary
compilerlib_static	static lib	recommended embedding target
compilerlib_shared	shared lib	optional embedding target
ct_instrument_runtime	static lib	linked into instrumented outputs