| 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 3: logical locations |
| 21 |
================================== |
| 22 |
|
| 23 |
Let's extend the previous example to add a |
| 24 |
:doc:`logical location <../topics/logical-locations>` to the |
| 25 |
:type:`diagnostic`. |
| 26 |
|
| 27 |
First we create a :type:`diagnostic_logical_location` representing a |
| 28 |
particular function:: |
| 29 |
|
| 30 |
const diagnostic_logical_location *logical_loc |
| 31 |
= diagnostic_manager_new_logical_location (diag_mgr, |
| 32 |
DIAGNOSTIC_LOGICAL_LOCATION_KIND_FUNCTION, |
| 33 |
NULL, /* parent */ |
| 34 |
"foo", |
| 35 |
NULL, |
| 36 |
NULL); |
| 37 |
|
| 38 |
In this simple example we specify that it is a function, and just give |
| 39 |
it a name (``foo``). For more complicated cases we can set up tree-like |
| 40 |
hierarchies of logical locations, set qualified names, "mangled" names, |
| 41 |
and so on; see :func:`diagnostic_manager_new_logical_location` for details. |
| 42 |
|
| 43 |
Once we have :type:`diagnostic_logical_location` we can associate it with |
| 44 |
a :type:`diagnostic` with :func:`diagnostic_set_logical_location`:: |
| 45 |
|
| 46 |
diagnostic_set_logical_location (d, logical_loc); |
| 47 |
|
| 48 |
The logical location will be printed by text output sinks like this:: |
| 49 |
|
| 50 |
In function 'foo': |
| 51 |
|
| 52 |
and will be captured in :doc:`SARIF <../topics/sarif>` output. |
| 53 |
|
| 54 |
|
| 55 |
Find out more |
| 56 |
************* |
| 57 |
|
| 58 |
For more details on the above, see :doc:`../topics/logical-locations`. |
| 59 |
Otherwise the :doc:`next part of the tutorial <04-notes>` covers adding |
| 60 |
supplementary "notes" to a :type:`diagnostic`. |