| 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` |