https://github.com/ebendler updated https://github.com/llvm/llvm-project/pull/209519
>From 11cf80eb3a5813a9a765f7aac662138f392ac8ca Mon Sep 17 00:00:00 2001 From: Ehren Bendler <[email protected]> Date: Tue, 14 Jul 2026 11:40:56 -0400 Subject: [PATCH] docs(clang): add some missing flags The current user-manual is missing options that are useful for machine-readable output, such as fdiagnostics-format=sarif and fdiagnostics-absolute-paths. --- clang/docs/UsersManual.md | 50 ++++++++++++++++++- .../analyzer/user-docs/CommandLineUsage.rst | 19 ++++++- 2 files changed, 67 insertions(+), 2 deletions(-) diff --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md index 756f2784dc076..fb38ebdb76806 100644 --- a/clang/docs/UsersManual.md +++ b/clang/docs/UsersManual.md @@ -327,7 +327,7 @@ output format of the diagnostics that it generates. ``` ```{eval-rst} -.. option:: -fdiagnostics-format=clang/msvc/vi +.. option:: -fdiagnostics-format=clang/msvc/vi/sarif Changes diagnostic output format to better match IDEs and command line tools. @@ -349,6 +349,28 @@ output format of the diagnostics that it generates. :: t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int' + + **sarif** + Emit diagnostics as a `SARIF <https://sarifweb.azurewebsites.net/>`_ JSON document. + This is useful when diagnostics are consumed by tools, including AI agents. + SARIF diagnostics are written to standard error. + ``-fno-caret-diagnostics`` suppresses the final diagnostic summary so that standard error contains a standalone JSON document. + Suppress the existing SARIF-stability warning too when capturing a standalone JSON document: + + :: + + clang -fdiagnostics-format=sarif -Wno-sarif-format-unstable -fno-caret-diagnostics t.c 2> diagnostics.sarif + + The SARIF diagnostic format is currently unstable. +``` + +```{eval-rst} +.. option:: -fdiagnostics-absolute-paths + + Print absolute paths in diagnostics. + + This option is useful when a diagnostic consumer does not share Clang's current working directory. + It resolves symbolic links before printing paths. ``` (opt_fdiagnostics-show-option)= @@ -926,6 +948,32 @@ information can be included in the remarks (see These are options that report execution time and consumed memory of different compilations steps. +```{eval-rst} +.. option:: -ftime-report-json + + Print compiler pass timing statistics as a JSON object to standard error. + Use this when no compiler diagnostics will also be emitted to standard error, since other diagnostic output would interleave with the JSON: + + .. code-block:: console + + $ clang -O2 -c foo.c -ftime-report-json -o foo.o 2> timing.json +``` + +```{eval-rst} +.. option:: -ftime-trace[=<path>] + + Write a Chrome tracing-format JSON time trace for the compilation. + Without a path, Clang derives the JSON filename from the compilation output. + A path names the JSON file or a directory that will contain it. + + :option:`-ftime-trace-granularity` sets the minimum recorded duration in microseconds (500 by default). + :option:`-ftime-trace-verbose` records additional event details, including source filenames, and can increase the trace size by two to three times. + + .. code-block:: console + + $ clang -c foo.c -ftime-trace=compile-trace.json -o foo.o +``` + ```{eval-rst} .. option:: -fproc-stat-report= diff --git a/clang/docs/analyzer/user-docs/CommandLineUsage.rst b/clang/docs/analyzer/user-docs/CommandLineUsage.rst index 089a8ce68ce0a..6bacb0d4eb6eb 100644 --- a/clang/docs/analyzer/user-docs/CommandLineUsage.rst +++ b/clang/docs/analyzer/user-docs/CommandLineUsage.rst @@ -7,6 +7,24 @@ Both provide a way of driving the analyzer, detecting compilation flags, and gen CodeChecker is more actively maintained, provides heuristics for working with multiple versions of popular compilers and it also comes with a web-based GUI for viewing, filtering, categorizing and suppressing the results. Therefore CodeChecker is recommended in case you need any of the above features or just more customizability in general. +Machine-readable output +----------------------- + +For a direct analysis of a source file, the ``clang`` driver can write a SARIF report that is suitable for automation and AI agents:: + + $ clang --analyze --analyzer-output sarif -o report.sarif source.c + +``--analyzer-output`` selects the report format. +The available formats are ``html``, ``plist``, ``plist-multi-file``, ``plist-html``, ``sarif``, ``sarif-html``, and ``text``. +``sarif`` writes a SARIF JSON report to the path specified by ``-o``; ``sarif-html`` also creates HTML files for interactive inspection. +The default format is ``plist``. + +This direct form analyzes a translation unit. +For project-wide analysis, use a tool such as CodeChecker or scan-build to drive the individual compiler invocations. +``scan-build`` can emit a SARIF report for each analyzed translation unit with its ``-sarif`` option:: + + $ scan-build -sarif -o reports make + Comparison of CodeChecker and scan-build ---------------------------------------- @@ -239,4 +257,3 @@ Detailed Usage ~~~~~~~~~~~~~~ For extended documentation please refer to the `official site of CodeChecker <https://github.com/Ericsson/codechecker/blob/master/docs/usage.md>`_! - _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
