Build System

Build System

The project uses CMake 3.16+ with C++20 and LLVM as the primary dependency.

---

CMake Configuration

Quick Build

./build.sh --type Release

Manual CMake

cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_DIR=/usr/lib/llvm-20/lib/cmake/llvm \
  -DClang_DIR=/usr/lib/llvm-20/lib/cmake/clang \
  -DLLVM_LINK_LLVM_DYLIB=ON

cmake --build build -j$(nproc)

---

CMake Options

Option	Default	Description
BUILD_CLI	ON	Build the stack_usage_analyzer CLI binary
BUILD_SHARED_LIB	ON	Reserved compatibility option (current target is still stack_usage_analyzer_lib static library)
BUILD_ANALYZER_UNIT_TESTS	OFF	Build unit tests (standalone builds only)
ENABLE_STACK_USAGE	OFF	Emit per-function .su files
ENABLE_DEBUG_ASAN	OFF	Enable AddressSanitizer + debug symbols
LLVM_LINK_LLVM_DYLIB	ON	Link against libLLVM shared library

---

CMake Targets

Target	Type	Description
stack_usage_analyzer_lib	Static library	Core analysis engine
coretrace::stack_usage_analyzer_lib	Alias	For FetchContent consumers
stack_usage_analyzer	Executable	CLI tool (requires BUILD_CLI=ON)
stack_usage_analyzer_unit_tests	Executable	Unit tests (requires BUILD_ANALYZER_UNIT_TESTS=ON)
format	Custom	Run clang-format on all sources
format-check	Custom	Verify clang-format compliance

---

Dependencies

Required

Dependency	Minimum Version	How It's Found
LLVM	19	find_package(LLVM REQUIRED CONFIG)
Clang	(matches LLVM)	Via LLVM

FetchContent (auto-downloaded)

Dependency	Repository	Purpose
coretrace-compiler	CoreTrace/coretrace-compiler	C/C++ to LLVM IR compilation
coretrace-logger	CoreTrace/coretrace-log	Structured logging

Both are fetched from main branch during CMake configure.

---

LLVM Linking

The default mode is dynamic linking (LLVM_LINK_LLVM_DYLIB=ON), which links against libLLVM.so/libLLVM.dylib.

If dynamic linking is not available, set LLVM_LINK_LLVM_DYLIB=OFF to link individual LLVM component libraries (core, irreader, support).

---

Build Script (build.sh)

The build.sh wrapper auto-detects LLVM/Clang:

macOS: uses brew --prefix llvm to find Homebrew LLVM.

Linux: uses llvm-config to locate LLVM CMake configs.

Options

./build.sh --type Release          # Build type
./build.sh --generator Ninja       # CMake generator
./build.sh --jobs 8                # Parallel jobs
./build.sh --build-dir out/build   # Custom output dir
./build.sh --clean                 # Clean before build
./build.sh --configure-only        # Only run CMake configure
./build.sh --llvm-dir /path/...    # Override LLVM path
./build.sh --clang-dir /path/...   # Override Clang path

Environment Variables

Variable	Description
LLVM_DIR	Path to LLVM CMake config directory
Clang_DIR	Path to Clang CMake config directory
DEBUG_ASAN	Set to ON to enable AddressSanitizer

---

Consuming as a Library

Other CMake projects can consume the analyzer via FetchContent:

include(FetchContent)
FetchContent_Declare(
    stack-analyzer
    GIT_REPOSITORY https://github.com/CoreTrace/coretrace-stack-analyzer.git
    GIT_TAG main
)
FetchContent_MakeAvailable(stack-analyzer)

target_link_libraries(my_tool PRIVATE coretrace::stack_usage_analyzer_lib)

See extern-project/ for a complete example.

---

Formatting

Run Formatter

./scripts/format.sh
# or
cmake --build build --target format

Check Formatting

./scripts/format-check.sh
# or
cmake --build build --target format-check

Target version: clang-format 20 (used in CI).

---

AddressSanitizer

Enable ASAN for debugging:

./build.sh --type Debug
# Then rebuild with ASAN:
cmake -S . -B build -DENABLE_DEBUG_ASAN=ON ...
cmake --build build

Or via environment:

DEBUG_ASAN=ON ./build.sh --type Debug

ASAN flags are applied to both the library and CLI binary.