Add clang-tidy config file
[babeltrace.git] / CONTRIBUTING.adoc
CommitLineData
cd4aac1e
PP
1// Render with Asciidoctor
2
28b765ac 3= Babeltrace{nbsp}2 contributor's guide
f9ded0e0 4Jérémie Galarneau, Philippe Proulx
a1ac73cf 522 February 2024
28b765ac
PP
6:toc: left
7:toclevels: 3
fb7ff115
PP
8:icons: font
9:nofooter:
28b765ac 10:bt2: Babeltrace{nbsp}2
fb7ff115
PP
11:c-cpp: C/{cpp}
12:cpp11: {cpp}11
a1ac73cf 13:fmt: pass:[{fmt}]
beb0fb75 14
f9ded0e0 15This is a partial contributor's guide for the
28b765ac 16https://babeltrace.org[{bt2}] project. If you have any
cd4aac1e
PP
17questions that are not answered by this guide, please post them on
18https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[Babeltrace's
19mailing list].
20
28b765ac 21== {bt2} library
f9ded0e0 22
cd4aac1e 23=== Object reference counting and lifetime
f9ded0e0 24
28b765ac
PP
25This section covers the rationale behind the design of {bt2}'s
26object lifetime management. This applies to the {bt2} library, as
cd4aac1e
PP
27well as to the CTF writer library (although the public reference
28counting functions are not named the same way).
f9ded0e0 29
28b765ac
PP
30Starting from Babeltrace{nbsp}2.0, all publicly exposed objects inherit
31a common base: `bt_object`. This base provides a number of facilities to
f9ded0e0
PP
32all objects, chief amongst which are lifetime management functions.
33
cd4aac1e
PP
34The lifetime of some public objects is managed by reference counting. In
35this case, the API offers the `+bt_*_get_ref()+` and `+bt_*_put_ref()+`
36functions which respectively increment and decrement an object's
37reference count.
f9ded0e0 38
28b765ac 39As far as lifetime management in concerned, {bt2} makes a clear
f9ded0e0
PP
40distinction between regular objects, which have a single parent, and
41root objects, which don't.
42
cd4aac1e 43==== The problem
f9ded0e0
PP
44
45Let us consider a problematic case to illustrate the need for this
46distinction.
47
28b765ac 48A user of the {bt2} library creates a trace class, which _has_ a
cd4aac1e
PP
49stream class (the class of a stream) and that stream class, in turn,
50_has_ an event class (the class of an event).
f9ded0e0
PP
51
52Nothing prevents this user from releasing his reference on any one of
53these objects in any order. However, all objects in the
54__trace--stream class--event class__ hierarchy can be retrieved
55from any other.
56
57For instance, the user could discard his reference on both the event
cd4aac1e
PP
58class and the stream class, only keeping a reference on the trace class.
59From this trace class reference, stream classes can be enumerated,
60providing the user with a new reference to the stream class he discarded
61earlier. Event classes can also be enumerated from stream classes,
62providing the user with references to the individual event classes.
f9ded0e0
PP
63
64Conversely, the user could also hold a reference to an event class and
cd4aac1e 65retrieve its parent stream class. The trace class, in turn, can then be
f9ded0e0
PP
66retrieved from the stream class.
67
68This example illustrates what could be interpreted as a circular
69reference dependency existing between these objects. Of course, if the
70objects in such a scenario were to hold references to each other (in
71both directions), we would be in presence of a circular ownership
72resulting in a leak of both objects as their reference counts would
73never reach zero.
74
75Nonetheless, the API must offer the guarantee that holding a node to any
76node of the graph keeps all other reachable nodes alive.
77
cd4aac1e 78==== The solution
f9ded0e0 79
28b765ac 80The scheme employed in {bt2} to break this cycle consists in the
cd4aac1e 81"children" holding _reverse component references_ to their parents. That
56e18c4c
PP
82is, in the context of the trace IR, that event classes hold a reference
83to their parent stream class and stream classes hold a reference to
cd4aac1e 84their parent trace class.
f9ded0e0 85
cd4aac1e 86On the other hand, parents hold _claiming aggregation references_ to
f9ded0e0
PP
87their children. A claiming aggregation reference means that the object
88being referenced should not be deleted as long as the reference still
89exists. In this respect, it can be said that parents truly hold the
90ownership of their children, since they control their lifetime.
91Conversely, the reference counting mechanism is leveraged by children to
92notify parents that no other child indirectly exposes the parent.
93
94When a parented object's reference count reaches zero, it invokes
cd4aac1e
PP
95`+bt_*_put_ref()+` on its parent and does _not_ free itself. However,
96from that point, the object depends on its parent to signal the moment
97when it can be safely reclaimed.
98
99The invocation of `+bt_*_put_ref()+` by the last children holding a
100reference to its parent might trigger a cascade of `+bt_*_put_ref()+`
101from child to parent. Eventually, a **root** object is reached. At that
102point, if this orphaned object's reference count reaches zero, the
103object invokes the destructor method defined by everyone of its children
104as part of their base `struct bt_object`. The key point here is that the
105cascade of destructor will necessarily originate from the root and
106propagate in preorder to the children. These children will propagate the
107destruction to their own children before reclaiming their own memory.
108This ensures that a node's pointer to its parent is _always_ valid since
109the parent has the responsibility of tearing-down their children before
110cleaning themselves up.
111
112Assuming a reference to an object is _acquired_ by calling
113`+bt_*_get_ref()+` while its reference count is zero, the object
114acquires, in turn, a reference on its parent using `+bt_*_get_ref()+`.
115At that point, the child can be thought of as having converted its weak
116reference to its parent into a regular reference. That is why this
117reference is referred to as a _claiming_ aggregation reference.
118
cd4aac1e 119==== Caveats
f9ded0e0
PP
120
121This scheme imposes a number of strict rules defining the relation
122between objects:
123
124* Objects may only have one parent.
125* Objects, beside the root, are only retrievable from their direct
126 parent or children.
127
cd4aac1e 128==== Example
f9ded0e0 129
cd4aac1e
PP
130The initial situation is rather simple: **User{nbsp}A** is holding a
131reference to a trace class, **TC1**. As per the rules previously
132enounced, stream classes **SC1** and **SC2** don't hold a reference to
133**TC1** since their own reference counts are zero. The same holds true
134for **EC1**, **EC2** and **EC3** with respect to **SC1** and **SC2**.
f9ded0e0
PP
135
136image::doc/contributing-images/bt-ref01.png[]
137
cd4aac1e
PP
138In this second step, we can see that **User{nbsp}A** has acquired a
139reference on **SC2** through the trace class, **TC1**.
f9ded0e0
PP
140
141The stream class's reference count transitions from zero to one,
142triggering the acquisition of a strong reference on **TC1** from
143**SC2**.
144
cd4aac1e
PP
145Hence, at this point, the trace class's ownership is shared by
146**User{nbsp}A** and **SC2**.
f9ded0e0
PP
147
148image::doc/contributing-images/bt-ref02.png[]
149
cd4aac1e
PP
150Next, **User{nbsp}A** acquires a reference on the **EC3** event class
151through its parent stream class, **SC2**. Again, the transition of an
152object's reference count from 0 to 1 triggers the acquisition of a
153reference on its parent.
f9ded0e0 154
cd4aac1e 155Note that SC2's reference count was incremented to 2. The trace class's
f9ded0e0
PP
156reference count remains unchanged.
157
158image::doc/contributing-images/bt-ref03.png[]
159
cd4aac1e
PP
160**User{nbsp}A** decides to drop its reference on **SC2**. **SC2**'s
161reference count returns back to 1, everything else remaining unchanged.
f9ded0e0
PP
162
163image::doc/contributing-images/bt-ref04.png[]
164
cd4aac1e
PP
165**User{nbsp}A** can then decide to drop its reference on the trace
166class. This results in a reversal of the initial situation:
167**User{nbsp}A** now owns an event, **EC3**, which is keeping everything
168else alive and reachable.
f9ded0e0
PP
169
170image::doc/contributing-images/bt-ref05.png[]
171
cd4aac1e 172If another object, **User{nbsp}B**, enters the picture and acquires a
f9ded0e0
PP
173reference on the **SC1** stream class, we see that **SC1**'s reference
174count transitioned from 0 to 1, triggering the acquisition of a
175reference on **TC1**.
176
177image::doc/contributing-images/bt-ref06.png[]
178
cd4aac1e
PP
179**User{nbsp}B** hands off a reference to **EC1**, acquired through
180**SC1**, to another object, **User{nbsp}C**. The acquisition of a
181reference on **EC1**, which transitions from 0 to 1, triggers the
182acquisition of a reference on its parent, **SC1**.
f9ded0e0
PP
183
184image::doc/contributing-images/bt-ref07.png[]
185
cd4aac1e 186At some point, **User{nbsp}A** releases its reference on **EC3**. Since
f9ded0e0
PP
187**EC3**'s reference count transitions to zero, it releases its reference
188on **SC2**. **SC2**'s reference count, in turn, reaches zero and it
189releases its reference to **TC1**.
190
191**TC1**'s reference count is now 1 and no further action is taken.
192
193image::doc/contributing-images/bt-ref08.png[]
194
cd4aac1e
PP
195**User{nbsp}B** releases its reference on **SC1**. **User{nbsp}C**
196becomes the sole owner of the whole hierarchy through his ownership of
197**EC1**.
f9ded0e0
PP
198
199image::doc/contributing-images/bt-ref09.png[]
200
cd4aac1e
PP
201Finally, **User{nbsp}C** releases his ownership of **EC1**, triggering
202the release of the whole hierarchy. Let's walk through the reclamation
203of the whole graph.
f9ded0e0 204
cd4aac1e
PP
205Mirroring what happened when **User{nbsp}A** released its last reference
206on **EC3**, the release of **EC1** by **User{nbsp}C** causes its
207reference count to fall to zero.
f9ded0e0
PP
208
209This transition to zero causes **EC1** to release its reference on
210**SC1**. **SC1**'s reference count reaching zero causes it to release
211its reference on **TC1**.
212
213image::doc/contributing-images/bt-ref10.png[]
214
215Since the reference count of **TC1**, a root object, has reached zero,
216it invokes the destructor method on its children. This method is
217recursive and causes the stream classes to call the destructor method on
218their event classes.
219
220The event classes are reached and, having no children of their own, are
221reclaimed.
222
223image::doc/contributing-images/bt-ref11.png[]
224
225The stream classes having destroyed their children, are then reclaimed
cd4aac1e 226by the trace class.
f9ded0e0
PP
227
228image::doc/contributing-images/bt-ref12.png[]
229
230Finally, the stream classes having been reclaimed, **TC1** is reclaimed.
231
232image::doc/contributing-images/bt-ref13.png[]
233
234
f9ded0e0 235== Logging
beb0fb75
PP
236
237Logging is a great instrument for a developer to be able to collect
238information about a running software.
239
28b765ac 240{bt2} is a complex software with many layers. When a {bt2}
beb0fb75 241graph fails to run, what caused the failure? It could be caused by any
cd4aac1e
PP
242component, any message iterator, and any deeply nested validation of a
243CTF IR object (within the `ctf` plugin), for example. With the
244appropriate logging statements manually placed in the source code, we
245can find the cause of a bug faster.
beb0fb75 246
cd4aac1e
PP
247While <<choose-a-log-level,care must be taken>> when placing _DEBUG_ to
248_FATAL_ logging statements, you should liberally instrument your
28b765ac 249{bt2} module with _TRACE_ logging statements to help future you
cd4aac1e 250and other developers understand what's happening at run time.
beb0fb75 251
f9ded0e0 252=== Logging API
beb0fb75 253
28b765ac 254The {bt2} logging API is internal: it is not exposed to the users
cd4aac1e 255of the library; only to their developers. The only thing that a library
4a41523d 256user can control is the current log level of the library itself with
beb0fb75 257`bt_logging_set_global_level()` and the initial library's log level with
cd4aac1e 258the `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable.
beb0fb75
PP
259
260This API is based on https://github.com/wonder-mice/zf_log[zf_log], a
261lightweight, yet featureful, MIT-licensed core logging library for C and
fb7ff115 262{cpp}. The zf_log source files were modified to have the `BT_` and
cd4aac1e
PP
263`bt_` prefixes, and other small changes, like color support and using
264the project's `BT_DEBUG_MODE` definition instead of the standard
265`NDEBUG`.
beb0fb75
PP
266
267The logging functions are implemented in the logging convenience
cd4aac1e 268library (`src/logging` directory).
beb0fb75 269
cd4aac1e 270[[logging-headers]]
f9ded0e0 271==== Headers
beb0fb75
PP
272
273The logging API headers are:
274
3fadfbc0 275`<babeltrace2/logging.h>`::
cd4aac1e 276 Public header which a library user can use to set and get
a12f3d62 277 libbabeltrace2's current log level.
beb0fb75 278
cd4aac1e 279`"logging/log.h"`::
28b765ac 280 Internal, generic logging API which you can use in any {bt2}
cd4aac1e
PP
281 module. This is the translation of `zf_log.h`.
282+
283This header offers the <<gen-logging-statements,generic logging
284statement macros>>.
beb0fb75 285
cd4aac1e
PP
286`"lib/logging.h"`::
287 Specific internal header to use within the library.
288+
289This header defines `BT_LOG_OUTPUT_LEVEL` to a custom, library-wide
290hidden symbol which is the library's current log level before including
291`"logging/log.h"`.
292+
293This header offers the <<lib-logging-statements,library-specific logging
294statement macros>>.
beb0fb75 295
d9c39b0a 296`"logging/comp-logging.h"`::
cd4aac1e
PP
297 Specific internal header to use within a component class.
298+
299This header offers the <<comp-logging-statements,component-specific
300logging statement macros>>.
beb0fb75 301
cd4aac1e 302[[log-levels]]
f9ded0e0 303==== Log levels
beb0fb75 304
cd4aac1e
PP
305The internal logging API offers the following log levels, in ascending
306order of severity:
beb0fb75 307
cd4aac1e
PP
308[options="header,autowidth",cols="4"]
309|===
310|Log level name
311|Log level short name
312|Internal API enumerator
313|Public API enumerator
314
ef267d12
PP
315|_TRACE_
316|`T`
317|`BT_LOG_TRACE`
318|`BT_LOGGING_LEVEL_TRACE`
cd4aac1e
PP
319
320|_DEBUG_
321|`D`
322|`BT_LOG_DEBUG`
323|`BT_LOGGING_LEVEL_DEBUG`
324
325|_INFO_
326|`I`
327|`BT_LOG_INFO`
328|`BT_LOGGING_LEVEL_INFO`
329
770538dd 330|_WARNING_
cd4aac1e 331|`W`
770538dd
PP
332|`BT_LOG_WARNING`
333|`BT_LOGGING_LEVEL_WARNING`
cd4aac1e
PP
334
335|_ERROR_
336|`E`
337|`BT_LOG_ERROR`
338|`BT_LOGGING_LEVEL_ERROR`
339
340|_FATAL_
341|`F`
342|`BT_LOG_FATAL`
343|`BT_LOGGING_LEVEL_FATAL`
344
345|_NONE_
346|`N`
347|`BT_LOG_NONE`
348|`BT_LOGGING_LEVEL_NONE`
349|===
350
351The short name is accepted by the log level environment variables and by
352the CLI's `--log-level` options.
beb0fb75 353
cd4aac1e 354See <<choose-a-log-level,how to decide which one to use>> below.
beb0fb75 355
cd4aac1e 356There are two important log level expressions:
beb0fb75
PP
357
358[[build-time-log-level]]Build-time, minimal log level::
cd4aac1e
PP
359 The minimal log level, or build-time log level, is set at build time
360 and determines the minimal log level of the logging statements which
361 can be executed. This applies to all the modules (CLI, library,
362 plugins, bindings, etc.).
beb0fb75
PP
363+
364All the logging statements with a level below this level are **not built
365at all**. All the logging statements with a level equal to or greater
f9ded0e0
PP
366than this level _can_ be executed, depending on the
367<<run-time-log-level,run-time log level>>.
beb0fb75
PP
368+
369You can set this level at configuration time with the
370`BABELTRACE_MINIMAL_LOG_LEVEL` environment variable, for example:
371+
372--
373----
770538dd 374$ BABELTRACE_MINIMAL_LOG_LEVEL=INFO ./configure
beb0fb75
PP
375----
376--
377+
cd4aac1e
PP
378The default build-time log level is `DEBUG`. For optimal performance,
379set it to `INFO`, which effectively disables all fast path logging in
28b765ac 380all the {bt2} modules. You can't set it to `WARNING`, `ERROR`,
dd22a91f 381`FATAL`, or `NONE` because the impact on performance is minuscule
28b765ac 382starting from the _INFO_ log level anyway and we want any {bt2}
dd22a91f 383build to always be able to print _INFO_-level logs.
beb0fb75
PP
384+
385The library's public API provides `bt_logging_get_minimal_level()` to
386get the configured minimal log level.
387
388[[run-time-log-level]]Run-time, dynamic log level::
cd4aac1e
PP
389 The dynamic log level is set at run time and determines the current,
390 _active_ log level. All the logging statements with a level below
391 this level are not executed, **but they still evaluate the
392 condition**. All the logging statements with a level equal to or
393 greater than this level are executed, provided that their level is
394 also <<build-time-log-level,enabled at build time>>.
beb0fb75 395+
f9ded0e0
PP
396`zf_log` has a concept of a global run-time log level which uses the
397`_bt_log_global_output_lvl` symbol. In practice, we never use this
398symbol, and always make sure that `BT_LOG_OUTPUT_LEVEL` is defined to a
cd4aac1e
PP
399module-wise expression before including `"logging/log.h"`.
400+
401In the library, `"lib/logging.h"` defines its own
402`BT_LOG_OUTPUT_LEVEL` to the library's log level symbol before it
403includes `"logging/log.h"` itself.
beb0fb75 404+
a12f3d62 405In libbabeltrace2, the user can set the current run-time log level with
beb0fb75
PP
406the `bt_logging_set_global_level()` function, for example:
407+
408--
409[source,c]
410----
411bt_logging_set_global_level(BT_LOGGING_LEVEL_INFO);
412----
413--
414+
415The library's initial run-time log level is defined by the
cd4aac1e
PP
416`LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable, or set to _NONE_
417if this environment variable is undefined.
418+
419Other modules have their own way of setting their run-time log level.
420+
421For example, the CLI uses the `BABELTRACE_CLI_LOG_LEVEL` environment
422variable, as well as its global `--log-level` option:
423+
424----
425$ babeltrace2 --log-level=I ...
426----
427+
428The components use their own log level (as returned by
429`bt_component_get_logging_level()`). With the CLI, you can set a
430specific component's log level with its own, position-dependent
431`--log-level` option:
432+
433----
434$ babeltrace2 /path/to/trace -c sink.ctf.fs --log-level=D
435----
436+
437Code which is common to the whole project, for example `src/common`
438and `src/compat`, use function parameters to get its run-time log
439level, for example:
440+
441[source,c]
442----
cd4aac1e
PP
443char *bt_common_get_home_plugin_path(int log_level);
444----
beb0fb75 445+
cd4aac1e
PP
446Typically, when a logging-enabled module calls such a function, it
447passes its own log level expression directly (`BT_LOG_OUTPUT_LEVEL`):
beb0fb75 448+
cd4aac1e
PP
449[source,c]
450----
451path = bt_common_get_home_plugin_path(BT_LOG_OUTPUT_LEVEL);
452----
453+
454Otherwise, just pass `BT_LOG_NONE`:
455+
456----
457path = bt_common_get_home_plugin_path(BT_LOG_NONE);
458----
459
cd4aac1e
PP
460[[gen-logging-statements]]
461==== Generic logging statement macros
462
28b765ac 463The {bt2} logging statement macros work just like `printf()`
cd4aac1e
PP
464(except the `+BT_LOG*_STR()+` ones) and contain their <<log-levels,log
465level>> (short name) in their name.
beb0fb75 466
cd4aac1e
PP
467Each of the following macros evaluate the
468<<build-time-log-level,build-time log level>> definition and
469<<run-time-log-level,run-time log level>> expression (as defined by
470`BT_LOG_OUTPUT_LEVEL`) to log conditionally.
beb0fb75 471
28b765ac
PP
472See <<logging-instrument-c-file-gen>> and
473<<logging-instrument-h-file-gen>> to learn how to be able to use the
474following macros.
beb0fb75 475
ef267d12
PP
476`+BT_LOGT("format string", ...)+`::
477 Generic trace logging statement.
beb0fb75 478
cd4aac1e
PP
479`+BT_LOGD("format string", ...)+`::
480 Generic debug logging statement.
beb0fb75 481
cd4aac1e
PP
482`+BT_LOGI("format string", ...)+`::
483 Generic info logging statement.
beb0fb75 484
cd4aac1e
PP
485`+BT_LOGW("format string", ...)+`::
486 Generic warning logging statement.
beb0fb75 487
cd4aac1e
PP
488`+BT_LOGE("format string", ...)+`::
489 Generic error logging statement.
beb0fb75 490
cd4aac1e
PP
491`+BT_LOGF("format string", ...)+`::
492 Generic fatal logging statement.
beb0fb75 493
ef267d12
PP
494`+BT_LOGT_STR("preformatted string")+`::
495 Generic preformatted string trace logging statement.
beb0fb75 496
cd4aac1e
PP
497`+BT_LOGD_STR("preformatted string")+`::
498 Generic preformatted string debug logging statement.
beb0fb75 499
cd4aac1e
PP
500`+BT_LOGI_STR("preformatted string")+`::
501 Generic preformatted string info logging statement.
beb0fb75 502
cd4aac1e
PP
503`+BT_LOGW_STR("preformatted string")+`::
504 Generic preformatted string warning logging statement.
beb0fb75 505
cd4aac1e
PP
506`+BT_LOGE_STR("preformatted string")+`::
507 Generic preformatted string error logging statement.
beb0fb75 508
cd4aac1e
PP
509`+BT_LOGF_STR("preformatted string")+`::
510 Generic preformatted string fatal logging statement.
beb0fb75 511
ef267d12
PP
512`+BT_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
513 Generic memory trace logging statement.
beb0fb75 514
cd4aac1e
PP
515`+BT_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
516 Generic memory debug logging statement.
b81626f9 517
cd4aac1e
PP
518`+BT_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
519 Generic memory info logging statement.
b81626f9 520
cd4aac1e
PP
521`+BT_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
522 Generic memory warning logging statement.
b81626f9 523
cd4aac1e
PP
524`+BT_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
525 Generic memory error logging statement.
b81626f9 526
cd4aac1e
PP
527`+BT_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
528 Generic memory fatal logging statement.
b81626f9 529
ef267d12
PP
530`+BT_LOGT_ERRNO("initial message", "format string", ...)+`::
531 Generic `errno` string trace logging statement.
b81626f9 532
cd4aac1e
PP
533`+BT_LOGD_ERRNO("initial message", "format string", ...)+`::
534 Generic `errno` string debug logging statement.
beb0fb75 535
cd4aac1e
PP
536`+BT_LOGI_ERRNO("initial message", "format string", ...)+`::
537 Generic `errno` string info logging statement.
beb0fb75 538
cd4aac1e
PP
539`+BT_LOGW_ERRNO("initial message", "format string", ...)+`::
540 Generic `errno` string warning logging statement.
beb0fb75 541
cd4aac1e
PP
542`+BT_LOGE_ERRNO("initial message", "format string", ...)+`::
543 Generic `errno` string error logging statement.
beb0fb75 544
cd4aac1e
PP
545`+BT_LOGF_ERRNO("initial message", "format string", ...)+`::
546 Generic `errno` string fatal logging statement.
beb0fb75 547
cd4aac1e
PP
548[[lib-logging-statements]]
549==== Library-specific logging statement macros
550
28b765ac
PP
551The {bt2} library contains an internal logging API based on the
552generic logging framework. You can use it to log known {bt2}
cd4aac1e
PP
553objects without having to manually log each member.
554
28b765ac
PP
555See <<logging-instrument-c-file-lib>>
556and <<logging-instrument-h-file-lib>> to
cd4aac1e
PP
557learn how to be able to use the following macros.
558
559The library logging statement macros are named `+BT_LIB_LOG*()+` instead
560of `+BT_LOG*()+`:
561
ef267d12
PP
562`+BT_LIB_LOGT("format string", ...)+`::
563 Library trace logging statement.
cd4aac1e
PP
564
565`+BT_LIB_LOGD("format string", ...)+`::
566 Library debug logging statement.
567
568`+BT_LIB_LOGI("format string", ...)+`::
569 Library info logging statement.
570
571`+BT_LIB_LOGW("format string", ...)+`::
572 Library warning logging statement.
573
574`+BT_LIB_LOGE("format string", ...)+`::
575 Library error logging statement.
576
577`+BT_LIB_LOGF("format string", ...)+`::
578 Library fatal logging statement.
579
3cd4c495
PP
580`+BT_LIB_LOGW_APPEND_CAUSE("format string", ...)+`::
581 Library warning logging statement, and unconditional error cause
582 appending.
583
584`+BT_LIB_LOGE_APPEND_CAUSE("format string", ...)+`::
585 Library error logging statement, and unconditional error cause
3cd4c495
PP
586 appending.
587
cd4aac1e
PP
588The macros above accept the typical `printf()` conversion specifiers
589with the following limitations:
590
591* The `+*+` width specifier is not accepted.
592* The `+*+` precision specifier is not accepted.
593* The `j` and `t` length modifiers are not accepted.
594* The `n` format specifier is not accepted.
595* The format specifiers defined in `<inttypes.h>` are not accepted,
596 except for `PRId64`, `PRIu64`, `PRIx64`, `PRIX64`, `PRIo64`, and
597 `PRIi64`.
598
28b765ac 599The {bt2} library custom conversion specifier is accepted. Its
cd4aac1e
PP
600syntax is either `%!u` to format a UUID (`bt_uuid` type), or:
601
602. Introductory `%!` sequence.
603
604. **Optional**: `[` followed by a custom prefix for the printed fields
605 of this specifier, followed by `]`. The standard form is to end this
606 prefix with `-` so that, for example, with the prefix `tc-`, the
607 complete field name becomes `tc-addr`.
608
609. **Optional**: `pass:[+]` to print extended object members. This
610 depends on the provided format specifier.
611
612. Format specifier (see below).
613
614The available format specifiers are:
615
616[options="header,autowidth",cols="3"]
617|===
618|Specifier
619|Object
620|Expected C type
621
622|`F`
623|Trace IR field class
6769570a 624|`+const struct bt_field_class *+`
cd4aac1e
PP
625
626|`f`
627|Trace IR field
6769570a 628|`+const struct bt_field *+`
cd4aac1e
PP
629
630|`P`
631|Trace IR field path
6769570a 632|`+const struct bt_field_path *+`
cd4aac1e
PP
633
634|`E`
635|Trace IR event class
6769570a 636|`+const struct bt_event_class *+`
cd4aac1e
PP
637
638|`e`
639|Trace IR event
6769570a 640|`+const struct bt_event *+`
cd4aac1e
PP
641
642|`S`
643|Trace IR stream class.
6769570a 644|`+const struct bt_stream_class *+`
cd4aac1e
PP
645
646|`s`
647|Trace IR stream
6769570a 648|`+const struct bt_stream *+`
cd4aac1e
PP
649
650|`a`
651|Trace IR packet
6769570a 652|`+const struct bt_packet *+`
cd4aac1e
PP
653
654|`T`
655|Trace IR trace class
6769570a 656|`+const struct bt_trace_class *+`
cd4aac1e
PP
657
658|`t`
659|Trace IR trace
6769570a 660|`+const struct bt_trace *+`
cd4aac1e
PP
661
662|`K`
663|Trace IR clock class
6769570a 664|`+const struct bt_clock_class *+`
cd4aac1e
PP
665
666|`k`
667|Trace IR clock snapshot
6769570a 668|`+const struct bt_clock_snapshot *+`
cd4aac1e
PP
669
670|`v`
671|Value object
6769570a
PP
672|`+const struct bt_value *+`
673
674|`R`
675|Integer range set
676|`const struct bt_integer_range_set *`
cd4aac1e
PP
677
678|`n`
679|Message
6769570a 680|`+const struct bt_message *+`
cd4aac1e 681
a3f0c7db
SM
682|`I`
683|Message iterator class
684|`struct bt_message_iterator_class *`
685
cd4aac1e
PP
686|`i`
687|Message iterator
688|`struct bt_message_iterator *`
689
690|`C`
691|Component class
692|`struct bt_component_class *`
693
694|`c`
695|Component
6769570a 696|`+const struct bt_component *+`
cd4aac1e
PP
697
698|`p`
699|Port
6769570a 700|`+const struct bt_port *+`
cd4aac1e
PP
701
702|`x`
703|Connection
6769570a 704|`+const struct bt_connection *+`
cd4aac1e
PP
705
706|`g`
707|Graph
6769570a 708|`+const struct bt_graph *+`
cd4aac1e 709
b70d57a1
PP
710|`z`
711|Interrupter
712|`+struct bt_interrupter *+`
713
cd4aac1e
PP
714|`l`
715|Plugin
6769570a 716|`+const struct bt_plugin *+`
cd4aac1e 717
553c4bab
PP
718|`r`
719|Error cause
6769570a 720|`+const struct bt_error_cause *+`
553c4bab 721
cd4aac1e
PP
722|`o`
723|Object pool
6769570a 724|`+const struct bt_object_pool *+`
cd4aac1e
PP
725
726|`O`
727|Object
6769570a 728|`+const struct bt_object *+`
cd4aac1e
PP
729|===
730
731Conversion specifier examples:
732
733* `%!f`
734* `%![my-event-]+e`
735* `%!t`
736* `%!+F`
737
738The ``, `` string (comma and space) is printed between individual
739fields, but **not after the last one**. Therefore, you must put this
740separator in the format string between two conversion specifiers, for
741example:
742
743[source,c]
744----
745BT_LIB_LOGW("Message: count=%u, %!E, %!+K", count, event_class, clock_class);
746----
747
748Example with a custom prefix:
749
750[source,c]
751----
752BT_LIB_LOGI("Some message: %![ec-a-]e, %![ec-b-]+e", ec_a, ec_b);
753----
754
28b765ac 755It is safe to pass `NULL` as any {bt2} object parameter: the macros
cd4aac1e
PP
756only print its null address.
757
758WARNING: Build-time `printf()` format checks are disabled for the
759`+BT_LIB_LOG*()+` macros because there are custom conversion specifiers,
760so make sure to test your logging statements.
761
cd4aac1e
PP
762[[comp-logging-statements]]
763==== Component-specific logging statement macros
764
765There are available logging macros for components. They prepend a prefix
766including the component's name to the logging message.
767
28b765ac
PP
768See <<logging-instrument-c-file-compcls>> and
769<<logging-instrument-h-file-compcls>> to learn how to be able to use the
cd4aac1e
PP
770following macros.
771
772The component logging statement macros are named `+BT_COMP_LOG*()+`
773instead of `+BT_LOG*()+`:
774
ef267d12
PP
775`+BT_COMP_LOGT("format string", ...)+`::
776 Component trace logging statement.
cd4aac1e
PP
777
778`+BT_COMP_LOGD("format string", ...)+`::
779 Component debug logging statement.
780
781`+BT_COMP_LOGI("format string", ...)+`::
782 Component info logging statement.
783
784`+BT_COMP_LOGW("format string", ...)+`::
785 Component warning logging statement.
786
787`+BT_COMP_LOGE("format string", ...)+`::
788 Component error logging statement.
789
790`+BT_COMP_LOGF("format string", ...)+`::
791 Component fatal logging statement.
792
ef267d12
PP
793`+BT_COMP_LOGT_STR("preformatted string")+`::
794 Component preformatted string trace logging statement.
cd4aac1e
PP
795
796`+BT_COMP_LOGD_STR("preformatted string")+`::
797 Component preformatted string debug logging statement.
798
799`+BT_COMP_LOGI_STR("preformatted string")+`::
800 Component preformatted string info logging statement.
801
802`+BT_COMP_LOGW_STR("preformatted string")+`::
803 Component preformatted string warning logging statement.
804
805`+BT_COMP_LOGE_STR("preformatted string")+`::
806 Component preformatted string error logging statement.
807
808`+BT_COMP_LOGF_STR("preformatted string")+`::
809 Component preformatted string fatal logging statement.
810
ef267d12
PP
811`+BT_COMP_LOGT_ERRNO("initial message", "format string", ...)+`::
812 Component `errno` string trace logging statement.
cd4aac1e
PP
813
814`+BT_COMP_LOGD_ERRNO("initial message", "format string", ...)+`::
815 Component `errno` string debug logging statement.
816
817`+BT_COMP_LOGI_ERRNO("initial message", "format string", ...)+`::
818 Component `errno` string info logging statement.
819
820`+BT_COMP_LOGW_ERRNO("initial message", "format string", ...)+`::
821 Component `errno` string warning logging statement.
822
823`+BT_COMP_LOGE_ERRNO("initial message", "format string", ...)+`::
824 Component `errno` string error logging statement.
825
826`+BT_COMP_LOGF_ERRNO("initial message", "format string", ...)+`::
827 Component `errno` string fatal logging statement.
828
ef267d12
PP
829`+BT_COMP_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
830 Component memory trace logging statement.
cd4aac1e
PP
831
832`+BT_COMP_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
833 Component memory debug logging statement.
834
835`+BT_COMP_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
836 Component memory info logging statement.
837
838`+BT_COMP_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
839 Component memory warning logging statement.
840
841`+BT_COMP_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
842 Component memory error logging statement.
843
844`+BT_COMP_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
845 Component memory fatal logging statement.
beb0fb75 846
f9ded0e0 847==== Conditional logging
beb0fb75 848
cd4aac1e 849`+BT_LOG_IF(cond, statement)+`::
beb0fb75
PP
850 Execute `statement` only if `cond` is true.
851+
852Example:
853+
854--
855[source,c]
856----
857BT_LOG_IF(i < count / 2, BT_LOGD("Log this: i=%d", i));
858----
859--
860
861To check the <<build-time-log-level,build-time log level>>:
862
863[source,c]
864----
865#if BT_LOG_ENABLED_DEBUG
866...
867#endif
868----
869
cd4aac1e
PP
870This tests if the _DEBUG_ level was enabled at build time. This means
871that the current, <<run-time-log-level,run-time log level>> _could_ be
f9ded0e0
PP
872_DEBUG_, but it could also be higher. The rule of thumb is to use only
873logging statements at the same level in a `BT_LOG_ENABLED_*` conditional
874block.
beb0fb75
PP
875
876The available definitions for build-time conditions are:
877
ef267d12 878* `BT_LOG_ENABLED_TRACE`
beb0fb75
PP
879* `BT_LOG_ENABLED_DEBUG`
880* `BT_LOG_ENABLED_INFO`
770538dd 881* `BT_LOG_ENABLED_WARNING`
beb0fb75
PP
882* `BT_LOG_ENABLED_ERROR`
883* `BT_LOG_ENABLED_FATAL`
884
885To check the current, <<run-time-log-level,run-time log level>>:
886
887[source,c]
888----
889if (BT_LOG_ON_DEBUG) {
890 ...
891}
892----
893
894This tests if the _DEBUG_ log level is dynamically turned on
cd4aac1e 895(implies that it's also enabled at build time). This check could have a
beb0fb75
PP
896noticeable impact on performance.
897
898The available definitions for run-time conditions are:
899
ef267d12 900* `BT_LOG_ON_TRACE`
beb0fb75
PP
901* `BT_LOG_ON_DEBUG`
902* `BT_LOG_ON_INFO`
770538dd 903* `BT_LOG_ON_WARNING`
beb0fb75
PP
904* `BT_LOG_ON_ERROR`
905* `BT_LOG_ON_FATAL`
906
cd4aac1e
PP
907Those macros check the module-specific log level symbol (defined by
908`BT_LOG_OUTPUT_LEVEL`).
beb0fb75
PP
909
910Never, ever write code which would be executed only to compute the
911fields of a logging statement outside a conditional logging scope,
912for example:
913
914[source,c]
915----
916int number = get_number_of_event_classes_with_property_x(...);
917BT_LOGD("Bla bla: number=%d", number);
918----
919
920Do this instead:
921
922[source,c]
923----
924if (BT_LOG_ON_DEBUG) {
925 int number = get_number_of_event_classes_with_property_x(...);
926 BT_LOGD("Bla bla: number=%d", number);
927}
928----
929
930Or even this:
931
932[source,c]
933----
934BT_LOGD("Bla bla: number=%d", get_number_of_event_classes_with_property_x(...));
935----
936
cd4aac1e 937=== Guides
beb0fb75 938
cd4aac1e 939[[logging-instrument-c-file-gen]]
fb7ff115 940==== Instrument a {c-cpp} source file (generic)
beb0fb75 941
fb7ff115 942To instrument a {c-cpp} source file (`.c`/`.cpp`):
cd4aac1e
PP
943
944. At the top of the file, before the first `#include` line (if any),
945 define your file's <<choose-a-logging-tag,logging tag>> name:
4a41523d
PP
946+
947--
948[source,c]
949----
cd4aac1e 950#define BT_LOG_TAG "SUBSYS/MY-MODULE/MY-FILE"
4a41523d
PP
951----
952--
cd4aac1e
PP
953
954. Below the line above, define the source file's log level expression,
955 `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
956 <<gen-logging-statements,logging statement>> to know the current
957 <<run-time-log-level,run-time log level>>.
958+
959Examples:
960+
961[source,c]
962----
963/* Global log level variable */
964#define BT_LOG_OUTPUT_LEVEL module_global_log_level
965----
4a41523d 966+
cd4aac1e
PP
967[source,c]
968----
969/* Local log level variable; must exist where you use BT_LOG*() */
970#define BT_LOG_OUTPUT_LEVEL log_level
971----
972+
973[source,c]
974----
975/* Object's log level; `obj` must exist where you use BT_LOG*() */
976#define BT_LOG_OUTPUT_LEVEL (obj->log_level)
977----
4a41523d 978
cd4aac1e 979. Include `"logging/log.h"`:
4a41523d 980+
beb0fb75
PP
981[source,c]
982----
578e048b 983#include "logging/log.h"
cd4aac1e 984----
4a41523d 985
cd4aac1e
PP
986. In the file, instrument your code with the
987 <<gen-logging-statements,generic logging statement macros>>.
4a41523d 988
cd4aac1e 989[[logging-instrument-h-file-gen]]
fb7ff115 990==== Instrument a {c-cpp} header file (generic)
cd4aac1e 991
fb7ff115
PP
992To instrument a {c-cpp} header file (`.h`/`.hpp`), if you have
993`static inline` functions in it:
cd4aac1e
PP
994
995. Do not include `"logging/log.h"`!
996
997. Do one of:
998
999.. In the file, instrument your code with the
1000 <<gen-logging-statements,generic logging statement macros>>, making
1001 each of them conditional to the existence of the macro you're using:
4a41523d 1002+
cd4aac1e
PP
1003[source,c]
1004----
1005static inline
1006int some_function(int x)
1007{
1008 /* ... */
4a41523d 1009
ef267d12
PP
1010#ifdef BT_LOGT
1011 BT_LOGT(...);
cd4aac1e 1012#endif
beb0fb75 1013
cd4aac1e 1014 /* ... */
6470c171 1015
cd4aac1e
PP
1016#ifdef BT_LOGW_STR
1017 BT_LOGW_STR(...);
1018#endif
f9ded0e0 1019
cd4aac1e
PP
1020 /* ... */
1021}
1022----
1023+
fb7ff115
PP
1024The {c-cpp} source files which include this header file determine if
1025logging is enabled or not for them, and if so, what is their
cd4aac1e
PP
1026<<choose-a-logging-tag,logging tag>> and <<run-time-log-level,run-time
1027log level>> expression.
f9ded0e0 1028
cd4aac1e
PP
1029.. Require that logging be enabled:
1030+
1031[source,c]
1032----
1033/* Protection: this file uses BT_LOG*() macros directly */
1034#ifndef BT_LOG_SUPPORTED
1035# error Please include "logging/log.h" before including this file.
1036#endif
1037----
1038+
1039Then, in the file, instrument your code with the
1040<<gen-logging-statements,generic logging statement macros>>.
1041
cd4aac1e 1042[[logging-instrument-c-file-lib]]
fb7ff115 1043==== Instrument a library {c-cpp} source file
cd4aac1e 1044
fb7ff115 1045To instrument a library {c-cpp} source file (`.c`/`.cpp`):
4a41523d
PP
1046
1047. At the top of the file, before the first `#include` line (if any),
cd4aac1e
PP
1048 define your file's <<choose-a-logging-tag,logging tag>> name (this
1049 tag must start with `LIB/`):
4a41523d
PP
1050+
1051--
1052[source,c]
1053----
cd4aac1e 1054#define BT_LOG_TAG "LIB/THE-FILE"
4a41523d
PP
1055----
1056--
cd4aac1e
PP
1057
1058. Include `"lib/logging.h"`:
4a41523d 1059+
cd4aac1e
PP
1060[source,c]
1061----
1062#include "lib/logging.h"
1063----
4a41523d 1064
cd4aac1e
PP
1065. In the file, instrument your code with the
1066 <<lib-logging-statements,library logging statement macros>> or with
1067 the <<gen-logging-statements,generic logging statement macros>>.
4a41523d 1068
cd4aac1e 1069[[logging-instrument-h-file-lib]]
fb7ff115 1070==== Instrument a library {c-cpp} header file
cd4aac1e 1071
fb7ff115
PP
1072To instrument a library {c-cpp} header file (`.h`/`.hpp`), if you have
1073`static inline` functions in it:
cd4aac1e
PP
1074
1075. Do not include `"lib/logging.h"`!
1076
1077. Require that library logging be enabled:
1078+
1079[source,c]
1080----
1081/* Protection: this file uses BT_LIB_LOG*() macros directly */
1082#ifndef BT_LIB_LOG_SUPPORTED
1083# error Please include "lib/logging.h" before including this file.
1084#endif
1085----
1086
1087. In the file, instrument your code with the
1088 <<lib-logging-statements,library logging statement macros>> or with
1089 the <<gen-logging-statements,generic logging statement macros>>.
f9ded0e0 1090
cd4aac1e 1091[[logging-instrument-c-file-compcls]]
fb7ff115 1092==== Instrument a component class {c-cpp} source file
cd4aac1e 1093
fb7ff115 1094To instrument a component class {c-cpp} source file (`.c`/`.cpp`):
cd4aac1e
PP
1095
1096. At the top of the file, before the first `#include` line (if any),
1097 define your file's <<choose-a-logging-tag,logging tag>> name (this tag
1098 must start with `PLUGIN/` followed by the component class identifier):
4a41523d
PP
1099+
1100--
1101[source,c]
1102----
cd4aac1e
PP
1103#define BT_LOG_TAG "PLUGIN/SRC.MY-PLUGIN.MY-SRC"
1104----
1105--
4a41523d 1106
cd4aac1e
PP
1107. Below the line above, define the source file's log level expression,
1108 `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
1109 <<comp-logging-statements,logging statement>> to know the current
1110 <<run-time-log-level,run-time log level>>.
1111+
1112For a component class file, it is usually a member of a local component
1113private structure variable:
1114+
1115[source,c]
1116----
1117#define BT_LOG_OUTPUT_LEVEL (my_comp->log_level)
1118----
4a41523d 1119
cd4aac1e
PP
1120. Below the line above, define `BT_COMP_LOG_SELF_COMP` to an expression
1121 which, evaluated in the context of the
1122 <<comp-logging-statements,logging statements>>, evaluates to the self
1123 component address (`+bt_self_component *+`) of the component.
1124+
1125This is usually a member of a local component private structure
1126variable:
1127+
1128[source,c]
1129----
1130#define BT_COMP_LOG_SELF_COMP (my_comp->self_comp)
1131----
1132
d9c39b0a 1133. Include `"logging/comp-logging.h"`:
cd4aac1e
PP
1134+
1135[source,c]
1136----
d9c39b0a 1137#include "logging/comp-logging.h"
cd4aac1e
PP
1138----
1139
1140. In the component initialization method, make sure to set the
1141 component private structure's log level member to the initial
1142 component's log level:
1143+
1144[source,c]
1145----
1146struct my_comp {
1147 bt_logging_level log_level;
4a41523d 1148 /* ... */
cd4aac1e 1149};
4a41523d 1150
cd4aac1e
PP
1151bt_self_component_status my_comp_init(
1152 bt_self_component_source *self_comp_src,
1153 bt_value *params, void *init_method_data)
1154{
1155 struct my_comp *my_comp = g_new0(struct my_comp, 1);
1156 bt_self_component *self_comp =
1157 bt_self_component_source_as_self_component(self_comp_src);
1158 const bt_component *comp = bt_self_component_as_component(self_comp);
1159
1160 BT_ASSERT(my_comp);
1161 my_comp->log_level = bt_component_get_logging_level(comp);
4a41523d
PP
1162
1163 /* ... */
1164}
1165----
cd4aac1e
PP
1166
1167. In the file, instrument your code with the
1168 <<comp-logging-statements,component logging statement macros>>.
1169
cd4aac1e 1170[[logging-instrument-h-file-compcls]]
fb7ff115 1171==== Instrument a component class {c-cpp} header file
cd4aac1e 1172
fb7ff115
PP
1173To instrument a component class {c-cpp} header file (`.h`/`.hpp`), if
1174you have `static inline` functions in it:
cd4aac1e 1175
d9c39b0a 1176. Do not include `"logging/comp-logging.h"`!
cd4aac1e
PP
1177
1178. Require that component logging be enabled:
4a41523d 1179+
cd4aac1e
PP
1180[source,c]
1181----
1182/* Protection: this file uses BT_COMP_LOG*() macros directly */
1183#ifndef BT_COMP_LOG_SUPPORTED
d9c39b0a 1184# error Please include "logging/comp-logging.h" before including this file.
cd4aac1e
PP
1185#endif
1186----
1187
1188. In the file, instrument your code with the
1189 <<comp-logging-statements,component logging statement macros>>.
1190
cd4aac1e
PP
1191[[choose-a-logging-tag]]
1192==== Choose a logging tag
beb0fb75 1193
fb7ff115
PP
1194Each logging-enabled {c-cpp} source file must define `BT_LOG_TAG` to a
1195logging tag. A logging tag is a namespace to identify the logging
1196messages of this specific source file.
beb0fb75 1197
cd4aac1e
PP
1198In general, a logging tag name _must_ be only uppercase letters, digits,
1199and the `-`, `.`, and `/` characters.
beb0fb75 1200
cd4aac1e
PP
1201Use `/` to show the subsystem to source file hierarchy.
1202
28b765ac 1203For the {bt2} library, start with `LIB/`.
cd4aac1e
PP
1204
1205For the CTF writer library, start with `CTF-WRITER/`.
1206
1207For component classes, use:
beb0fb75 1208
93841983 1209[verse]
cd4aac1e
PP
1210`PLUGIN/__CCTYPE__.__PNAME__.__CCNAME__[/__FILE__]`
1211
1212With:
1213
1214`__CCTYPE__`::
1215 Component class's type (`SRC`, `FLT`, or `SINK`).
beb0fb75 1216
cd4aac1e 1217`__PNAME__`::
93841983 1218 Plugin's name.
beb0fb75 1219
cd4aac1e 1220`__CCNAME__`::
93841983 1221 Component class's name.
beb0fb75 1222
cd4aac1e 1223`__FILE__`::
93841983 1224 Additional information to specify the source file name or module.
beb0fb75 1225
cd4aac1e 1226For plugins (files common to many component classes), use:
beb0fb75 1227
cd4aac1e
PP
1228[verse]
1229`PLUGIN/__PNAME__[/__FILE__]`
beb0fb75 1230
cd4aac1e 1231With:
beb0fb75 1232
cd4aac1e
PP
1233`__PNAME__`::
1234 Plugin's name.
1235
1236`__FILE__`::
1237 Additional information to specify the source file name or module.
1238
cd4aac1e
PP
1239[[choose-a-log-level]]
1240==== Choose a log level
beb0fb75
PP
1241
1242Choosing the appropriate level for your logging statement is very
1243important.
1244
cd4aac1e 1245[options="header,autowidth",cols="1,2,3a,4"]
beb0fb75 1246|===
cd4aac1e 1247|Log level |Description |Use cases |Expected impact on performance
beb0fb75
PP
1248
1249|_FATAL_
cd4aac1e
PP
1250|
1251The program, library, or plugin cannot continue to work in this
beb0fb75
PP
1252condition: it must be terminated immediately.
1253
b4b9064d 1254A _FATAL_-level logging statement should always be followed by
4a41523d 1255`abort()`.
beb0fb75
PP
1256|
1257* Unexpected return values from system calls.
4a41523d
PP
1258* Logic error in internal code, for example an unexpected value in a
1259 `switch` statement.
cd4aac1e 1260* Failed assertion (within `BT_ASSERT()`).
bdb288b3
PP
1261* Unsatisfied library precondition (within `BT_ASSERT_PRE()` or
1262 `BT_ASSERT_PRE_DEV()`).
1263* Unsatisfied library postcondition (within `BT_ASSERT_POST()` or
1264 `BT_ASSERT_POST_DEV()`).
dd22a91f 1265|Almost none: always enabled.
beb0fb75
PP
1266
1267|_ERROR_
cd4aac1e
PP
1268|
1269An important error which is somewhat not fatal, that is, the program,
beb0fb75
PP
1270library, or plugin can continue to work after this, but you judge that
1271it should be reported to the user.
1272
1273Usually, the program cannot recover from such an error, but it can at
1274least exit cleanly.
1275|
1276* Memory allocation errors.
cd4aac1e
PP
1277* Wrong component initialization parameters.
1278* Corrupted, unrecoverable trace data.
beb0fb75
PP
1279* Failed to perform an operation which should work considering the
1280 implementation and the satisfied preconditions. For example, the
1281 failure to create an empty object (no parameters): most probably
1282 failed internally because of an allocation error.
93841983 1283* Almost any error in terminal elements: CLI and plugins.
dd22a91f 1284|Almost none: always enabled.
beb0fb75 1285
770538dd 1286|_WARNING_
cd4aac1e
PP
1287|
1288An error which still allows the execution to continue, but you judge
1289that it should be reported to the user.
6c1b33a8 1290
770538dd
PP
1291_WARNING_-level logging statements are for any error or weird action
1292that is directly or indirectly caused by the user, often through some
1293bad input data. For example, not having enough memory is considered
1294beyond the user's control, so we always log memory errors with an
1295_ERROR_ level (not _FATAL_ because we usually don't abort in this
1296condition).
beb0fb75 1297|
cd4aac1e
PP
1298* Missing data within something that is expected to have it, but there's
1299 an alternative.
1300* Invalid file, but recoverable/fixable.
dd22a91f 1301|Almost none: always enabled.
beb0fb75
PP
1302
1303|_INFO_
beb0fb75 1304|
cd4aac1e
PP
1305Any useful information which a non-developer user would possibly
1306understand.
1307
1308Anything logged with this level must _not_ happen repetitively on the
1309fast path, that is, nothing related to each message, for example. This
1310level is used for sporadic and one-shot events.
1311|
1312* CLI or component configuration report.
1313* Successful plugin, component, or message iterator initialization.
1314* In the library: anything related to plugins, graphs, component
1315 classes, components, message iterators, connections, and ports which
1316 is not on the fast path.
beb0fb75 1317* Successful connection to or disconnection from another system.
4a41523d 1318* An _optional_ subsystem cannot be loaded.
cd4aac1e
PP
1319* An _optional_ field/datum cannot be found.
1320|
dd22a91f 1321Very little: always enabled.
beb0fb75
PP
1322
1323|_DEBUG_
beb0fb75 1324|
28b765ac 1325Something that only {bt2} developers would be interested into,
cd4aac1e
PP
1326which can occur on the fast path, but not more often than once per
1327message.
1328
1329The _DEBUG_ level is the default <<build-time-log-level,build-time log
1330level>> as, since it's not _too_ verbose, the performance is similar to
1331an _INFO_ build.
1332|
1333* Object construction and destruction.
1334* Object recycling (except fields).
1335* Object copying (except fields and values).
1336* Object freezing (whatever the type, as freezing only occurs in
1337 developer mode).
9b4f9b42 1338* Object interruption.
cd4aac1e
PP
1339* Calling user methods and logging the result.
1340* Setting object properties (except fields and values).
1341|
ef267d12 1342Noticeable, but not as much as the _TRACE_ level: could be executed
cd4aac1e
PP
1343in production if you're going to need a thorough log for support
1344tickets without having to rebuild the project.
beb0fb75 1345
ef267d12 1346|_TRACE_
cd4aac1e
PP
1347|
1348Low-level debugging context information (anything that does not fit the
1349other log levels). More appropriate for tracing in general.
beb0fb75
PP
1350|
1351* Reference count change.
cd4aac1e 1352* Fast path, low level state machine's state change.
beb0fb75
PP
1353* Get or set an object's property.
1354* Object comparison's intermediate results.
1355|Huge: not executed in production.
1356|===
1357
cd4aac1e
PP
1358[IMPORTANT]
1359--
770538dd 1360Make sure not to use a _WARNING_ (or higher) log level when the
cd4aac1e
PP
1361condition leading to the logging statement can occur under normal
1362circumstances.
1363
1364For example, a public function to get some object or
1365property from an object by name or key that fails to find the value is
1366not a warning scenario: the user could legitimately use this function to
1367check if the name/key exists in the object. In this case, use the
ef267d12 1368_TRACE_ level (or do not log at all).
cd4aac1e 1369--
b4b9064d 1370
b4b9064d 1371[[message]]
cd4aac1e 1372==== Write an appropriate message
beb0fb75
PP
1373
1374Follow those rules when you write a logging statement's message:
1375
cd4aac1e
PP
1376* Use an English sentence which starts with a capital letter.
1377
1378* Start the sentence with the appropriate verb tense depending on the
1379 context. For example:
beb0fb75
PP
1380+
1381--
b4b9064d
PP
1382** Beginning of operation (present continuous): _Creating ..._,
1383 _Copying ..._, _Serializing ..._, _Freezing ..._, _Destroying ..._
1384** End of operation (simple past): _Created ..._, _Successfully created ..._,
1385 _Failed to create ..._, _Set ..._ (simple past of _to set_ which is
1386 also _set_)
beb0fb75
PP
1387--
1388+
1389For warning and error messages, you can start the message with _Cannot_
b4b9064d 1390or _Failed to_ followed by a verb if it's appropriate.
beb0fb75
PP
1391
1392* Do not include the log level in the message itself. For example,
1393 do not start the message with _Error while_ or _Warning:_.
1394
cd4aac1e
PP
1395* Do not put newlines, tabs, or other special characters in the message,
1396 unless you want to log a string with such characters. Note that
1397 multiline logging messages can be hard to parse, analyze, and filter,
1398 however, so prefer multiple logging statements over a single statement
1399 with newlines.
beb0fb75
PP
1400
1401* **If there are fields that your logging statement must record**,
1402 follow the message with `:` followed by a space, then with the list of
1403 fields (more about this below). If there are no fields, end the
1404 sentence with a period.
1405
1406The statement's fields _must_ be a comma-separated list of
cd4aac1e
PP
1407`__name__=__value__` tokens. Keep `__name__` as simple as possible; use
1408kebab case if possible. If `__value__` is a non-alphanumeric string, put
1409it between double quotes (`"%s"` specifier). Always use the `PRId64` and
1410`PRIu64` specifiers to log an `int64_t` or an `uint64_t` value. Use `%d`
1411to log a boolean value.
beb0fb75
PP
1412
1413Example:
1414
cd4aac1e
PP
1415 "Cannot read stream data for indexing: path=\"%s\", name=\"%s\", "
1416 "stream-id=%" PRIu64 ", stream-fd=%d, "
1417 "index=%" PRIu64 ", status=%s, is-mapped=%d"
beb0fb75 1418
cd4aac1e
PP
1419By following a standard format for the statement fields, it is easier to
1420use tools like https://www.elastic.co/products/logstash[Logstash] or
1421even https://www.splunk.com/[Splunk] to split fields and analyze logs.
beb0fb75
PP
1422
1423Prefer the following suffixes in field names:
1424
1425[options="header,autowidth"]
1426|===
1427|Field name suffix |Description |Format specifier
1428
1429|`-addr` |Memory address |`%p`
1430|`-fd` |File descriptor |`%d`
cd4aac1e
PP
1431|`-fp` |File stream (`+FILE *+`) |`%p`
1432|`-id` |Object's ID |`%" PRIu64 "`
1433|`-index` |Index |`%" PRIu64 "`
beb0fb75 1434|`-name` |Object's name |`\"%s\"`
beb0fb75
PP
1435|===
1436
f9ded0e0 1437=== Output
beb0fb75
PP
1438
1439The log is printed to the standard error stream. A log line contains the
cd4aac1e
PP
1440time, the process and thread IDs, the <<log-levels,log level>>, the
1441<<choose-a-logging-tag,logging tag>>, the source's function name, file
1442name and line number, and the <<message,message>>.
beb0fb75 1443
28b765ac 1444When {bt2} supports terminal color codes (depends on the
f9ded0e0
PP
1445`BABELTRACE_TERM_COLOR` environment variable's value and what the
1446standard output and error streams are plugged into), _INFO_-level lines
770538dd 1447are blue, _WARNING_-level lines are yellow, and _ERROR_-level and
f9ded0e0
PP
1448_FATAL_-level lines are red.
1449
1450Log line example:
beb0fb75 1451
cd4aac1e
PP
1452----
145305-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
1454----
beb0fb75 1455
cd4aac1e
PP
1456You can easily filter the log with `grep` or `ag`. For example, to keep
1457only the _DEBUG_-level logging messages that the `FIELD-CLASS` module
beb0fb75
PP
1458generates:
1459
cd4aac1e
PP
1460----
1461$ babeltrace2 --log-level=D /path/to/trace |& ag 'D FIELD-CLASS'
1462----
1463
cd4aac1e
PP
1464== Valgrind
1465
1466To use Valgrind on an application (for example, the CLI or a test) which
1467loads libbabeltrace2, use:
1468
1469----
1470$ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \
916d0d91 1471 LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full app
cd4aac1e
PP
1472----
1473
1474`G_SLICE=always-malloc` and `G_DEBUG=gc-friendly` is for GLib and
1475`PYTHONMALLOC=malloc` is for the Python interpreter, if it is used by
1476the Python plugin provider (Valgrind will probably show a lot of errors
1477which originate from the Python interpreter anyway).
1478
16b7b5e7 1479`LIBBABELTRACE2_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared
cd4aac1e
PP
1480libraries (plugins) which it loads. You need this to see the appropriate
1481backtrace when Valgrind shows errors.
c637d729
FD
1482
1483== Testing
1484
800400d8
PP
1485[[test-env]]
1486=== Environment
c637d729 1487
8aed890c
SM
1488Running `make check` in the build directory (regardless of whether the build is
1489in-tree or out-of-tree) automatically sets up the appropriate environment for
1490tests to run in, so nothing more is needed.
1491
1492If building in-tree, you can run single tests from the tree directly:
1493
1494----
7132b838 1495$ ./tests/plugins/sink.text.pretty/test-enum.sh
8aed890c
SM
1496----
1497
1498If building out-of-tree, you can get the appropriate environment by sourcing
1499the `tests/utils/env.sh` file residing in the build directory against which you
1500want to run tests.
1501
1502----
1503$ source /path/to/my/build/tests/utils/env.sh
7132b838 1504$ ./tests/plugins/sink.text.pretty/test-enum.sh
800400d8
PP
1505----
1506
1507==== Python
1508
31d2049b
PP
1509You can use the `tests/utils/run-in-py-env.sh` script to run any command
1510within an environment making the build's `bt2` Python package available,
1511as well as the testing utility Python modules.
800400d8 1512
31d2049b 1513`run-in-py-env.sh` uses <<test-env,`utils.sh`>> which needs to know the
800400d8
PP
1514build directory, so make sure you set the `BT_TESTS_BUILDDIR`
1515environment variable correctly _if you build out of tree_, for example:
1516
1517----
1518$ export BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests
1519----
1520
1521You can run any command which needs the `bt2` Python package through
31d2049b 1522`run-in-py-env.sh`, for example:
c637d729
FD
1523
1524----
31d2049b 1525$ ./tests/utils/run-in-py-env.sh ipython3
c637d729
FD
1526----
1527
800400d8
PP
1528=== Report format
1529
1530All test scripts output the test results following the
1531https://testanything.org/[Test Anything Protocol] (TAP) format.
1532
1533The TAP format has two mechanisms to print additional information about
1534a test:
1535
1536* Print a line starting with `#` to the standard output.
1537+
1538This is usually done with the `diag()` C function or the `diag` shell
1539function.
1540
1541* Print to the standard error.
1542
800400d8
PP
1543=== Python bindings
1544
1545The `bt2` Python package tests are located in
1546`tests/bindings/python/bt2`.
1547
800400d8
PP
1548==== Python test runner
1549
28b765ac 1550`tests/utils/python/testrunner.py` is {bt2}'s Python test runner
800400d8
PP
1551which loads Python files containing unit tests, finds all the test
1552cases, and runs the tests, producing a TAP report.
1553
1554You can see the test runner command's help with:
c637d729
FD
1555
1556----
800400d8 1557$ python3 ./tests/utils/python/testrunner.py --help
c637d729
FD
1558----
1559
800400d8
PP
1560By default, the test runner reports failing tests (TAP's `not{nbsp}ok`
1561line), but continues to run other tests. You can use the `--failfast`
1562option to make the test runner fail as soon as a test fails.
c637d729 1563
800400d8
PP
1564==== Guides
1565
1566To run all the `bt2` Python package tests:
1567
1568* Run:
1569+
1570----
31d2049b 1571$ ./tests/utils/run-in-py-env.sh ./tests/bindings/python/bt2/test-python-bt2.sh
800400d8
PP
1572----
1573+
1574or:
1575+
1576----
31d2049b 1577$ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \
800400d8
PP
1578 ./tests/bindings/python/bt2/ -p '*.py'
1579----
1580
1581To run **all the tests** in a test module (for example,
1582`test_value.py`):
1583
1584* Run:
1585+
1586----
31d2049b 1587$ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \
800400d8
PP
1588 ./tests/bindings/python/bt2 -t test_value
1589----
1590
1591To run a **specific test case** (for example, `RealValueTestCase` within
1592`test_value.py`):
1593
1594* Run:
1595+
1596----
31d2049b 1597$ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \
800400d8
PP
1598 ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase
1599----
1600
1601To run a **specific test** (for example,
1602`RealValueTestCase.test_assign_pos_int` within `test_value.py`):
1603
1604* Run:
1605+
c637d729 1606----
31d2049b 1607$ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \
800400d8 1608 ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int
c637d729 1609----
fb7ff115
PP
1610
1611== {cpp} usage
1612
a1ac73cf
PP
1613A significant part and, in general, all the new code of {bt2} is written
1614in {cpp}.
fb7ff115
PP
1615
1616This section shows what's important to know about {cpp} to contribute
1617to {bt2}.
1618
1619[IMPORTANT]
1620====
1621{bt2} only has {cpp} sources for _internal_ code.
1622
1623In other words, libbabeltrace2 _must_ expose a pure C99 API to preserve
1624ABI compatibility over time.
1625====
1626
a1ac73cf 1627=== Standard
fb7ff115
PP
1628
1629The {bt2} project is configured to use the {cpp11} standard.
1630
1631{cpp11} makes it possible to build {bt2} with a broad range of
1632compilers, from GCC{nbsp}4.8 and Clang{nbsp}3.3.
1633
a1ac73cf
PP
1634=== Common {cpp} code
1635
1636Many parts of the project need common {cpp} code. You'll find all of it
1637under `src/cpp-common`.
1638
1639In general, anything under a namespace named `internal` is internal to
1640the API containing it. For example, everything under the `bt2::internal`
1641namespace is internal to the `bt2` namespace and therefore isn't meant
1642to be used outside the `src/cpp-common/bt2` directory.
1643
1644==== `bt2`: libbabeltrace2 {cpp} bindings
1645
1646`src/cpp-common/bt2` contains our internal {cpp} bindings of
1647the libbabeltrace2 C{nbsp}API, under the `bt2` namespace.
1648
1649Those bindings are designed to have, as much as possible, no performance
1650impact. Anything which inherits `bt2::BorrowedObject` contains a single
1651libbabeltrace2 object pointer.
1652
1653Pass and return borrowed objects _by value_ (copy).
1654
1655In general, the following holds:
1656
1657[options="header,autowidth",cols="2"]
1658|===
1659|{cpp} expression
1660|Equivalent C{nbsp}expression
1661
1662|`bt2::Xyz`
1663|`bt_xyz *`
1664
1665|`const bt2::Xyz`
1666|`bt_xyz * const`
1667
1668|`bt2::ConstXyz`
1669|`const bt_xyz *`
1670
1671|`const bt2::ConstXyz`
1672|`const bt_xyz * const`
1673|===
1674
1675==== `bt2c`: general common {cpp} code
1676
1677Similar to the role of `src/common` for C code.
1678
1679In general, everything in here is under the `bt2c` namespace.
1680
1681Notable files are:
1682
1683`align.hpp`::
1684 The `bt2c::align()` function template: a wrapper of
1685 `src/common/align.h`.
1686
1687`c-string-view.hpp`::
1688 The `bt2c::CStringView` class: a view on a constant null-terminated
1689 C{nbsp}string.
1690+
1691We have this because `bt2s::string_view` doesn't imply null termination,
1692only a beginning and a length.
1693+
1694A `bt2c::CStringView` instance is convertible to `const char *` and may
1695be empty (the underlying pointer is null).
1696
1697`call.hpp`::
1698 The `bt2c::call()` function template: a partial implementation of
1699 https://en.cppreference.com/w/cpp/utility/functional[INVOKE].
1700+
1701We use this mostly to assign the result of calling an immediately
1702invoked function expression (lambda) to an `auto` variable without
1703risking to assign the lambda itself, should we forget the calling
1704parentheses:
1705+
1706[source,cpp]
1707----
1708const auto res = bt2c::call([&] {
1709 /* Complex initialization */
1710});
1711----
1712
1713`endian.hpp`::
1714 Typed wrappers of `src/compat/endian.h`.
1715
1716`exc.hpp`::
1717 Common exception classes.
1718
1719`fmt.hpp`::
1720 Common https://fmt.dev/[{fmt}] formatters.
1721
1722`logging.hpp`::
1723 The `bt2c::Logger` class and helper `BT_CPPLOG*()` macros for any
1724 {cpp} logging.
1725+
1726When possible, prefer using this over the C{nbsp}logging API.
1727+
1728One important benefit is that this API uses {fmt} to format the logging
1729message instead of `vsnprintf()`.
1730
1731`prio-heap.hpp`::
1732 The `bt2c::PrioHeap` class template: an efficient heap data
1733 structure.
1734
1735`read-fixed-len-int.hpp`::
1736 The function templates `bt2c::readFixedLenInt()`,
1737 `bt2c::readFixedLenIntLe()`, and `bt2c::readFixedLenIntBe()`: read a
1738 fixed-length integer from a byte buffer.
1739
1740`safe-ops.hpp`::
1741 The `bt2c::safe*()` function templates: arithmetic operations which
1742 assert that there's no possible overflow.
1743
1744`std-int.hpp`::
1745 The `bt2c::StdIntT` type alias template: becomes one of the
1746 `std::*int*_t` types depending on its parameters.
1747+
1748For example, `bt2c::StdIntT<32, true>` is `std::int32_t`.
1749
1750`type-traits.hpp`::
1751 Common type traits.
1752
1753`uuid.hpp`::
1754 The following classes:
1755
1756`bt2c::Uuid`:::
1757 Container of a 16-byte
1758 https://en.wikipedia.org/wiki/Universally_unique_identifier[UUID].
1759+
1760Provides the static `generate()` method as well as conversion to
1761`bt2c::UuidView`.
1762
1763`bt2c::UuidView`:::
1764 View on a UUID (not a container).
1765+
1766Provides byte access, comparison, as well as string conversion methods.
1767+
1768Also provides conversion to `bt2c::Uuid`.
1769
1770`vector.hpp`::
1771 The `bt2c::vectorFastRemove()` function template: remove an element
1772 from an `std::vector` instance quickly when the order isn't
1773 important.
1774
1775==== `bt2s`: drop-in replacements of {cpp}14 to {cpp}20 STL features
1776
1777Everything under the `bt2s` namespace has its equivalent under the `std`
1778namespace, but in {cpp} versions we don't yet have access to, namely:
1779
1780`make_unique.hpp`::
1781 `bt2s::make_unique()`, a drop-in replacement of `std::make_unique()`
1782 ({cpp}14).
1783
1784`optional.hpp`::
1785 Drop-in replacement of the `std::optional` API ({cpp}17).
1786
1787`span.hpp`::
1788 Drop-in replacement of the `std::span` API ({cpp}20).
1789
1790`string-view.hpp`::
1791 Drop-in replacement of the `std::string_view` API ({cpp}17).
1792
1793==== `vendor`: copies of {cpp} dependencies
1794
1795This directory contains copies of the source code of {cpp} dependencies
1796to avoid packaging issues.
1797
1798They are:
1799
1800`fmt`::
1801 https://fmt.dev/[{fmt}].
1802
1803`nlohmann`::
1804 https://json.nlohmann.me/[JSON for Modern C++].
1805
1806`optional-lite`::
1807 https://github.com/martinmoene/optional-lite[optional lite].
1808+
1809IMPORTANT: Use the symbols of `src/cpp-common/bt2s/optional.hpp`, under
1810the `bt2s` namespace, instead of using this directly.
1811
1812`span-lite`::
1813 https://github.com/martinmoene/span-lite[span lite].
1814+
1815IMPORTANT: Use the symbols of `src/cpp-common/bt2s/span.hpp`, under the
1816`bt2s` namespace, instead of using this directly.
1817
a19a1879
MJ
1818`string-view-lite`::
1819 https://github.com/martinmoene/string-view-lite[string_view lite].
a1ac73cf
PP
1820+
1821IMPORTANT: Use the symbols of `src/cpp-common/bt2s/string-view.hpp`,
1822under the `bt2s` namespace, instead of using this directly.
1823
fb7ff115
PP
1824=== Automake/Libtool requirements
1825
1826To add a {cpp} source file to a part of the project, use the `.cpp`
1827extension and add it to the list of source files in `Makefile.am` as
1828usual.
1829
1830If a program or a shared library has a direct {cpp} source file, then
1831Libtool uses the {cpp} linker to create the result, dynamically
1832linking important runtime libraries such as libstdc++ and libgcc_s.
1833
1834Because a Libtool _convenience library_ is just an archive (`.a`), it's
1835_not_ dynamically linked to runtime libraries, even if one of its direct
1836sources is a {cpp} file. This means that for each program or shared
1837library named `my_target` in `Makefile.am` which is linked to a
1838convenience library having {cpp} sources (recursively), you _must_ do
1839one of:
1840
1841* Have at least one direct {cpp} source file in the
1842 `+*_my_target_SOURCES+` list.
1843
1844* Add:
1845+
1846----
1847nodist_EXTRA_my_target_SOURCES = dummy.cpp
1848----
1849+
1850See
1851https://www.gnu.org/software/automake/manual/automake.html#Libtool-Convenience-Libraries[Libtool
1852Convenience Libraries] to learn more.
1853
1854For a given program or library, you _cannot_ have a C{nbsp}file and a
1855{cpp}{nbsp}file having the same name, for example `list.c` and
1856`list.cpp`.
1857
1858=== Coding style
1859
1860==== Whitespaces, indentation, and line breaks
1861
1862All the project's {cpp} files follow the
1863https://clang.llvm.org/docs/ClangFormat.html[clang-format]
1864https://clang.llvm.org/docs/ClangFormatStyleOptions.html[style] of the
1865`.clang-format` file for whitespaces, indentation, and line breaks.
1866
1867You _must_ format modified and new {cpp} files with clang-format before
1868you create a contribution patch.
1869
1d323849 1870You need clang-format{nbsp}15 to use the project's `.clang-format` file.
fb7ff115
PP
1871
1872To automatically format all the project's {cpp} files, run:
1873
1874----
ac4d5cf0 1875$ ./tools/format-cpp.sh
b61d5465
PP
1876----
1877
a1ac73cf 1878To only format the {cpp} files of a given directory:
3e674024
PP
1879
1880----
ac4d5cf0 1881$ ./tools/format-cpp.sh ./src/cli
3e674024
PP
1882----
1883
b61d5465
PP
1884Use the `FORMATTER` environment variable to override the default
1885formatter (`clang-format{nbsp}-i`):
1886
1887----
ac4d5cf0 1888$ FORMATTER='my-clang-format-15 -i' ./tools/format-cpp.sh
fb7ff115
PP
1889----
1890
1891==== Naming
1892
1893* Use camel case with a lowercase first letter for:
1894** Variable names: `size`, `objSize`.
1895** Function/method names: `size()`, `formatAndPrint()`.
1896
1897* Use camel case with an uppercase first letter for:
1898** Types: `Pistachio`, `NutManager`.
1899** Template parameters: `PlanetT`, `TotalSize`.
1900
1901* Use snake case with uppercase letters for:
1902** Definition/macro names: `MARK_AS_UNUSED()`, `SOME_FEATURE_EXISTS`.
1903** Enumerators: `Type::SIGNED_INT`, `Scope::FUNCTION`.
1904
1905* Use only lowercase letters and digits for namespaces: `mylib`, `bt2`.
1906
a1ac73cf
PP
1907* Use the `T` suffix for type template parameters and the `V` suffix for
1908 non-type template parameters:
fb7ff115
PP
1909+
1910[source,cpp]
1911----
a1ac73cf 1912template <typename NameT, typename ItemT, unsigned int SizeV = 0>
fb7ff115
PP
1913----
1914
a1ac73cf 1915* Name a template parameter pack `ArgTs`.
fb7ff115
PP
1916+
1917[source,cpp]
1918----
a1ac73cf 1919template <typename NameT, typename... ArgTs>
fb7ff115
PP
1920----
1921
1922* Use an underscore prefix for private and protected methods and member
1923 type names: `_tryConnect()`, `_NodeType`.
1924
1925* Use the prefix `_m` for private and protected member variable names:
1926 `_mLogger`, `_mSize`, `_mFieldClass`.
a1ac73cf
PP
1927+
1928This is to avoid name clashes with private/protected getters/setters.
fb7ff115 1929
a1ac73cf 1930* Name setters and getters like the property name, without the `set` and
fb7ff115
PP
1931 `get` prefixes.
1932
1933* Use the `is` or `has` prefix, if possible, to name the functions which
1934 return `bool`.
a1ac73cf
PP
1935+
1936However, try to keep the name readable. For example, prefer
1937`colorIsBlue()` over `isColorBlue()`.
fb7ff115
PP
1938
1939=== Coding convention
1940
1941In general, the project's contributors make an effort to follow,
1942for {cpp11} code:
1943
1944* The
1945 https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md[{cpp} Core Guidelines].
1946
1947* Scott Meyers's
1948 "`https://www.oreilly.com/library/view/effective-modern-c/9781491908419/[Effective Modern {cpp}]`".
1949
1950Here are a few important reminders:
1951
1952* Namespace your code.
1953
1954* Create one header/source file pair per class when possible.
1955+
1956For a class named `MyClass`, name the corresponding files `my-class.hpp`
1957and `my-class.cpp`.
1958
a1ac73cf
PP
1959* Use the `inline` keyword, not `static inline`, for header-only
1960 functions that are not templates.
1961
1962* When defining a class, use this order:
1963+
1964--
1965. Friends (without any preceding access specifier).
1966
1967. Public types and type aliases.
1968+
1969Private/protected types may be here too if they can't be lower.
1970
1971. Constructors, whatever their access.
1972
1973. Destructor (always public).
1974
1975. Copy-assignment and move-assignment operators.
1976
1977. Public methods.
1978
1979. Protected types and type aliases.
1980
1981. Protected methods.
fb7ff115 1982
a1ac73cf
PP
1983. Private types and type aliases.
1984
1985. Private methods.
1986
1987. Protected data members.
1988
1989. Private data members.
1990--
1991
1992* Declare variables as close to where they're used as possible.
1993
1994* In general, try to avoid variables if it doesn't lead to more lines.
1995+
1996For example, given:
1997+
1998[source,cpp]
1999----
2000const auto size = getSize(myObj, 23);
2001auto& obj = this->_objForSize(size);
2002
2003abc::sendObj(obj, SendOpts::WAIT);
2004----
2005+
2006Prefer this:
2007+
2008[source,cpp]
2009----
2010abc::sendObj(this->_objForSize(getSize(myObj, 23)), SendOpts::WAIT);
2011----
2012
2013* If you really need variables, then scope them to avoid "`leaking`"
2014 them:
2015+
2016[source,cpp]
2017----
2018doSomeStuff(123, &obj);
2019
2020{
2021 const auto status = tryChange(obj);
2022
2023 BT_CPPLOGD("New status: {}.", status);
2024 BT_ASSERT(status == Status::CONTINUE);
2025}
2026
2027doMoreStuff(&obj);
2028----
2029+
2030This also means to either use a dedicated, named method/function or to
2031use `bt2c::call()` with an immediately invoked function expression
2032(lambda) to perform complex initialization of an ideally `const`
2033variable:
2034+
2035[source,cpp]
2036----
2037const auto size = bt2c::call([this] {
2038 auto& sender = this->_curSender();
2039
2040 if (sender.strategy() == Strategy::ACK) {
2041 return sender.strategySize();
2042 } else if (sender.strategy() == Strategy::NACK) {
2043 return 0;
2044 }
2045
2046 return _mDefSize;
2047});
2048----
2049
2050* Always use `bt2c::call()` to call an immediately invoked function
2051 expression (see the previous point).
2052
2053* If possible, initialize object members without a default value with
2054 the initializer list of a constructor, not in the constructor body.
2055+
2056If the initialization is complex, either use a dedicated, named
2057method/function or `bt2c::call()` with an immediately invoked function
2058expression (lambda):
2059+
2060[source,cpp]
2061----
2062MyObj::MyObj(const std::size_t size) :
2063 _mSize {size},
2064 _mOtherObj {bt2c::call([size] {
2065 /* Complex initialization here */
2066 })}
2067{
2068}
2069----
fb7ff115
PP
2070
2071* Use `auto` when possible.
a1ac73cf
PP
2072+
2073Use `auto&` instead of `const auto&` when you know that the type is
2074`const` anyway.
2075+
2076Don't use `auto *`.
fb7ff115 2077
a1ac73cf
PP
2078* Use `const` as much as possible, even for pointers
2079 (`+const char * const+`) and numeric values (`const unsigned int`)
fb7ff115
PP
2080 which never need to change.
2081
a1ac73cf
PP
2082* Prefer the `pass:[MyObj myObj {...}]` initialization form over
2083 `pass:[auto myObj = MyObj {...}]`.
2084
fb7ff115 2085* Implement simple setters, getters, and one-liners in header files and
a1ac73cf
PP
2086 everything else that's not a template in source files, including
2087 constructors.
fb7ff115
PP
2088
2089* Make methods `const noexcept` or `const` as much as possible.
2090
2091* Make constructors `explicit` unless you really need an implicit
a1ac73cf
PP
2092 constructor (which is rare), including default constructors:
2093+
2094[source,cpp]
2095----
2096explicit Meow();
2097----
fb7ff115
PP
2098
2099* Use `std::unique_ptr` to manage memory when possible.
2100+
2101However, use references (`+*my_unique_ptr+`) and raw pointers
2102(`+my_unique_ptr.get()+`) when not transferring ownership.
2103
2104* Use `nullptr`, not `NULL` nor 0.
2105
2106* Return by value (rvalue) instead of by output parameter (non-const
2107 lvalue reference), even complex objects, unless you can prove that the
2108 performance is improved when returning by parameter.
2109
2110* For a function parameter or a return value of which the type needs to
2111 be a reference or pointer, use:
2112+
2113If the value is mandatory:::
2114 A reference.
2115If the value is optional:::
2116 A raw pointer.
2117
2118* Don't use `+std::move()+` when you already have an rvalue, which
2119 means:
2120** Don't write `+return std::move(...);+` as this can interfere with
2121 RVO.
2122** Don't use `+std::move()+` with a function call
2123 (`+std::move(func())+`).
2124
2125* For each possible move/copy constructor or assignment operator, do one
2126 of:
2127** Write a custom one.
2128** Mark it as defaulted (`default`)
2129** Mark it as deleted (`delete`).
2130
2131* Use scoped enumerations (`+enum class+`).
2132
2133* Mark classes known to be final with the `final` keyword.
2134
2135* Use type aliases (`using`), not type definitions (`typedef`).
2136
a1ac73cf
PP
2137* In a `.cpp` file, use anonymous namespaces for local symbols instead
2138 of `static` or `inline`.
2139
2140* Prefer a function in an anonymous namespace in a `.cpp` file over a
2141 private static method if it doesn't need private access to an object.
fb7ff115
PP
2142
2143* Don't pollute the global namespace:
2144** Don't use `using namespace xyz` anywhere.
2145** Use only namespace aliases in source files (`.cpp`), trying to
2146 use them in the smallest possible scope (function, or even smaller).
2147
2148* Return a structure with named members instead of a generic container
2149 such as `std::pair` or `std::tuple`.
2150
2151* When a class inherits a base class with virtual methods, use the
2152 `override` keyword to mark overridden virtual methods, and do not use
2153 the `virtual` keyword again.
2154
2155* Define overloaded operators only if their meaning is obvious,
2156 unsurprising, and consistent with the corresponding built-in
2157 operators.
2158+
2159For example, use `+|+` as a bitwise- or logical-or, not as a shell-style
2160pipe.
2161
2162* Use RAII wrappers when managing system resources or interacting with
2163 C{nbsp}libraries.
2164+
2165In other words, don't rely on ``goto``s and error labels to clean up as
2166you would do in{nbsp}C.
2167+
2168Use the RAII, Luke.
2169
2170* Throw an exception when there's an unexpected, exceptional condition,
2171 https://isocpp.org/wiki/faq/exceptions#ctors-can-throw[including from
2172 a constructor], instead of returning a status code.
2173
2174* Accept a by-value parameter and move it (when it's moveable) when you
2175 intend to copy it anyway.
2176+
2177You can do this with most STL containers.
2178+
2179Example:
2180+
2181[source,cpp]
2182----
2183void Obj::doSomething(std::string str)
2184{
2185 _mName = std::move(str);
a1ac73cf 2186 /* ... */
fb7ff115
PP
2187}
2188----
2189
2190.`baby.hpp`
2191====
2192This example shows a {cpp} header which follows the {bt2} {cpp} coding
2193convention.
2194
2195[source,cpp]
2196----
2197/*
a1ac73cf 2198 * SPDX-FileCopyrightText: 2020 Harry Burnett <hburnett@reese.choco>
fb7ff115 2199 * SPDX-License-Identifier: MIT
fb7ff115
PP
2200 */
2201
2202#ifndef BABELTRACE_BABY_HPP
2203#define BABELTRACE_BABY_HPP
2204
2205#include <string>
2206#include <unordered_set>
2207#include <utility>
2208
2209namespace life {
2210
2211class Toy;
2212
2213/*
2214 * A baby is a little human.
2215 */
2216class Baby : public Human
2217{
a1ac73cf
PP
2218 friend class Parent;
2219
fb7ff115
PP
2220public:
2221 using Toys = std::unordered_set<Toy>;
2222
2223 enum class Gender
2224 {
2225 MALE,
2226 FEMALE,
a1ac73cf 2227 OTHER,
fb7ff115
PP
2228 };
2229
a1ac73cf 2230 explicit Baby() = default;
fb7ff115
PP
2231 explicit Baby(const Toys& toys);
2232 Baby(const Baby&) = delete;
2233 Baby(Baby&&) = delete;
fb7ff115
PP
2234
2235protected:
a1ac73cf 2236 explicit Baby(Gender initialGender = Gender::OTHER);
fb7ff115
PP
2237
2238public:
a1ac73cf
PP
2239 ~Baby();
2240 Baby& operator=(const Baby&) = delete;
2241 Baby& operator=(Baby&&) = delete;
2242
fb7ff115
PP
2243 /*
2244 * Eats `weight` grams of food.
2245 */
2246 void eat(unsigned long weight);
2247
2248 /*
2249 * Sleeps for `duration` seconds.
2250 */
2251 void sleep(double duration);
2252
2253 /*
2254 * Sets this baby's name to `name`.
2255 */
2256 void name(std::string name)
2257 {
2258 _mName = std::move(name);
2259 }
2260
2261 /*
2262 * This baby's name.
2263 */
2264 const std::string& name() const noexcept
2265 {
2266 return _mName;
2267 }
2268
2269protected:
2270 void _addTeeth(unsigned long index);
2271 void _grow(double size) override;
2272
2273private:
2274 std::string _mName {"Paul"};
2275 Toys _mToys;
2276};
2277
a1ac73cf 2278} /* namespace life */
fb7ff115 2279
a1ac73cf 2280#endif /* BABELTRACE_BABY_HPP */
fb7ff115
PP
2281----
2282====
7554731e
SM
2283
2284== Python Usage
2285
2286=== Formatting
2287
2288All Python code must be formatted using the version of
2289https://github.com/psf/black[Black] specified in `dev-requirements.txt`.
5995b304
SM
2290
2291All Python imports must be sorted using the version of
2292https://pycqa.github.io/isort/[isort] indicated in `dev-requirements.txt`.
This page took 0.181135 seconds and 4 git commands to generate.