CLI Reference

CLI Reference

Usage

stack_usage_analyzer <file.ll|.c|.cpp> [file2 ...] [options]

Input files can be LLVM IR (.ll), C (.c), or C++ (.cpp, .cc, .cxx).

---

Analysis Options

Option	Default	Description
--mode=ir|abi	ir	Analysis mode. ir = pure LLVM IR sizes. abi = includes ABI calling convention overhead.
--analysis-profile=fast|full	full	Precision/speed tradeoff. See Analysis Profiles.
--stack-limit=<value>	8MiB	Stack size overflow threshold. Accepts bytes or units (e.g., 8KiB, 1MiB, 2GiB).
--jobs=<N>	1	Parallel jobs for multi-file loading, analysis, and cross-TU summary build.
--timing	off	Print compilation/analysis timings to stderr.

---

Input Options

Option	Description
<file> [file2 ...]	Source or IR files to analyze.
--compile-commands=<path>	Path to compile_commands.json (file or directory).
--compdb=<path>	Alias for --compile-commands.
--compdb-fast	Strip heavy build flags (optimizations, sanitizers) for faster analysis.
--include-compdb-deps	Include _deps entries from compile database (skipped by default).
-I<dir> or -I <dir>	Add include directory for C/C++ inputs.
-D<name>[=value] or -D <name>[=value]	Define preprocessor macro.
--compile-arg=<arg>	Pass extra argument to the compiler (repeatable).

When --compile-commands is provided without explicit input files, the analyzer auto-discovers all supported entries from the database.

---

Output Options

Option	Default	Description
--format=human|json|sarif	human	Output format.
--quiet	off	Suppress per-function diagnostics entirely.
--warnings-only	off	Hide info-level diagnostics. In human output, list only functions that still have warnings/errors.
--base-dir=<path>	-	Strip this base directory from SARIF URIs for relative paths.
--dump-ir=<path>	-	Write generated LLVM IR to file (or directory for multiple inputs).

---

Filter Options

Option	Description
--only-file=<path>	Only report functions from this source file.
--only-dir=<path>	Only report functions under this directory.
--exclude-dir=<dir0,dir1>	Exclude input files under these directories (comma-separated).
--only-function=<name>	Only report functions matching this name (comma-separated).
--only-func=<name>	Alias for --only-function.
--STL	Include STL/system library functions (excluded by default).
--dump-filter	Print filter decisions to stderr for debugging.

See Filtering and Configuration for details.

---

Model Options

Option	Description
--resource-model=<path>	Load external acquire/release rules for resource lifetime analysis.
--escape-model=<path>	Load external noescape rules for stack pointer escape analysis.
--resource-cross-tu	Enable cross-TU resource summaries (default: on).
--no-resource-cross-tu	Disable cross-TU resource summaries.
--uninitialized-cross-tu	Enable cross-TU uninitialized summaries (default: on).
--no-uninitialized-cross-tu	Disable cross-TU uninitialized summaries.
--resource-summary-cache-dir=<path>	Cache directory for cross-TU resource summaries (default: .cache/resource-lifetime).
--resource-summary-cache-memory-only	Use in-memory cache only (no filesystem writes).

See External Models for the model file format.

---

Other Options

Option	Description
-h, --help	Show help message and exit.

---

Examples

# Basic analysis
./build/stack_usage_analyzer main.cpp -I./include

# JSON output for CI
./build/stack_usage_analyzer src/*.cpp --format=json --warnings-only

# Analyze using compile database with fast profile
./build/stack_usage_analyzer --compdb=build/compile_commands.json --analysis-profile=fast --jobs=4

# ABI mode with custom stack limit
./build/stack_usage_analyzer main.c --mode=abi --stack-limit=1MiB

# Resource lifetime analysis with external model
./build/stack_usage_analyzer a.c b.c \
  --resource-model=models/resource-lifetime/generic.txt \
  --resource-summary-cache-memory-only \
  --warnings-only

# Debug: dump generated IR
./build/stack_usage_analyzer main.cpp --dump-ir=./debug/main.ll

# Filter to specific files and functions
./build/stack_usage_analyzer --compdb=build --only-dir=src/ --only-func=main,processData