| 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 |
| ^~~~~~~~~~ |