Debian Codegraph @

gcc/doc/libgdiagnostics/index.rst

raw
1 .. Copyright (C) 2024-2025 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <[email protected]>
3
4 This is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see
16 <https://www.gnu.org/licenses/>.
17
18 libgdiagnostics
19 ===============
20
21 This document describes `libgdiagnostics <https://gcc.gnu.org/wiki/libgdiagnostics>`_,
22 an API for programs to use to emit diagnostics (such as for "lint"-style checker
23 tools), supporting:
24
25 * text output similar to GCC's errors and warnings::
26
27 test-typo.c:19:13: error: unknown field 'colour'
28 19 | return p->colour;
29 | ^~~~~~
30
31 quoting pertinent source code (with a cache), and underlining
32 :doc:`points and ranges in the files being tested <tutorial/02-physical-locations>`,
33 possibly with labels::
34
35 test-labelled-ranges.c:9:6: error: mismatching types: 'int' and 'const char *'
36 19 | 42 + "foo"
37 | ~~ ^ ~~~~~
38 | | |
39 | int const char *
40
41 * emitting :doc:`fix-it hints <tutorial/06-fix-it-hints>`::
42
43 test-fix-it-hint.c:19:13: error: unknown field 'colour'; did you mean 'color'
44 19 | return p->colour;
45 | ^~~~~~
46 | color
47
48 and generating patches from them::
49
50 @@ -16,7 +16,7 @@
51 struct rgb
52 get_color (struct object *p)
53 {
54 - return p->colour;
55 + return p->color;
56 }
57
58 * capturing :doc:`execution paths<tutorial/07-execution-paths>` through code::
59
60 In function 'make_a_list_of_random_ints_badly':
61 test-warning-with-path.c:30:5: warning: passing NULL as argument 1 to 'PyList_Append' which requires a non-NULL parameter"
62 30 | PyList_Append(list, item);
63 | ^~~~~~~~~~~~~~~~~~~~~~~~~
64 make_a_list_of_random_ints_badly': events 1-3
65 26 | list = PyList_New(0);
66 | ^~~~~~~~~~~~~
67 | |
68 | (1) when 'PyList_New' fails, returning NULL
69 27 |
70 28 | for (i = 0; i < count; i++) {
71 | ~~~~~~~~~
72 | |
73 | (2) when 'i < count'
74 29 | item = PyLong_FromLong(random());
75 30 | PyList_Append(list, item);
76 | ~~~~~~~~~~~~~~~~~~~~~~~~~
77 | |
78 | (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
79
80 * support for emitting machine-readable representations of the above
81 using the :doc:`SARIF file format <topics/sarif>`
82
83 There are actually two APIs for the library:
84
85 * a pure C API: ``libgdiagnostics.h``
86
87 * a C++ wrapper API: ``libgdiagnostics+.h``. This is a header-only
88 collection of wrapper classes around the C API to give a less
89 verbose API.
90
91 This documentation covers the C API.
92
93 Contents
94 ********
95
96 .. toctree::
97 :maxdepth: 2
98
99 tutorial/index.rst
100 topics/index.rst
101
102 libgdiagnostics is free software: you can redistribute it and/or modify it
103 under the terms of the GNU General Public License as published by
104 the Free Software Foundation, either version 3 of the License, or
105 (at your option) any later version.
106
107
108 Indices and tables
109 ******************
110
111 * :ref:`genindex`
112 * :ref:`modindex`
113 * :ref:`search`