Getting Started

Getting Started

Prerequisites

• LLVM/Clang 19+ (20 recommended)
• CMake 3.16+
• C++20 compiler (GCC 12+ or Clang 15+)
• Ninja (recommended) or Make

macOS (Homebrew)

brew install llvm cmake ninja

Ubuntu/Debian

wget -qO - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
sudo apt-add-repository "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-20 main"
sudo apt-get update
sudo apt-get install -y cmake ninja-build \
  llvm-20 llvm-20-dev clang-20 libclang-20-dev

---

Building from Source

git clone https://github.com/CoreTrace/coretrace-stack-analyzer.git
cd coretrace-stack-analyzer
./build.sh --type Release

The build script auto-detects LLVM/Clang via Homebrew (macOS) or llvm-config (Linux). If detection fails, set the paths manually:

LLVM_DIR=/usr/lib/llvm-20/lib/cmake/llvm \
Clang_DIR=/usr/lib/llvm-20/lib/cmake/clang \
./build.sh --type Release

Build Options

Option	Default	Description
--type <type>	Release	Build type: Release, Debug, RelWithDebInfo
--generator <gen>	auto	Ninja or Unix Makefiles
--jobs <n>	auto	Parallel compilation jobs
--build-dir <dir>	build	Output directory
--llvm-dir <path>	auto	Path to LLVM CMake config
--clang-dir <path>	auto	Path to Clang CMake config
--clean	-	Clean build directory before building
--configure-only	-	Run CMake configure without building

The output binary is at ./build/stack_usage_analyzer.

---

Your First Scan

Analyzing a Single File

Create a test file example.c:

int main(void)
{
    char buf[10];
    buf[15] = 'x';  // out-of-bounds write
    return 0;
}

Run the analyzer:

./build/stack_usage_analyzer example.c

Expected output:

Mode: ABI

Function: main
  local stack: 32 bytes
  max stack (including callees): 32 bytes
  at line 4, column 14
  [ !!Warn ] potential stack buffer overflow on variable 'buf' (size 10)
  ... constant index 15 is out of bounds (0..9)
  ... (this is a write access)

Diagnostics summary: info=0, warning=1, error=0

Analyzing with Include Paths

./build/stack_usage_analyzer src/main.cpp -I./include -I/opt/homebrew/opt/llvm@20/include

Analyzing a Full Project

Generate compile_commands.json from your CMake project:

cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

Then analyze all files:

./build/stack_usage_analyzer --compile-commands=build/compile_commands.json

For faster CI scans, use the fast profile:

./build/stack_usage_analyzer --compile-commands=build/compile_commands.json --analysis-profile=fast

---

Understanding the Output

Severity Levels

Level	Prefix	Meaning
Error	[!!Error]	Definite issue (e.g., stack overflow exceeding limit)
Warning	[!!Warn]	Potential issue requiring review
Info	[!Info]	Informational finding (e.g., multiple stores to buffer)

Output Formats

• Human-readable (default): per-function stack sizes + diagnostics
• JSON (--format=json): structured data for CI pipelines
• SARIF (--format=sarif): GitHub Code Scanning compatible

See Output Formats for details.

---

Docker Quick Start

docker build -t coretrace-stack-analyzer .
docker run --rm -v "$PWD:/workspace" coretrace-stack-analyzer

The Docker image auto-detects compile_commands.json and uses sensible defaults. See CI/CD Integration for more.

---

Next Steps

• CLI Reference -- full list of options
• Analysis Categories -- what the tool detects
• CI/CD Integration -- automate in your pipeline