Clang

Clang

Purpose

Guide agents through Clang-specific features: superior diagnostics, sanitizer integration, optimization remarks, static analysis, and LLVM tooling. Covers divergences from GCC and Apple/FreeBSD specifics.

Triggers

• "I want better compiler diagnostics/errors"
• "How do I use clang-tidy / clang-format?"
• "How do I see what the compiler optimised or didn't?"
• "I'm on macOS / FreeBSD using clang"
• "clang-cl for MSVC-compatible builds" — see skills/compilers/msvc-cl
• Sanitizer queries — see skills/runtimes/sanitizers

Workflow

1. Build mode flags (identical to GCC)

Clang accepts most GCC flags. Key differences:

2. Clang-specific diagnostic flags

# Show fix-it hints inline
clang -Wall -Wextra --show-fixits src.c

# Limit error count
clang -ferror-limit=5 src.c

# Verbose template errors (disable elision)
clang -fno-elide-type src.cpp

# Show tree diff for template mismatch
clang -fdiagnostics-show-template-tree src.cpp

Clang's diagnostics include exact range highlighting and fix-it suggestions that GCC lacks.

3. Optimization remarks

Optimization remarks let you see what Clang did or refused to do:

# Inliner decisions
clang -O2 -Rpass=inline src.c

# Missed vectorisation
clang -O2 -Rpass-missed=loop-vectorize src.c

# Why a loop was not vectorized
clang -O2 -Rpass-analysis=loop-vectorize src.c

# Save all remarks to YAML for post-processing
clang -O2 -fsave-optimization-record src.c
# Produces src.opt.yaml

Interpret remarks:

• remark: foo inlined into bar — inlining happened; good for hot paths
• remark: loop not vectorized: loop control flow is not understood — restructure the loop
• remark: not vectorized: cannot prove it is safe to reorder... — add __restrict__ or #pragma clang loop vectorize(assume_safety)

4. Static analysis

# Built-in analyser (CSA)
clang --analyze -Xanalyzer -analyzer-output=text src.c

# clang-tidy (separate tool, richer checks)
clang-tidy src.c -- -std=c++17 -I/usr/include

# Enable specific check families
clang-tidy -checks='clang-analyzer-*,modernize-*,bugprone-*' src.cpp --

# Apply fixits automatically
clang-tidy -fix src.cpp --

Common clang-tidy check families:

• bugprone-*: real bugs (use-after-move, dangling, etc.)
• clang-analyzer-*: CSA checks (memory, null deref)
• modernize-*: C++11/14/17 modernisation
• performance-*: unnecessary copies, move candidates
• readability-*: naming, complexity

5. LTO with lld

# Full LTO
clang -O2 -flto -fuse-ld=lld src.c -o prog

# Thin LTO (faster link, nearly same quality)
clang -O2 -flto=thin -fuse-ld=lld src.c -o prog

# Check lld is available
clang -fuse-ld=lld -Wl,--version 2>&1 | head -1

For large projects, ThinLTO is preferred: link times 5-10x faster than full LTO with comparable code quality.

6. PGO (LLVM instrumentation)

# Step 1: instrument
clang -O2 -fprofile-instr-generate prog.c -o prog_inst

# Step 2: run with representative input
./prog_inst < workload.input
# Generates default.profraw

# Step 3: merge profiles
llvm-profdata merge -output=prog.profdata default.profraw

# Step 4: use profile
clang -O2 -fprofile-instr-use=prog.profdata prog.c -o prog

AutoFDO (sampling-based, less intrusive): collect with perf, convert with create_llvm_prof, use with -fprofile-sample-use. See skills/profilers/linux-perf.

7. GCC compatibility

Clang is intentionally GCC-compatible for driver flags. Key differences:

• Clang does not support all GCC-specific attributes; check with __has_attribute(foo)
• -Weverything enables all Clang warnings (no GCC equivalent); too noisy for production, useful for one-off audits
• Some GCC intrinsics need #include <x86intrin.h> on Clang too
• __int128 is supported; __float128 requires -lquadmath on some targets

8. macOS specifics

On macOS, clang is the system compiler (Apple LLVM). Key points:

• ld64 is the default linker; lld requires explicit -fuse-ld=lld and Homebrew LLVM
• Use -mmacosx-version-min=X.Y to set deployment target
• Sanitizers on macOS use DYLD_INSERT_LIBRARIES; do not strip the binary
• xcrun clang resolves to the Xcode toolchain clang

For flag reference, see references/flags.md. For clang-tidy config examples, see references/clang-tidy.md.

Related skills

• Use skills/compilers/gcc for GCC-equivalent flag mapping
• Use skills/runtimes/sanitizers for -fsanitize=* workflows
• Use skills/compilers/llvm for IR-level work (opt, llc, llvm-dis)
• Use skills/compilers/msvc-cl for clang-cl on Windows
• Use skills/binaries/linkers-lto for linker-level LTO details

clang-tidy Reference

Source: <https://clang.llvm.org/extra/clang-tidy/>

Configuration (.clang-tidy)

---
Checks: >
  clang-analyzer-*,
  bugprone-*,
  modernize-*,
  performance-*,
  readability-identifier-naming,
  -modernize-use-trailing-return-type,
  -readability-magic-numbers
WarningsAsErrors: 'bugprone-*'
HeaderFilterRegex: '.*'
FormatStyle: file
CheckOptions:
  - key: readability-identifier-naming.VariableCase
    value: camelCase

Common invocations

# Single file
clang-tidy src.cpp -- -std=c++17 -I./include

# All files using compile_commands.json
clang-tidy $(find src -name '*.cpp') -p build/

# Apply fixits (creates in-place changes)
clang-tidy -fix src.cpp -- -std=c++17

# Parallel (requires run-clang-tidy script)
run-clang-tidy -j4 -p build/ 2>&1 | tee tidy.log

# Generate compile_commands.json with CMake
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S . -B build
ln -sf build/compile_commands.json .

Key check families

Suppressing checks

// NOLINT: suppress all checks on this line
int x = getValue();  // NOLINT

// NOLINT(check-name): suppress specific check
int y = getValue();  // NOLINT(bugprone-narrowing-conversions)

// NOLINTNEXTLINE: suppress on next line
// NOLINTNEXTLINE(modernize-use-auto)
MyType* ptr = new MyType();

In .clang-tidy, prefix a check with - to disable:

Checks: 'modernize-*,-modernize-use-trailing-return-type'

Clang Flag Reference

Source: <https://clang.llvm.org/docs/UsersManual.html> Source: <https://clang.llvm.org/docs/ClangCommandLineReference.html>

Table of Contents

1. Optimisation 2. Diagnostics 3. Sanitizers 4. LTO / PGO 5. Code generation 6. Target-specific

---

Optimisation

---

Diagnostics

---

Sanitizers

See skills/runtimes/sanitizers for full decision tree and report interpretation.

---

LTO / PGO

---

Code generation

---

Target-specific

x86-64

-march=x86-64-v2    # SSE4.2, POPCNT (Nehalem+)
-march=x86-64-v3    # AVX2 (Haswell+)
-march=x86-64-v4    # AVX-512
-march=native       # Detect host CPU

AArch64 / ARM

-target aarch64-linux-gnu
-mcpu=cortex-a72
-mfloat-abi=hard

WebAssembly

--target=wasm32-unknown-unknown
-nostdlib