| 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 1: "Hello world" |
| 21 |
============================== |
| 22 |
|
| 23 |
Before we look at the details of the API, let's look at building and |
| 24 |
running programs that use the library. |
| 25 |
|
| 26 |
Here's a toy program that uses libgdiagnostics to emit an error message |
| 27 |
to stderr. |
| 28 |
|
| 29 |
.. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-example-1.c |
| 30 |
:language: c |
| 31 |
:start-after: /* begin quoted source */ |
| 32 |
:end-before: /* end quoted source */ |
| 33 |
|
| 34 |
Copy the above to `tut01-hello-world.c`. |
| 35 |
|
| 36 |
Assuming you have libgdiagnostics installed, build the test program |
| 37 |
using: |
| 38 |
|
| 39 |
.. code-block:: console |
| 40 |
|
| 41 |
$ gcc \ |
| 42 |
tut01-hello-world.c \ |
| 43 |
-o tut01-hello-world \ |
| 44 |
-lgdiagnostics |
| 45 |
|
| 46 |
You should then be able to run the built program: |
| 47 |
|
| 48 |
.. code-block:: console |
| 49 |
|
| 50 |
$ ./tut01-hello-world |
| 51 |
progname: error: I'm sorry Dave, I'm afraid I can't do that |
| 52 |
|
| 53 |
If stderr is connected to a terminal, you should get colorized output |
| 54 |
(using `SGR control codes <https://en.wikipedia.org/wiki/ANSI_escape_code>`_). |
| 55 |
|
| 56 |
.. image:: example-1.png |
| 57 |
|
| 58 |
Otherwise, the output will be plain text. |
| 59 |
|
| 60 |
Obviously a trivial example like the above could be done using ``fprintf`` |
| 61 |
on stderr, and it's fairly easy to colorize text at the terminal. |
| 62 |
|
| 63 |
In :doc:`the next part of the tutorial <02-physical-locations>` we'll add |
| 64 |
file/location information to our error messages, and libgdiagnostics will |
| 65 |
quote the pertinent parts of the file, underlining them, which is less trivial |
| 66 |
to reimplement. libgdiagnostics gives us many other such abilities, such as |
| 67 |
fix-it hints and execution paths, which we'll cover in the following |
| 68 |
tutorials. Also, once a program's diagnostics are using libgdiagnostics, |
| 69 |
it is trivial to add support for outputting them in |
| 70 |
machine-readable form as :doc:`SARIF <../topics/sarif>`. |
| 71 |
|
| 72 |
|
| 73 |
Structure |
| 74 |
********* |
| 75 |
|
| 76 |
The above example shows the typical structure of a program using |
| 77 |
libgdiagnostics: |
| 78 |
|
| 79 |
* **initialization**: create a :type:`diagnostic_manager` instance, |
| 80 |
and create an output sink for it, and other one-time initialization |
| 81 |
|
| 82 |
* **emission**: create various :type:`diagnostic` instances, populating |
| 83 |
them with data, and calling "finish" once they're ready to be emitted. |
| 84 |
:doc:`Text sinks <../topics/text-output>` emit their diagnostics as soon |
| 85 |
as "finish" is called on them. |
| 86 |
|
| 87 |
* **cleanup**: call :func:`diagnostic_manager_release` on the |
| 88 |
:type:`diagnostic_manager` to finish and free up resources. |
| 89 |
:doc:`SARIF sinks <../topics/sarif>` write their output when |
| 90 |
:func:`diagnostic_manager_release` is called on the manager. |
| 91 |
|
| 92 |
For non-trivial examples we'll also want to create location information, |
| 93 |
which could happen during initialization, or during a parsing phase of |
| 94 |
the program using libgdiagnostics. See :doc:`02-physical-locations` for |
| 95 |
more information. |
| 96 |
|
| 97 |
|
| 98 |
Formatted messages |
| 99 |
****************** |
| 100 |
|
| 101 |
The above example uses :func:`diagnostic_finish`, which takes a format |
| 102 |
string and arguments. libgdiagnostics has its own style of format |
| 103 |
string arguments used for :func:`diagnostic_finish` and some other |
| 104 |
entrypoints. |
| 105 |
|
| 106 |
.. note:: The format syntax is *not* the same as ``printf``; see |
| 107 |
:doc:`supported formatting options <../topics/message-formatting>`. |
| 108 |
|
| 109 |
You can use the ``q`` modifier on arguments |
| 110 |
to quote them, so, for example ``%qs`` is a quoted string, consuming a |
| 111 |
``const char *`` argument:: |
| 112 |
|
| 113 |
diagnostic_finish (d, "can't find %qs", "foo"); |
| 114 |
|
| 115 |
This gives output like this: |
| 116 |
|
| 117 |
.. code-block:: console |
| 118 |
|
| 119 |
progname: error: can't find ‘foo’ |
| 120 |
|
| 121 |
where the quoted string will appear in bold in a suitably-capable |
| 122 |
terminal, and the quotes will be internationalized, so that e.g. with |
| 123 |
``LANG=fr_FR.UTF8`` we might get: |
| 124 |
|
| 125 |
.. code-block:: console |
| 126 |
|
| 127 |
progname: erreur: can't find « foo » |
| 128 |
|
| 129 |
Note that: |
| 130 |
|
| 131 |
* the string ``error`` has been localized by libgdiagnostics to |
| 132 |
``erreur``, |
| 133 |
|
| 134 |
* locale-specific quoting has been used (``«`` and ``»`` rather than |
| 135 |
``‘`` and ``’``), |
| 136 |
|
| 137 |
* ``foo`` hasn't been localized - you would typically use quoted strings |
| 138 |
for referring to identifiers in the input language (such as function names |
| 139 |
in code, property names in JSON, etc), |
| 140 |
|
| 141 |
* the message itself hasn't been localized: you are responsible for |
| 142 |
passing a translated format string to :func:`diagnostic_finish` if you |
| 143 |
want to internationalize the output. |
| 144 |
|
| 145 |
There are many :doc:`supported formatting options <../topics/message-formatting>`. |
| 146 |
|
| 147 |
|
| 148 |
Naming the program |
| 149 |
****************** |
| 150 |
|
| 151 |
In the above output the message was preceded with ``progname``. This |
| 152 |
appears for diagnostics that don't have any location information associated |
| 153 |
with them. We'll look at setting up location information in the |
| 154 |
:doc:`next tutorial <02-physical-locations>`, but we can override this |
| 155 |
default name via :func:`diagnostic_manager_set_tool_name`:: |
| 156 |
|
| 157 |
diagnostic_manager_set_tool_name (diag_mgr, "my-awesome-checker"); |
| 158 |
|
| 159 |
leading to output like this:: |
| 160 |
|
| 161 |
my-awesome-checker: error: can't find ‘foo’ |
| 162 |
|
| 163 |
There are various other functions for |
| 164 |
:doc:`supplying metadata to libgdiagnostics <../../topics/metadata>`. |
| 165 |
|
| 166 |
|
| 167 |
Moving beyond trivial examples |
| 168 |
****************************** |
| 169 |
|
| 170 |
Obviously it's not very useful if we can't refer to specific files and |
| 171 |
specific locations in those files in our diagnostics, so read |
| 172 |
:doc:`part 2 of the tutorial <02-physical-locations>` for information on |
| 173 |
how to do this. |