https://gcc.gnu.org/g:a4e4f2d22589a8565bebf906930bf6a536a81167
commit r15-4230-ga4e4f2d22589a8565bebf906930bf6a536a81167
Author: David Malcolm <dmalc...@redhat.com>
Date: Wed Oct 9 21:26:09 2024 -0400
diagnostics: mark the JSON output format as deprecated
The bulk of the documentation for -fdiagnostics-format= is taken up
by a description of the "json" format added in r9-4156-g478dd60ddcf177.
I don't plan to add any extra features to the "json" format; all my
future work on machine-readable GCC diagnostics is likely to be on the
SARIF output format (https://gcc.gnu.org/wiki/SARIF).
Hence users seeking machine-readable output from GCC should use SARIF.
This patch removes the long documentation of the format and describes it
as deprecated.
gcc/ChangeLog:
* doc/invoke.texi (fdiagnostics-format): Describe "json" et al as
deprecated, and remove the long description of the output format.
Signed-off-by: David Malcolm <dmalc...@redhat.com>
Diff:
---
gcc/doc/invoke.texi | 266 +---------------------------------------------------
1 file changed, 2 insertions(+), 264 deletions(-)
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 12477e6f9df3..575dffd2a2f5 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -5907,276 +5907,14 @@ The @samp{sarif-stderr} and @samp{sarif-file} formats
both emit
diagnostics in SARIF Version 2.1.0 format, either to stderr, or to a file
named @file{@var{source}.sarif}, respectively.
+The various @samp{json}, @samp{json-stderr}, and @samp{json-file} values
+are deprecated and refer to a legacy JSON-based output format.
The @samp{json} format is a synonym for @samp{json-stderr}.
The @samp{json-stderr} and @samp{json-file} formats are identical, apart from
where the JSON is emitted to. With @samp{json-stderr}, the JSON is emitted
to stderr, whereas with @samp{json-file} it is written to
@file{@var{source}.gcc.json}.
-The emitted JSON consists of a top-level JSON array containing JSON objects
-representing the diagnostics.
-
-Diagnostics can have child diagnostics. For example, this error and note:
-
-@smallexample
-misleading-indentation.c:15:3: warning: this 'if' clause does not
- guard... [-Wmisleading-indentation]
- 15 | if (flag)
- | ^~
-misleading-indentation.c:17:5: note: ...this statement, but the latter
- is misleadingly indented as if it were guarded by the 'if'
- 17 | y = 2;
- | ^
-@end smallexample
-
-@noindent
-might be printed in JSON form (after formatting) like this:
-
-@smallexample
-[
- @{
- "kind": "warning",
- "locations": [
- @{
- "caret": @{
- "display-column": 3,
- "byte-column": 3,
- "column": 3,
- "file": "misleading-indentation.c",
- "line": 15
- @},
- "finish": @{
- "display-column": 4,
- "byte-column": 4,
- "column": 4,
- "file": "misleading-indentation.c",
- "line": 15
- @}
- @}
- ],
- "message": "this \u2018if\u2019 clause does not guard...",
- "option": "-Wmisleading-indentation",
- "option_url":
"https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wmisleading-indentation";,
- "children": [
- @{
- "kind": "note",
- "locations": [
- @{
- "caret": @{
- "display-column": 5,
- "byte-column": 5,
- "column": 5,
- "file": "misleading-indentation.c",
- "line": 17
- @}
- @}
- ],
- "escape-source": false,
- "message": "...this statement, but the latter is @dots{}"
- @}
- ]
- "escape-source": false,
- "column-origin": 1,
- @}
-]
-@end smallexample
-
-@noindent
-where the @code{note} is a child of the @code{warning}.
-
-A diagnostic has a @code{kind}. If this is @code{warning}, then there is
-an @code{option} key describing the command-line option controlling the
-warning.
-
-A diagnostic can contain zero or more locations. Each location has an
-optional @code{label} string and up to three positions within it: a
-@code{caret} position and optional @code{start} and @code{finish} positions.
-A position is described by a @code{file} name, a @code{line} number, and
-three numbers indicating a column position:
-@itemize @bullet
-
-@item
-@code{display-column} counts display columns, accounting for tabs and
-multibyte characters.
-
-@item
-@code{byte-column} counts raw bytes.
-
-@item
-@code{column} is equal to one of
-the previous two, as dictated by the @option{-fdiagnostics-column-unit}
-option.
-
-@end itemize
-All three columns are relative to the origin specified by
-@option{-fdiagnostics-column-origin}, which is typically equal to 1 but may
-be set, for instance, to 0 for compatibility with other utilities that
-number columns from 0. The column origin is recorded in the JSON output in
-the @code{column-origin} tag. In the remaining examples below, the extra
-column number outputs have been omitted for brevity.
-
-For example, this error:
-
-@smallexample
-bad-binary-ops.c:64:23: error: invalid operands to binary + (have 'S' @{aka
- 'struct s'@} and 'T' @{aka 'struct t'@})
- 64 | return callee_4a () + callee_4b ();
- | ~~~~~~~~~~~~ ^ ~~~~~~~~~~~~
- | | |
- | | T @{aka struct t@}
- | S @{aka struct s@}
-@end smallexample
-
-@noindent
-has three locations. Its primary location is at the ``+'' token at column
-23. It has two secondary locations, describing the left and right-hand sides
-of the expression, which have labels. It might be printed in JSON form as:
-
-@smallexample
- @{
- "children": [],
- "kind": "error",
- "locations": [
- @{
- "caret": @{
- "column": 23, "file": "bad-binary-ops.c", "line": 64
- @}
- @},
- @{
- "caret": @{
- "column": 10, "file": "bad-binary-ops.c", "line": 64
- @},
- "finish": @{
- "column": 21, "file": "bad-binary-ops.c", "line": 64
- @},
- "label": "S @{aka struct s@}"
- @},
- @{
- "caret": @{
- "column": 25, "file": "bad-binary-ops.c", "line": 64
- @},
- "finish": @{
- "column": 36, "file": "bad-binary-ops.c", "line": 64
- @},
- "label": "T @{aka struct t@}"
- @}
- ],
- "escape-source": false,
- "message": "invalid operands to binary + @dots{}"
- @}
-@end smallexample
-
-If a diagnostic contains fix-it hints, it has a @code{fixits} array,
-consisting of half-open intervals, similar to the output of
-@option{-fdiagnostics-parseable-fixits}. For example, this diagnostic
-with a replacement fix-it hint:
-
-@smallexample
-demo.c:8:15: error: 'struct s' has no member named 'colour'; did you
- mean 'color'?
- 8 | return ptr->colour;
- | ^~~~~~
- | color
-@end smallexample
-
-@noindent
-might be printed in JSON form as:
-
-@smallexample
- @{
- "children": [],
- "fixits": [
- @{
- "next": @{
- "column": 21,
- "file": "demo.c",
- "line": 8
- @},
- "start": @{
- "column": 15,
- "file": "demo.c",
- "line": 8
- @},
- "string": "color"
- @}
- ],
- "kind": "error",
- "locations": [
- @{
- "caret": @{
- "column": 15,
- "file": "demo.c",
- "line": 8
- @},
- "finish": @{
- "column": 20,
- "file": "demo.c",
- "line": 8
- @}
- @}
- ],
- "escape-source": false,
- "message": "\u2018struct s\u2019 has no member named @dots{}"
- @}
-@end smallexample
-
-@noindent
-where the fix-it hint suggests replacing the text from @code{start} up
-to but not including @code{next} with @code{string}'s value. Deletions
-are expressed via an empty value for @code{string}, insertions by
-having @code{start} equal @code{next}.
-
-If the diagnostic has a path of control-flow events associated with it,
-it has a @code{path} array of objects representing the events. Each
-event object has a @code{description} string, a @code{location} object,
-along with a @code{function} string and a @code{depth} number for
-representing interprocedural paths. The @code{function} represents the
-current function at that event, and the @code{depth} represents the
-stack depth relative to some baseline: the higher, the more frames are
-within the stack.
-
-For example, the intraprocedural example shown for
-@option{-fdiagnostics-path-format=} might have this JSON for its path:
-
-@smallexample
- "path": [
- @{
- "depth": 0,
- "description": "when 'PyList_New' fails, returning NULL",
- "function": "test",
- "location": @{
- "column": 10,
- "file": "test.c",
- "line": 25
- @}
- @},
- @{
- "depth": 0,
- "description": "when 'i < count'",
- "function": "test",
- "location": @{
- "column": 3,
- "file": "test.c",
- "line": 27
- @}
- @},
- @{
- "depth": 0,
- "description": "when calling 'PyList_Append', passing NULL from
(1) as argument 1",
- "function": "test",
- "location": @{
- "column": 5,
- "file": "test.c",
- "line": 29
- @}
- @}
- ]
-@end smallexample
-
-Diagnostics have a boolean attribute @code{escape-source}, hinting whether
-non-ASCII bytes should be escaped when printing the pertinent lines of
-source code (@code{true} for diagnostics involving source encoding issues).
-
@opindex fno-diagnostics-json-formatting
@opindex fdiagnostics-json-formatting
@item -fno-diagnostics-json-formatting
