clang

Clang

Contract

Inputs

• Compiler version: required, from clang --version. The current stable line is LLVM/Clang 23.1.0; Apple's clang reports an Apple version and lags upstream.
• The task: required. One of diagnostics, remarks, static analysis, LTO, PGO, GCC migration, or macOS specifics.
• Source file or compile command that reproduces the question: required for diagnostics and remarks.
• Linker available (ld.lld, ld64, GNU ld): required for LTO questions.

Procedure

1. Confirm the compiler and driver: run clang --version. On macOS, xcrun clang resolves to the Xcode toolchain; Homebrew LLVM installs a separate upstream clang. Done when: the vendor and version are recorded.
2. Map GCC flags to Clang where they differ. Clang accepts most GCC driver flags. Differences that matter: -Oz shrinks harder than -Os; -flto=thin selects ThinLTO; -fprofile-instr-generate and -fprofile-instr-use select LLVM's own PGO format while -fprofile-generate and -fprofile-use keep the GCC-compatible format; -Weverything enables every warning and suits a one-off audit, not a production build; --analyze runs the Clang Static Analyzer where GCC has -fanalyzer. Attributes differ: gate GCC-only attributes with __has_attribute(name). Done when: each GCC flag in the request has its Clang spelling or a note that it is unchanged.
3. Tune diagnostics with confirmed flags: -ferror-limit=N stops after N errors (default 20); -fno-elide-type prints full template types; -fdiagnostics-show-template-tree shows a tree diff for template mismatches; -ftemplate-backtrace-limit=N bounds the instantiation backtrace; -fdiagnostics-parseable-fixits emits fix-its in a machine-readable form; -fdiagnostics-format=vi or msvc changes the location format. Fix-it hints already print inline by default. Done when: the diagnostic flags are stated with their effect.
4. Read optimization remarks. Emit them with -Rpass=<regex> (transform happened), -Rpass-missed=<regex> (transform skipped), -Rpass-analysis=<regex> (why), for example clang -O2 -Rpass-analysis=loop-vectorize src.c. Save all remarks with -fsave-optimization-record, which writes <object>.opt.yaml next to the object file. Interpret: an inline remark on a hot path is good; loop not vectorized: loop control flow is not understood calls for restructuring the loop; a reordering-safety remark calls for __restrict__ or #pragma clang loop vectorize(assume_safety) after the user proves no aliasing. Done when: each remark in the request has a reading and a next action.
5. Run static analysis. Built-in analyzer: clang --analyze -Xanalyzer -analyzer-output=text src.c. clang-tidy: clang-tidy src.cpp -- -std=c++20 -I<dir> for one file, -p build/ against compile_commands.json (generate it with cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON), run-clang-tidy -j<N> -p build/ for the tree, -checks='clang-analyzer-*,bugprone-*,modernize-*,performance-*' to select families, --fix to apply fix-its in place. Suppress one line with // NOLINT(check-name) or the following line with // NOLINTNEXTLINE(check-name). Done when: the analysis command and check families match the code class.
6. Configure LTO. Full: clang -O2 -flto -fuse-ld=lld. Thin: clang -O2 -flto=thin -fuse-ld=lld. Confirm the linker with clang -fuse-ld=lld -Wl,--version. ThinLTO links faster than full LTO on large programs; measure the code-quality difference on the project rather than assuming a ratio. -fwhole-program-vtables and -fvirtual-function-elimination need LTO. On macOS the default linker is ld64; -fuse-ld=lld needs an upstream LLVM install. Done when: the LTO mode, linker, and confirmation command are stated.
7. Configure PGO: clang -O2 -fprofile-instr-generate to instrument, run the workload (writes default.profraw; set LLVM_PROFILE_FILE="prog-%p.profraw" for parallel runs), llvm-profdata merge -output=prog.profdata *.profraw, then clang -O2 -fprofile-instr-use=prog.profdata. Sampling-based profiles use -fprofile-sample-use=<file>. The full flow, context-sensitive PGO, and BOLT: use pgo. Done when: the four PGO commands are listed.
8. Handle macOS specifics when asked: set the deployment target with -mmacosx-version-min=X.Y; sanitizer runtimes are injected at load, so do not strip a sanitized binary; xcrun clang selects the Xcode toolchain. Done when: the macOS points relevant to the request are stated.
9. Confirm every flag against the installed Clang with a scratch compile; drop any the driver rejects and say so. Done when: no unconfirmed flag remains.