CLI Reference

CLI Reference

Synopsis

./cc [coretrace-options] [clang-options] <inputs...>

CoreTrace-specific flags are parsed first, and non-CoreTrace arguments are forwarded to Clang/Driver behavior.

Core options

Flag	Effect
-h, --help	Show help and exit
--version	Print CoreTrace Compiler <version> (LLVM <llvm version>) and exit
--instrument	Enable instrumentation pipeline and runtime linking
--in-mem, --in-memory	Use OutputMode::ToMemory (LLVM IR string/stdout)
--	Stop CoreTrace parsing; forward remaining args as-is

Running cc with no argument prints the help, like --help.

Exit codes

Code	Meaning
0	Success
1	Argument error, or the compilation reported errors

Diagnostics are written to stderr; in --in-mem mode the IR goes to stdout, so the two can be redirected separately.

Instrumentation module selection

Flag	Effect
--ct-modules=<list>	Set enabled modules among trace,alloc,bounds,vtable,all

Notes:

• --ct-modules resets module booleans (trace/alloc/bounds/vtable) before applying the list.
• Default module booleans: trace=true, alloc=true, bounds=true, vtable=false.

Instrumentation toggles

Allocation and auto-free

Flag	Default	Effect
--ct-alloc / --ct-no-alloc	enabled	Toggle allocation instrumentation
--ct-alloc-trace / --ct-no-alloc-trace	enabled	Toggle runtime alloc/free logs
--ct-autofree / --ct-no-autofree	disabled	Toggle compile-time auto-free feature bit

Bounds

Flag	Default	Effect
--ct-bounds / --ct-no-bounds	enabled	Toggle bounds instrumentation
--ct-bounds-no-abort	disabled	Log violations without abort

Trace

Flag	Default	Effect
--ct-trace / --ct-no-trace	enabled	Toggle function entry/exit tracing

VTable / virtual calls

Flag	Default	Effect
--ct-vcall-trace / --ct-no-vcall-trace	disabled	Toggle virtual call tracing hooks
--ct-vtable-diag / --ct-no-vtable-diag	disabled	Toggle diagnostic verbosity in runtime

Shadow memory

Flag	Default	Effect
--ct-shadow	disabled	Enable shadow metadata
--ct-shadow-aggressive / --ct-shadow=aggressive	disabled	Enable aggressive shadow mode

Frontend behavior

Flag	Default	Effect
--ct-optnone	disabled	Inject optnone + noinline on user-defined functions
--ct-no-optnone	disabled	Explicitly disable this behavior

Important behavior details

• -o=<file> and -x=<lang> are normalized internally to -o <file> and -x <lang>.
• Most --ct-* flags only affect compilation when --instrument is enabled.
• Exception: --ct-optnone can still affect frontend execution without --instrument.
• In --in-mem mode:
  • no linking is performed,
  • only a single compilation job is supported.
• --instrument needs the runtime archives. They are looked up in CT_RUNTIME_LIB_DIR, then <cc dir>/../lib (installed layout), then cc's own directory, then the build-tree paths recorded at configure time — which is what lets an installed prefix be moved. A directory is accepted only when it holds both archives; otherwise the run fails with instrumentation runtime archives not found. See Getting Started and API Reference.

Environment variables read by cc

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

Runtime behavior is configured by its own variables at run time, not here — see Runtime Library and Auto-Free GC.

Common examples

# C and C++
./build/cc main.c -o app_c
./build/cc main.cpp -o app_cpp

# Force C++ mode for .c source
./build/cc -x c++ legacy.c -o legacy_cpp

# Instrumented build
./build/cc --instrument --ct-modules=trace,alloc,bounds main.c -o app_inst

# VTable diagnostics
./build/cc --instrument --ct-modules=vtable --ct-vcall-trace --ct-vtable-diag main.cpp -o app_vtable

# ToMemory LLVM IR
./build/cc --in-mem -S -emit-llvm main.c

# Objective-C with allocation tracking (macOS)
./build/cc --instrument --ct-modules=alloc -fobjc-arc -framework Foundation -o app main.m

See Objective-C Support for what alloc and trace cover in Objective-C programs.