Debian Codegraph @

gcc/doc/libgdiagnostics/topics/metadata.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 Adding metadata
21 ===============
22
23 Tool metadata
24 *************
25
26 It's possible to set up various metadata on the :type:`diagnostic_manager`
27 as a whole, describing the program creating the diagnostics.
28
29 .. note::
30
31 It's not required to set up any of this up on a
32 :type:`diagnostic_manager`. However, if you are doing
33 :doc:`SARIF output <sarif>`, then you need to at least call
34 :func:`diagnostic_manager_set_tool_name` or the generated ``.sarif``
35 file will not validate against the schema.
36
37 .. function:: void diagnostic_manager_set_tool_name (diagnostic_manager *diag_mgr, \
38 const char *value)
39
40 Set a string for the name of the tool emitting the diagnostics.
41
42 Both parameters must be non-NULL.
43
44 If set, this string will be used
45
46 * by :doc:`text output sinks <text-output>` as a prefix for output
47 when no physical location is available, replacing ``progname``
48 in the following:
49
50 .. code-block:: console
51
52 $ ./tut01-hello-world
53 progname: error: I'm sorry Dave, I'm afraid I can't do that
54
55 * by :doc:`SARIF output sinks <sarif>` as the value for the
56 ``name`` property of the ``driver``
57 (`SARIF v2.1.0 §3.19.8 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790791>`_).
58
59 .. function:: void diagnostic_manager_set_full_name (diagnostic_manager *diag_mgr, \
60 const char *value)
61
62 Set a string giving the name of the tool along with the its version and
63 other useful information::
64
65 diagnostic_manager_set_full_name (diag_mgr, "FooChecker 0.1 (en_US)");
66
67 If set, this string will be used by :doc:`SARIF output sinks <sarif>` as
68 the value for the ``fullName`` property of the ``driver``
69 (`SARIF v2.1.0 §3.19.9 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790792>`_).
70
71 Both parameters must be non-NULL.
72
73 .. function:: void diagnostic_manager_set_version_string (diagnostic_manager *diag_mgr, \
74 const char *value)
75
76 Set a string suitable for use as the value of the SARIF ``version`` property
77 of the ``driver``.
78 (`SARIF v2.1.0 §3.19.13 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790796>`_)::
79
80 diagnostic_manager_set_version_string (diag_mgr, "0.1");
81
82 Both parameters must be non-NULL.
83
84 .. function:: void diagnostic_manager_set_version_url (diagnostic_manager *diag_mgr, \
85 const char *value)
86
87 Set a string suitable for use as the value of the SARIF ``informationUri``
88 property of the ``driver``.
89 (`SARIF v2.1.0 §3.19.17 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790800>`_)::
90
91 diagnostic_manager_set_version_url (diag_mgr,
92 "https://www.example.com/foo-checker/releases/0.1/");
93
94 Both parameters must be non-NULL.
95
96 Adding metadata to a diagnostic
97 *******************************
98
99 .. function:: void diagnostic_set_cwe (diagnostic *diag, \
100 unsigned cwe_id)
101
102 Associate ``diag`` with the given ID within
103 the `Common Weakness Enumeration <https://cwe.mitre.org/>`_::
104
105 /* CWE-242: Use of Inherently Dangerous Function. */
106 diagnostic_set_cwe (d, 242);
107
108 ``diag`` must be non-NULL.
109
110 The CWE value will be printed by text sinks after the message::
111
112 test-metadata.c:21:3: warning: never use 'gets' [CWE-242]
113
114 and in a sufficiently-capable terminal will be a link to
115 documentation about the CWE.
116
117 .. function:: void diagnostic_add_rule (diagnostic *diag, \
118 const char *title, \
119 const char *url)
120
121 Associate this :type:`diagnostic` with a particular rule that has been
122 violated (such as in a coding standard, or within a specification).
123
124 A diagnostic can be associated with zero or more rules.
125
126 ``diag`` must be non-NULL. The rule must have at least one of a
127 title and a URL, but these can be NULL.
128
129 For example, given::
130
131 diagnostic_add_rule (d,
132 "MSC24-C",
133 "https://wiki.sei.cmu.edu/confluence/display/c/MSC24-C.+Do+not+use+deprecated+or+obsolescent+functions");
134
135 the rule name will be printed by text sinks after the message::
136
137 test-metadata.c:21:3: warning: never use 'gets' [MSC24-C]
138 21 | gets (buf);
139 | ^~~~~~~~~~
140
141 and if so, the URL will be available in a sufficiently capable
142 terminal.
143
144 This can be used in conjunction with :func:`diagnostic_set_cwe`,
145 giving output like this::
146
147 test-metadata.c:21:3: warning: never use 'gets' [CWE-242] [MSC24-C]
148 21 | gets (buf);
149 | ^~~~~~~~~~