Debian Codegraph @

gcc/doc/libgdiagnostics/tutorial/02-physical-locations.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 .. default-domain:: c
19
20 Tutorial part 2: physical locations
21 ===================================
22
23 libgdiagnostics has two kinds of location:
24
25 * *physical locations* expressed in terms of a specific file, and line(s)
26 and perhaps column(s), such as ``some-file.c:3:1``, or a range of
27 columns, such as in::
28
29 test-typo.c:19:13: error: unknown field 'colour'
30 19 | return p->colour;
31 | ^~~~~~
32
33 or even a range spanning multiple lines of a file.
34
35 All of these are instances of :type:`diagnostic_physical_location`.
36
37 * *logical locations* which refers to semantic constructs
38 in the input, such as ``within function 'foo'``, or within
39 namespace ``foo``'s class ``bar``'s member function ``get_color``.
40
41 These are instances of :type:`diagnostic_logical_location`,
42
43 A :type:`diagnostic` can have zero or more physical locations,
44 and optionally have a logical location.
45
46 Let's extend the previous example to add a physical location to the
47 :type:`diagnostic`; we'll cover logical locations in the
48 :doc:`next section <03-logical-locations>`.
49
50
51 Source files
52 ************
53
54 Given these declarations::
55
56 static diagnostic_manager *diag_mgr;
57 static diagnostic_file *main_file;
58
59 we can create a :type:`diagnostic_file` describing an input file ``foo.c``
60 via :func:`diagnostic_manager_new_file`::
61
62 foo_c = diagnostic_manager_new_file (diag_mgr,
63 "foo.c",
64 "c" /* source_language */);
65
66 You can use :func:`diagnostic_manager_debug_dump_file` to print a
67 representation of a :type:`diagnostic_file` for debugging.
68 For example::
69
70 diagnostic_manager_debug_dump_file (diag_mgr, foo_c, stderr);
71
72 might lead to this output on ``stderr``::
73
74 file(name="foo.c", sarif_source_language="c")
75
76 Once we have a :type:`diagnostic_file` we can use it to create instances
77 of :type:`diagnostic_physical_location` within the :type:`diagnostic_manager`.
78 These are owned by the :type:`diagnostic_manager` and cleaned up
79 automatically when :func:`diagnostic_manager_release` is called.
80
81 Instances of :type:`diagnostic_physical_location` can refer to
82
83 * a source line as a whole, created via
84 :func:`diagnostic_manager_new_location_from_file_and_line`.
85
86 * a particular point within a source file (line/column), created via
87 :func:`diagnostic_manager_new_location_from_file_line_column`.
88
89 * a range of text within of source file, created via
90 :func:`diagnostic_manager_new_location_from_range`.
91
92
93 Diagnostics affecting a whole source line
94 *****************************************
95
96 If we want a diagnostic to refer to an entire source line,
97 we can use :func:`diagnostic_manager_new_location_from_file_and_line`.
98
99 For example, given this example input where the tool can't find the header::
100
101 #include <foo.h>
102
103 we could complain about it via libgdiagnostics via:
104
105 .. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-no-column.c
106 :language: c
107 :start-after: /* begin quoted source */
108 :end-before: /* end quoted source */
109
110 leading to output like this::
111
112 foo.c:17: error: can't find 'foo.h'"
113 17 | #include <foo.h>
114
115 where libgdiagnostics will attempt to load the source file and
116 quote the pertinent line.
117
118 If libgdiagnostics cannot open the file, it will merely print::
119
120 foo.c:17: error: can't find 'foo.h'
121
122 You can use :func:`diagnostic_manager_debug_dump_location` to dump a
123 :type:`diagnostic_physical_location`. For the above example::
124
125 diagnostic_manager_debug_dump_location (diag_mgr, loc, stderr);
126
127 might print::
128
129 foo.c:17
130
131 to stderr.
132
133
134 Columns and ranges
135 ******************
136
137 If we want to generate output like this::
138
139 foo.c:17:11: error: can't find 'foo'"
140 17 | #include <foo.h>
141 | ^~~~~
142
143 where the diagnostic is marked as relating to the above range of
144 characters in line 17, we need to express the range of characters
145 within the line of interest.
146
147 We can do this by creating a :type:`diagnostic_physical_location` for the
148 start of the range, another one for the end of the range, and then using
149 these two to create a :type:`diagnostic_physical_location` for the
150 range as a whole:
151
152 .. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-error.c
153 :language: c
154 :start-after: /* begin quoted source */
155 :end-before: /* end quoted source */
156
157 On compiling and running the program, we should get this output::
158
159 foo.c:17:11: error: can't find 'foo.h'
160 17 | #include <foo.h>
161 | ^~~~~
162
163 where libgdiagnostics will attempt to load the source file and
164 underling the pertinent part of the given line.
165
166 If libgdiagnostics cannot open the file, it will merely print::
167
168 foo.c:17:8: error: can't find 'foo.h'
169
170 A range can span multiple lines within the same file.
171
172 As before, you can use :func:`diagnostic_manager_debug_dump_location` to
173 dump the locations. For the above example::
174
175 diagnostic_manager_debug_dump_location (diag_mgr, loc_start, stderr);
176
177 and::
178
179 diagnostic_manager_debug_dump_location (diag_mgr, loc_range, stderr);
180
181 might print::
182
183 foo.c:17:11
184
185 to stderr, whereas::
186
187 diagnostic_manager_debug_dump_location (diag_mgr, loc_end, stderr);
188
189 might print::
190
191 foo.c:17:15
192
193
194 Multiple locations
195 ******************
196
197 As well as the primary physical location seen above, a :type:`diagnostic`
198 can have additional physical locations. You can add these secondary
199 locations via :func:`diagnostic_add_location`.
200
201 For example, for this valid but suspicious-looking C code::
202
203 const char *strs[3] = {"foo",
204 "bar"
205 "baz"};
206
207 the following :type:`diagnostic` has its primary location where the missing
208 comma should be, and secondary locations for each of the string literals
209 ``"foo"``, ``"bar"``, and ``"baz"``, added via :func:`diagnostic_add_location`:
210
211 .. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-multiple-lines.c
212 :language: c
213 :start-after: /* begin quoted source */
214 :end-before: /* end quoted source */
215
216 where the text output might be::
217
218 test-multiple-lines.c:23:29: warning: missing comma
219 22 | const char *strs[3] = {"foo",
220 | ~~~~~
221 23 | "bar"
222 | ~~~~~^
223 24 | "baz"};
224 | ~~~~~
225
226
227 Labelling locations
228 *******************
229
230 You can give the locations labels using
231 :func:`diagnostic_set_location_with_label` and
232 :func:`diagnostic_add_location_with_label`.
233
234 Consider emitting a "type mismatch" diagnostic for::
235
236 42 + "foo"
237
238 where the primary location is on the ``+``, with secondary locations on the``42``
239 and the ``"foo"``:
240
241 .. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-labelled-ranges.c
242 :language: c
243 :start-after: /* begin quoted source */
244 :end-before: /* end quoted source */
245
246 giving this text output::
247
248 test-labelled-ranges.c:9:6: error: mismatching types: 'int' and 'const char *'
249 19 | 42 + "foo"
250 | ~~ ^ ~~~~~
251 | | |
252 | int const char *
253
254
255 More on locations
256 *****************
257
258 For more details on the above, see :doc:`../topics/physical-locations`.
259 Otherwise the :doc:`next part of the tutorial <03-logical-locations>`
260 covers logical locations.