Debian Codegraph @

gcc/doc/libgdiagnostics/tutorial/01-hello-world.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 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.