Filtering and Configuration

Filtering and Configuration

The analyzer provides flexible filtering to focus analysis on specific files, directories, or functions.

---

File Filters

--only-file=<path>

Only report diagnostics from functions defined in this source file.

./build/stack_usage_analyzer --compdb=build --only-file=src/main.cpp

Matching is flexible:

• Absolute path match
• Basename match (just the filename)
• Suffix match (partial path)

--only-dir=<path>

Only report diagnostics from functions defined under this directory.

./build/stack_usage_analyzer --compdb=build --only-dir=src/core/

--exclude-dir=<dir0,dir1>

Exclude input files under these directories. Applied before analysis, so excluded files are not compiled at all. Comma-separated.

./build/stack_usage_analyzer --compdb=build --exclude-dir=_deps,third_party,vendor

---

Function Filters

--only-function=<name> / --only-func=<name>

Only report functions matching this name. Comma-separated for multiple.

./build/stack_usage_analyzer main.cpp --only-func=main,processData

Matching supports:

• Exact symbol name
• Demangled name (with or without parameters)
• Itanium ABI base name extraction
• Mangled filter values

--STL

Include STL, system library, and third-party functions in analysis output. By default, these are excluded to keep results focused on project code.

---

Compile Database Filters

Auto-Discovery

When --compile-commands is provided and no explicit input files are given:

• All supported entries (.c, .cc, .cpp, .cxx, .ll) are analyzed
• Unsupported entries (e.g., .m for Objective-C) are skipped
• _deps directories are excluded by default

--include-compdb-deps

Override the default _deps exclusion:

./build/stack_usage_analyzer --compdb=build --include-compdb-deps

--compdb-fast

Strips heavy build flags from compile database entries for faster analysis:

• Optimization flags (-O2, -O3)
• Sanitizer flags (-fsanitize=...)
• Profiling flags
• Platform-specific flags

Include paths and macros are preserved.

---

Diagnostic Filters

--warnings-only

Only emit warnings and errors. Hides info-level diagnostics (e.g., MultipleStoresToStackBuffer, ConstParameterNotModified). In human output, functions with no remaining warning/error diagnostics are omitted from the listing.

--quiet

Suppress all per-function diagnostics. Only stack sizes are shown in human output.

---

Debugging Filters

--dump-filter

Print filter decisions to stderr. Shows why each function/file was included or excluded:

./build/stack_usage_analyzer --compdb=build --only-dir=src/ --dump-filter

---

Configuration File (--config)

Rather than repeating flags on every invocation, put them in a key=value file. The repository ships .ctrace-analyzer.cfg as the conventional name.

./build/stack_usage_analyzer --config=.ctrace-analyzer.cfg
./build/stack_usage_analyzer --config=.ctrace-analyzer.cfg --print-effective-config

Priority: CLI flags > config file > built-in defaults.

The keys are the long option names without the leading --:

# Models
resource-model=models/resource-lifetime/generic.txt
escape-model=models/stack-escape/generic.txt
buffer-model=models/buffer-overflow/generic.txt

# Inputs and analysis profile
# compile-commands=build/compile_commands.json
analysis-profile=full
jobs=auto
compile-ir-cache-dir=.cache/compile-ir
compile-ir-format=bc

# Output behavior
warnings-only=false
demangle=true
timing=false

# Inter-TU analysis
resource-cross-tu=true
uninitialized-cross-tu=true
resource-summary-cache-dir=.cache/resource-lifetime
resource-summary-cache-memory-only=false

--print-effective-config writes the resolved configuration to stderr, which is the way to see what the file, the flags and the defaults actually produced — particularly when a profile was auto-selected.

---

Configuration Defaults

Setting	Default
Analysis mode	ir
Analysis profile	full (auto: fast for multi-file compdb)
Stack limit	8 MiB (8388608 bytes)
Assumed external frame	0 (unresolved calls make max stack unknown)
Output format	human
SMT refinement	off
SMT backend	interval
SMT mode	single
Resource cross-TU	enabled
Uninitialized cross-TU	enabled
Summary cache dir	.cache/resource-lifetime
Compile IR format	bc
Jobs	1
STL inclusion	off
Include compdb _deps	off

---

Stack Limit

Override the default 8 MiB stack limit:

--stack-limit=8192         # 8192 bytes
--stack-limit=8KiB         # 8 * 1024 bytes
--stack-limit=1MiB         # 1 * 1024 * 1024 bytes
--stack-limit=2GiB         # 2 * 1024^3 bytes

This affects the StackFrameTooLarge error threshold.