// Render with Asciidoctor
-= Babeltrace contributor's guide
+= Babeltrace{nbsp}2 contributor's guide
Jérémie Galarneau, Philippe Proulx
-v0.2, 19 June 2019
-:toc:
-:toclevels: 5
-
+1 December 2020
+:toc: left
+:toclevels: 3
+:icons: font
+:nofooter:
+:bt2: Babeltrace{nbsp}2
+:c-cpp: C/{cpp}
+:cpp11: {cpp}11
This is a partial contributor's guide for the
-http://diamon.org/babeltrace[Babeltrace] project. If you have any
+https://babeltrace.org[{bt2}] project. If you have any
questions that are not answered by this guide, please post them on
https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[Babeltrace's
mailing list].
-
-== Babeltrace library
+== {bt2} library
=== Object reference counting and lifetime
-This section covers the rationale behind the design of Babeltrace's
-object lifetime management. This applies to the Babeltrace library, as
+This section covers the rationale behind the design of {bt2}'s
+object lifetime management. This applies to the {bt2} library, as
well as to the CTF writer library (although the public reference
counting functions are not named the same way).
-Starting from Babeltrace 2.0, all publicly exposed objects inherit a
-common base: `bt_object`. This base provides a number of facilities to
+Starting from Babeltrace{nbsp}2.0, all publicly exposed objects inherit
+a common base: `bt_object`. This base provides a number of facilities to
all objects, chief amongst which are lifetime management functions.
The lifetime of some public objects is managed by reference counting. In
functions which respectively increment and decrement an object's
reference count.
-As far as lifetime management in concerned, Babeltrace makes a clear
+As far as lifetime management in concerned, {bt2} makes a clear
distinction between regular objects, which have a single parent, and
root objects, which don't.
-
==== The problem
Let us consider a problematic case to illustrate the need for this
distinction.
-A user of the Babeltrace library creates a trace class, which _has_ a
+A user of the {bt2} library creates a trace class, which _has_ a
stream class (the class of a stream) and that stream class, in turn,
_has_ an event class (the class of an event).
Nonetheless, the API must offer the guarantee that holding a node to any
node of the graph keeps all other reachable nodes alive.
-
==== The solution
-The scheme employed in Babeltrace to break this cycle consists in the
+The scheme employed in {bt2} to break this cycle consists in the
"children" holding _reverse component references_ to their parents. That
is, in the context of the trace IR, that event classes hold a reference
to their parent stream class and stream classes hold a reference to
reference to its parent into a regular reference. That is why this
reference is referred to as a _claiming_ aggregation reference.
-
==== Caveats
This scheme imposes a number of strict rules defining the relation
* Objects, beside the root, are only retrievable from their direct
parent or children.
-
==== Example
The initial situation is rather simple: **User{nbsp}A** is holding a
Logging is a great instrument for a developer to be able to collect
information about a running software.
-Babeltrace is a complex software with many layers. When a Babeltrace
+{bt2} is a complex software with many layers. When a {bt2}
graph fails to run, what caused the failure? It could be caused by any
component, any message iterator, and any deeply nested validation of a
CTF IR object (within the `ctf` plugin), for example. With the
While <<choose-a-log-level,care must be taken>> when placing _DEBUG_ to
_FATAL_ logging statements, you should liberally instrument your
-Babeltrace module with _TRACE_ logging statements to help future you
+{bt2} module with _TRACE_ logging statements to help future you
and other developers understand what's happening at run time.
-
=== Logging API
-The Babeltrace logging API is internal: it is not exposed to the users
+The {bt2} logging API is internal: it is not exposed to the users
of the library; only to their developers. The only thing that a library
user can control is the current log level of the library itself with
`bt_logging_set_global_level()` and the initial library's log level with
This API is based on https://github.com/wonder-mice/zf_log[zf_log], a
lightweight, yet featureful, MIT-licensed core logging library for C and
-pass:[C++]. The zf_log source files were modified to have the `BT_` and
+{cpp}. The zf_log source files were modified to have the `BT_` and
`bt_` prefixes, and other small changes, like color support and using
the project's `BT_DEBUG_MODE` definition instead of the standard
`NDEBUG`.
The logging functions are implemented in the logging convenience
library (`src/logging` directory).
-
[[logging-headers]]
==== Headers
libbabeltrace2's current log level.
`"logging/log.h"`::
- Internal, generic logging API which you can use in any Babeltrace
+ Internal, generic logging API which you can use in any {bt2}
module. This is the translation of `zf_log.h`.
+
This header offers the <<gen-logging-statements,generic logging
This header offers the <<lib-logging-statements,library-specific logging
statement macros>>.
-`"plugins/comp-logging.h"`::
+`"logging/comp-logging.h"`::
Specific internal header to use within a component class.
+
This header offers the <<comp-logging-statements,component-specific
logging statement macros>>.
-
[[log-levels]]
==== Log levels
|`BT_LOG_INFO`
|`BT_LOGGING_LEVEL_INFO`
-|_WARN_
+|_WARNING_
|`W`
-|`BT_LOG_WARN`
-|`BT_LOGGING_LEVEL_WARN`
+|`BT_LOG_WARNING`
+|`BT_LOGGING_LEVEL_WARNING`
|_ERROR_
|`E`
+
--
----
-$ BABELTRACE_MINIMAL_LOG_LEVEL=WARN ./configure
+$ BABELTRACE_MINIMAL_LOG_LEVEL=INFO ./configure
----
--
+
The default build-time log level is `DEBUG`. For optimal performance,
set it to `INFO`, which effectively disables all fast path logging in
-all the Babeltrace modules.
+all the {bt2} modules. You can't set it to `WARNING`, `ERROR`,
+`FATAL`, or `NONE` because the impact on performance is minuscule
+starting from the _INFO_ log level anyway and we want any {bt2}
+build to always be able to print _INFO_-level logs.
+
The library's public API provides `bt_logging_get_minimal_level()` to
get the configured minimal log level.
path = bt_common_get_home_plugin_path(BT_LOG_NONE);
----
-
[[gen-logging-statements]]
==== Generic logging statement macros
-The Babeltrace logging statement macros work just like `printf()`
+The {bt2} logging statement macros work just like `printf()`
(except the `+BT_LOG*_STR()+` ones) and contain their <<log-levels,log
level>> (short name) in their name.
<<run-time-log-level,run-time log level>> expression (as defined by
`BT_LOG_OUTPUT_LEVEL`) to log conditionally.
-See <<logging-instrument-c-file-gen,Instrument a C source file
-(generic)>> and <<logging-instrument-h-file-gen,Instrument a C header
-file (generic)>> to learn how to be able to use the following macros.
+See <<logging-instrument-c-file-gen>> and
+<<logging-instrument-h-file-gen>> to learn how to be able to use the
+following macros.
`+BT_LOGT("format string", ...)+`::
Generic trace logging statement.
`+BT_LOGF_ERRNO("initial message", "format string", ...)+`::
Generic `errno` string fatal logging statement.
-
[[lib-logging-statements]]
==== Library-specific logging statement macros
-The Babeltrace library contains an internal logging API based on the
-generic logging framework. You can use it to log known Babeltrace
+The {bt2} library contains an internal logging API based on the
+generic logging framework. You can use it to log known {bt2}
objects without having to manually log each member.
-See <<logging-instrument-c-file-lib,Instrument a library C source file>>
-and <<logging-instrument-h-file-lib,Instrument a library C header file>> to
+See <<logging-instrument-c-file-lib>>
+and <<logging-instrument-h-file-lib>> to
learn how to be able to use the following macros.
The library logging statement macros are named `+BT_LIB_LOG*()+` instead
`+BT_LIB_LOGF("format string", ...)+`::
Library fatal logging statement.
+`+BT_LIB_LOGW_APPEND_CAUSE("format string", ...)+`::
+ Library warning logging statement, and unconditional error cause
+ appending.
+
+`+BT_LIB_LOGE_APPEND_CAUSE("format string", ...)+`::
+ Library error logging statement, and unconditional error cause
+ appending.
+
+`+BT_LIB_LOGF_APPEND_CAUSE("format string", ...)+`::
+ Library fatal logging statement, and unconditional error cause
+ appending.
+
The macros above accept the typical `printf()` conversion specifiers
with the following limitations:
except for `PRId64`, `PRIu64`, `PRIx64`, `PRIX64`, `PRIo64`, and
`PRIi64`.
-The Babeltrace library custom conversion specifier is accepted. Its
+The {bt2} library custom conversion specifier is accepted. Its
syntax is either `%!u` to format a UUID (`bt_uuid` type), or:
. Introductory `%!` sequence.
|`F`
|Trace IR field class
-|`+struct bt_field_class *+`
+|`+const struct bt_field_class *+`
|`f`
|Trace IR field
-|`+struct bt_field *+`
+|`+const struct bt_field *+`
|`P`
|Trace IR field path
-|`+struct bt_field_path *+`
+|`+const struct bt_field_path *+`
|`E`
|Trace IR event class
-|`+struct bt_event_class *+`
+|`+const struct bt_event_class *+`
|`e`
|Trace IR event
-|`+struct bt_event *+`
+|`+const struct bt_event *+`
|`S`
|Trace IR stream class.
-|`+struct bt_stream_class *+`
+|`+const struct bt_stream_class *+`
|`s`
|Trace IR stream
-|`+struct bt_stream *+`
+|`+const struct bt_stream *+`
|`a`
|Trace IR packet
-|`+struct bt_packet *+`
+|`+const struct bt_packet *+`
|`T`
|Trace IR trace class
-|`+struct bt_trace_class *+`
+|`+const struct bt_trace_class *+`
|`t`
|Trace IR trace
-|`+struct bt_trace *+`
+|`+const struct bt_trace *+`
|`K`
|Trace IR clock class
-|`+struct bt_clock_class *+`
+|`+const struct bt_clock_class *+`
|`k`
|Trace IR clock snapshot
-|`+struct bt_clock_snapshot *+`
+|`+const struct bt_clock_snapshot *+`
|`v`
|Value object
-|`+struct bt_value *+`
+|`+const struct bt_value *+`
+
+|`R`
+|Integer range set
+|`const struct bt_integer_range_set *`
|`n`
|Message
-|`+struct bt_message *+`
+|`+const struct bt_message *+`
+
+|`I`
+|Message iterator class
+|`struct bt_message_iterator_class *`
|`i`
|Message iterator
|`c`
|Component
-|`+struct bt_component *+`
+|`+const struct bt_component *+`
|`p`
|Port
-|`+struct bt_port *+`
+|`+const struct bt_port *+`
|`x`
|Connection
-|`+struct bt_connection *+`
+|`+const struct bt_connection *+`
|`g`
|Graph
-|`+struct bt_graph *+`
+|`+const struct bt_graph *+`
+
+|`z`
+|Interrupter
+|`+struct bt_interrupter *+`
|`l`
|Plugin
-|`const struct bt_plugin *`
+|`+const struct bt_plugin *+`
+
+|`r`
+|Error cause
+|`+const struct bt_error_cause *+`
|`o`
|Object pool
-|`+struct bt_object_pool *+`
+|`+const struct bt_object_pool *+`
|`O`
|Object
-|`+struct bt_object *+`
+|`+const struct bt_object *+`
|===
Conversion specifier examples:
BT_LIB_LOGI("Some message: %![ec-a-]e, %![ec-b-]+e", ec_a, ec_b);
----
-It is safe to pass `NULL` as any Babeltrace object parameter: the macros
+It is safe to pass `NULL` as any {bt2} object parameter: the macros
only print its null address.
WARNING: Build-time `printf()` format checks are disabled for the
`+BT_LIB_LOG*()+` macros because there are custom conversion specifiers,
so make sure to test your logging statements.
-
[[comp-logging-statements]]
==== Component-specific logging statement macros
There are available logging macros for components. They prepend a prefix
including the component's name to the logging message.
-See <<logging-instrument-c-file-compcls,Instrument a component class C
-source file>> and <<logging-instrument-h-file-compcls,Instrument a
-component class C header file>> to learn how to be able to use the
+See <<logging-instrument-c-file-compcls>> and
+<<logging-instrument-h-file-compcls>> to learn how to be able to use the
following macros.
The component logging statement macros are named `+BT_COMP_LOG*()+`
`+BT_COMP_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
Component memory fatal logging statement.
-
==== Conditional logging
`+BT_LOG_IF(cond, statement)+`::
* `BT_LOG_ENABLED_TRACE`
* `BT_LOG_ENABLED_DEBUG`
* `BT_LOG_ENABLED_INFO`
-* `BT_LOG_ENABLED_WARN`
+* `BT_LOG_ENABLED_WARNING`
* `BT_LOG_ENABLED_ERROR`
* `BT_LOG_ENABLED_FATAL`
* `BT_LOG_ON_TRACE`
* `BT_LOG_ON_DEBUG`
* `BT_LOG_ON_INFO`
-* `BT_LOG_ON_WARN`
+* `BT_LOG_ON_WARNING`
* `BT_LOG_ON_ERROR`
* `BT_LOG_ON_FATAL`
BT_LOGD("Bla bla: number=%d", get_number_of_event_classes_with_property_x(...));
----
-
=== Guides
[[logging-instrument-c-file-gen]]
-==== Instrument a C source file (generic)
+==== Instrument a {c-cpp} source file (generic)
-To instrument a C source file (`.c`):
+To instrument a {c-cpp} source file (`.c`/`.cpp`):
. At the top of the file, before the first `#include` line (if any),
define your file's <<choose-a-logging-tag,logging tag>> name:
. In the file, instrument your code with the
<<gen-logging-statements,generic logging statement macros>>.
-
[[logging-instrument-h-file-gen]]
-==== Instrument a C header file (generic)
+==== Instrument a {c-cpp} header file (generic)
-To instrument a C header file (`.h`), if you have `static inline`
-functions in it:
+To instrument a {c-cpp} header file (`.h`/`.hpp`), if you have
+`static inline` functions in it:
. Do not include `"logging/log.h"`!
}
----
+
-The C source files which include this header file determine if logging
-is enabled or not for them, and if so, what is their
+The {c-cpp} source files which include this header file determine if
+logging is enabled or not for them, and if so, what is their
<<choose-a-logging-tag,logging tag>> and <<run-time-log-level,run-time
log level>> expression.
Then, in the file, instrument your code with the
<<gen-logging-statements,generic logging statement macros>>.
-
[[logging-instrument-c-file-lib]]
-==== Instrument a library C source file
+==== Instrument a library {c-cpp} source file
-To instrument a library C source file (`.c`):
+To instrument a library {c-cpp} source file (`.c`/`.cpp`):
. At the top of the file, before the first `#include` line (if any),
define your file's <<choose-a-logging-tag,logging tag>> name (this
<<lib-logging-statements,library logging statement macros>> or with
the <<gen-logging-statements,generic logging statement macros>>.
-
[[logging-instrument-h-file-lib]]
-==== Instrument a library C header file
+==== Instrument a library {c-cpp} header file
-To instrument a library C header file (`.h`), if you have `static
-inline` functions in it:
+To instrument a library {c-cpp} header file (`.h`/`.hpp`), if you have
+`static inline` functions in it:
. Do not include `"lib/logging.h"`!
<<lib-logging-statements,library logging statement macros>> or with
the <<gen-logging-statements,generic logging statement macros>>.
-
[[logging-instrument-c-file-compcls]]
-==== Instrument a component class C source file
+==== Instrument a component class {c-cpp} source file
-To instrument a component class C source file (`.c`):
+To instrument a component class {c-cpp} source file (`.c`/`.cpp`):
. At the top of the file, before the first `#include` line (if any),
define your file's <<choose-a-logging-tag,logging tag>> name (this tag
#define BT_COMP_LOG_SELF_COMP (my_comp->self_comp)
----
-. Include `"plugins/comp-logging.h"`:
+. Include `"logging/comp-logging.h"`:
+
[source,c]
----
-#include "plugins/comp-logging.h"
+#include "logging/comp-logging.h"
----
. In the component initialization method, make sure to set the
. In the file, instrument your code with the
<<comp-logging-statements,component logging statement macros>>.
-
[[logging-instrument-h-file-compcls]]
-==== Instrument a component class C header file
+==== Instrument a component class {c-cpp} header file
-To instrument a component class C header file (`.h`), if you have
-`static inline` functions in it:
+To instrument a component class {c-cpp} header file (`.h`/`.hpp`), if
+you have `static inline` functions in it:
-. Do not include `"plugins/comp-logging.h"`!
+. Do not include `"logging/comp-logging.h"`!
. Require that component logging be enabled:
+
----
/* Protection: this file uses BT_COMP_LOG*() macros directly */
#ifndef BT_COMP_LOG_SUPPORTED
-# error Please include "plugins/comp-logging.h" before including this file.
+# error Please include "logging/comp-logging.h" before including this file.
#endif
----
. In the file, instrument your code with the
<<comp-logging-statements,component logging statement macros>>.
-
[[choose-a-logging-tag]]
==== Choose a logging tag
-Each logging-enabled C source file must define `BT_LOG_TAG` to a logging
-tag. A logging tag is a namespace to identify the logging messages of
-this specific source file.
+Each logging-enabled {c-cpp} source file must define `BT_LOG_TAG` to a
+logging tag. A logging tag is a namespace to identify the logging
+messages of this specific source file.
In general, a logging tag name _must_ be only uppercase letters, digits,
and the `-`, `.`, and `/` characters.
Use `/` to show the subsystem to source file hierarchy.
-For the Babeltrace library, start with `LIB/`.
+For the {bt2} library, start with `LIB/`.
For the CTF writer library, start with `CTF-WRITER/`.
`__FILE__`::
Additional information to specify the source file name or module.
-
[[choose-a-log-level]]
==== Choose a log level
* Logic error in internal code, for example an unexpected value in a
`switch` statement.
* Failed assertion (within `BT_ASSERT()`).
-* Unsatisfied library precondition (within `BT_ASSERT_PRE()`).
-|Almost none: should be executed in production.
+* Unsatisfied library precondition (within `BT_ASSERT_PRE()` or
+ `BT_ASSERT_PRE_DEV()`).
+* Unsatisfied library postcondition (within `BT_ASSERT_POST()` or
+ `BT_ASSERT_POST_DEV()`).
+|Almost none: always enabled.
|_ERROR_
|
failure to create an empty object (no parameters): most probably
failed internally because of an allocation error.
* Almost any error in terminal elements: CLI and plugins.
-|Almost none: should be executed in production.
+|Almost none: always enabled.
-|_WARN_
+|_WARNING_
|
An error which still allows the execution to continue, but you judge
that it should be reported to the user.
-_WARN_-level logging statements are for any error or weird action that
-is directly or indirectly caused by the user, often through some bad
-input data. For example, not having enough memory is considered beyond
-the user's control, so we always log memory errors with an _ERROR_ level
-(not _FATAL_ because we usually don't abort in this condition).
+_WARNING_-level logging statements are for any error or weird action
+that is directly or indirectly caused by the user, often through some
+bad input data. For example, not having enough memory is considered
+beyond the user's control, so we always log memory errors with an
+_ERROR_ level (not _FATAL_ because we usually don't abort in this
+condition).
|
* Missing data within something that is expected to have it, but there's
an alternative.
* Invalid file, but recoverable/fixable.
-|Almost none: can be executed in production.
+|Almost none: always enabled.
|_INFO_
|
* An _optional_ subsystem cannot be loaded.
* An _optional_ field/datum cannot be found.
|
-Very little: can be executed in production if _INFO_ level information
-is desired.
+Very little: always enabled.
|_DEBUG_
|
-Something that only Babeltrace developers would be interested into,
+Something that only {bt2} developers would be interested into,
which can occur on the fast path, but not more often than once per
message.
* Object copying (except fields and values).
* Object freezing (whatever the type, as freezing only occurs in
developer mode).
-* Object cancellation.
+* Object interruption.
* Calling user methods and logging the result.
* Setting object properties (except fields and values).
|
[IMPORTANT]
--
-Make sure not to use a _WARN_ (or higher) log level when the
+Make sure not to use a _WARNING_ (or higher) log level when the
condition leading to the logging statement can occur under normal
circumstances.
_TRACE_ level (or do not log at all).
--
-
[[message]]
==== Write an appropriate message
|`-name` |Object's name |`\"%s\"`
|===
-
=== Output
The log is printed to the standard error stream. A log line contains the
<<choose-a-logging-tag,logging tag>>, the source's function name, file
name and line number, and the <<message,message>>.
-When Babeltrace supports terminal color codes (depends on the
+When {bt2} supports terminal color codes (depends on the
`BABELTRACE_TERM_COLOR` environment variable's value and what the
standard output and error streams are plugged into), _INFO_-level lines
-are blue, _WARN_-level lines are yellow, and _ERROR_-level and
+are blue, _WARNING_-level lines are yellow, and _ERROR_-level and
_FATAL_-level lines are red.
Log line example:
$ babeltrace2 --log-level=D /path/to/trace |& ag 'D FIELD-CLASS'
----
-
== Valgrind
To use Valgrind on an application (for example, the CLI or a test) which
----
$ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \
- BABELTRACE_NO_DLCLOSE=1 valgrind --leak-check=full \
- --suppressions=/path/to/babeltrace/extras/valgrind/popt.supp app
+ LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full app
----
`G_SLICE=always-malloc` and `G_DEBUG=gc-friendly` is for GLib and
the Python plugin provider (Valgrind will probably show a lot of errors
which originate from the Python interpreter anyway).
-`BABELTRACE_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared
+`LIBBABELTRACE2_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared
libraries (plugins) which it loads. You need this to see the appropriate
backtrace when Valgrind shows errors.
+
+== Testing
+
+[[test-env]]
+=== Environment
+
+Running `make check` in the build directory (regardless of whether the build is
+in-tree or out-of-tree) automatically sets up the appropriate environment for
+tests to run in, so nothing more is needed.
+
+If building in-tree, you can run single tests from the tree directly:
+
+----
+$ ./tests/plugins/sink.text.pretty/test_enum
+----
+
+If building out-of-tree, you can get the appropriate environment by sourcing
+the `tests/utils/env.sh` file residing in the build directory against which you
+want to run tests.
+
+----
+$ source /path/to/my/build/tests/utils/env.sh
+$ ./tests/plugins/sink.text.pretty/test_enum
+----
+
+==== Python
+
+You can use the `tests/utils/run_python_bt2` script to run any command
+within an environment making the build's `bt2` Python package available.
+
+`run_python_bt2` uses <<test-env,`utils.sh`>> which needs to know the
+build directory, so make sure you set the `BT_TESTS_BUILDDIR`
+environment variable correctly _if you build out of tree_, for example:
+
+----
+$ export BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests
+----
+
+You can run any command which needs the `bt2` Python package through
+`run_python_bt2`, for example:
+
+----
+$ ./tests/utils/run_python_bt2 ipython3
+----
+
+=== Report format
+
+All test scripts output the test results following the
+https://testanything.org/[Test Anything Protocol] (TAP) format.
+
+The TAP format has two mechanisms to print additional information about
+a test:
+
+* Print a line starting with `#` to the standard output.
++
+This is usually done with the `diag()` C function or the `diag` shell
+function.
+
+* Print to the standard error.
+
+=== Python bindings
+
+The `bt2` Python package tests are located in
+`tests/bindings/python/bt2`.
+
+==== Python test runner
+
+`tests/utils/python/testrunner.py` is {bt2}'s Python test runner
+which loads Python files containing unit tests, finds all the test
+cases, and runs the tests, producing a TAP report.
+
+You can see the test runner command's help with:
+
+----
+$ python3 ./tests/utils/python/testrunner.py --help
+----
+
+By default, the test runner reports failing tests (TAP's `not{nbsp}ok`
+line), but continues to run other tests. You can use the `--failfast`
+option to make the test runner fail as soon as a test fails.
+
+==== Guides
+
+To run all the `bt2` Python package tests:
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 ./tests/bindings/python/bt2/test_python_bt2
+----
++
+or:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2/ -p '*.py'
+----
+
+To run **all the tests** in a test module (for example,
+`test_value.py`):
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2 -t test_value
+----
+
+To run a **specific test case** (for example, `RealValueTestCase` within
+`test_value.py`):
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase
+----
+
+To run a **specific test** (for example,
+`RealValueTestCase.test_assign_pos_int` within `test_value.py`):
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int
+----
+
+== {cpp} usage
+
+Some parts of {bt2} are written in {cpp}.
+
+This section shows what's important to know about {cpp} to contribute
+to {bt2}.
+
+[IMPORTANT]
+====
+{bt2} only has {cpp} sources for _internal_ code.
+
+In other words, libbabeltrace2 _must_ expose a pure C99 API to preserve
+ABI compatibility over time.
+====
+
+=== Standard and dependencies
+
+The {bt2} project is configured to use the {cpp11} standard.
+
+{cpp11} makes it possible to build {bt2} with a broad range of
+compilers, from GCC{nbsp}4.8 and Clang{nbsp}3.3.
+
+=== Automake/Libtool requirements
+
+To add a {cpp} source file to a part of the project, use the `.cpp`
+extension and add it to the list of source files in `Makefile.am` as
+usual.
+
+If a program or a shared library has a direct {cpp} source file, then
+Libtool uses the {cpp} linker to create the result, dynamically
+linking important runtime libraries such as libstdc++ and libgcc_s.
+
+Because a Libtool _convenience library_ is just an archive (`.a`), it's
+_not_ dynamically linked to runtime libraries, even if one of its direct
+sources is a {cpp} file. This means that for each program or shared
+library named `my_target` in `Makefile.am` which is linked to a
+convenience library having {cpp} sources (recursively), you _must_ do
+one of:
+
+* Have at least one direct {cpp} source file in the
+ `+*_my_target_SOURCES+` list.
+
+* Add:
++
+----
+nodist_EXTRA_my_target_SOURCES = dummy.cpp
+----
++
+See
+https://www.gnu.org/software/automake/manual/automake.html#Libtool-Convenience-Libraries[Libtool
+Convenience Libraries] to learn more.
+
+For a given program or library, you _cannot_ have a C{nbsp}file and a
+{cpp}{nbsp}file having the same name, for example `list.c` and
+`list.cpp`.
+
+=== Coding style
+
+==== Whitespaces, indentation, and line breaks
+
+All the project's {cpp} files follow the
+https://clang.llvm.org/docs/ClangFormat.html[clang-format]
+https://clang.llvm.org/docs/ClangFormatStyleOptions.html[style] of the
+`.clang-format` file for whitespaces, indentation, and line breaks.
+
+You _must_ format modified and new {cpp} files with clang-format before
+you create a contribution patch.
+
+You need clang-format{nbsp}13 to use the project's `.clang-format` file.
+
+To automatically format all the project's {cpp} files, run:
+
+----
+$ ./tools/format-cpp
+----
+
+Use the `FORMATTER` environment variable to override the default
+formatter (`clang-format{nbsp}-i`):
+
+----
+$ FORMATTER='clang-format-10 -i' ./tools/format-cpp
+----
+
+==== Naming
+
+* Use camel case with a lowercase first letter for:
+** Variable names: `size`, `objSize`.
+** Function/method names: `size()`, `formatAndPrint()`.
+
+* Use camel case with an uppercase first letter for:
+** Types: `Pistachio`, `NutManager`.
+** Template parameters: `PlanetT`, `TotalSize`.
+
+* Use snake case with uppercase letters for:
+** Definition/macro names: `MARK_AS_UNUSED()`, `SOME_FEATURE_EXISTS`.
+** Enumerators: `Type::SIGNED_INT`, `Scope::FUNCTION`.
+
+* Use only lowercase letters and digits for namespaces: `mylib`, `bt2`.
+
+* Use the suffix `T` for type template parameters:
++
+[source,cpp]
+----
+template <typename NameT, typename ItemT>
+----
+
+* Name a template parameter pack `Args`.
++
+[source,cpp]
+----
+template <typename NameT, typename... Args>
+----
+
+* Use an underscore prefix for private and protected methods and member
+ type names: `_tryConnect()`, `_NodeType`.
+
+* Use the prefix `_m` for private and protected member variable names:
+ `_mLogger`, `_mSize`, `_mFieldClass`.
+
+* Name setters and getters like the property name, without `set` and
+ `get` prefixes.
+
+* Use the `is` or `has` prefix, if possible, to name the functions which
+ return `bool`.
+
+=== Coding convention
+
+In general, the project's contributors make an effort to follow,
+for {cpp11} code:
+
+* The
+ https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md[{cpp} Core Guidelines].
+
+* Scott Meyers's
+ "`https://www.oreilly.com/library/view/effective-modern-c/9781491908419/[Effective Modern {cpp}]`".
+
+Here are a few important reminders:
+
+* Namespace your code.
+
+* Create one header/source file pair per class when possible.
++
+For a class named `MyClass`, name the corresponding files `my-class.hpp`
+and `my-class.cpp`.
+
+* When defining a class, put constructors as the first methods, whatever
+ their access (public/protected/private), then the destructor, and then
+ the rest.
+
+* Declare variables as close to where they are used as possible.
+
+* Use `auto` when possible.
+
+* Use `const` as much as possible, even for pointer
+ (`+const char* const+`) and numeric values (`const unsigned int`)
+ which never need to change.
+
+* Implement simple setters, getters, and one-liners in header files and
+ everything else that's not a template in source files.
+
+* Make methods `const noexcept` or `const` as much as possible.
+
+* Make constructors `explicit` unless you really need an implicit
+ constructor (which is rare).
+
+* Use `std::unique_ptr` to manage memory when possible.
++
+However, use references (`+*my_unique_ptr+`) and raw pointers
+(`+my_unique_ptr.get()+`) when not transferring ownership.
+
+* Use `nullptr`, not `NULL` nor 0.
+
+* Return by value (rvalue) instead of by output parameter (non-const
+ lvalue reference), even complex objects, unless you can prove that the
+ performance is improved when returning by parameter.
+
+* For a function parameter or a return value of which the type needs to
+ be a reference or pointer, use:
++
+If the value is mandatory:::
+ A reference.
+If the value is optional:::
+ A raw pointer.
+
+* Don't use `+std::move()+` when you already have an rvalue, which
+ means:
+** Don't write `+return std::move(...);+` as this can interfere with
+ RVO.
+** Don't use `+std::move()+` with a function call
+ (`+std::move(func())+`).
+
+* For each possible move/copy constructor or assignment operator, do one
+ of:
+** Write a custom one.
+** Mark it as defaulted (`default`)
+** Mark it as deleted (`delete`).
+
+* Use scoped enumerations (`+enum class+`).
+
+* Mark classes known to be final with the `final` keyword.
+
+* Use type aliases (`using`), not type definitions (`typedef`).
+
+* Use anonymous namespaces for local functions instead of `static`.
+
+* Don't pollute the global namespace:
+** Don't use `using namespace xyz` anywhere.
+** Use only namespace aliases in source files (`.cpp`), trying to
+ use them in the smallest possible scope (function, or even smaller).
+
+* Return a structure with named members instead of a generic container
+ such as `std::pair` or `std::tuple`.
+
+* When a class inherits a base class with virtual methods, use the
+ `override` keyword to mark overridden virtual methods, and do not use
+ the `virtual` keyword again.
+
+* Define overloaded operators only if their meaning is obvious,
+ unsurprising, and consistent with the corresponding built-in
+ operators.
++
+For example, use `+|+` as a bitwise- or logical-or, not as a shell-style
+pipe.
+
+* Use RAII wrappers when managing system resources or interacting with
+ C{nbsp}libraries.
++
+In other words, don't rely on ``goto``s and error labels to clean up as
+you would do in{nbsp}C.
++
+Use the RAII, Luke.
+
+* Throw an exception when there's an unexpected, exceptional condition,
+ https://isocpp.org/wiki/faq/exceptions#ctors-can-throw[including from
+ a constructor], instead of returning a status code.
+
+* Accept a by-value parameter and move it (when it's moveable) when you
+ intend to copy it anyway.
++
+You can do this with most STL containers.
++
+Example:
++
+[source,cpp]
+----
+void Obj::doSomething(std::string str)
+{
+ _mName = std::move(str);
+ // ...
+}
+----
+
+.`baby.hpp`
+====
+This example shows a {cpp} header which follows the {bt2} {cpp} coding
+convention.
+
+[source,cpp]
+----
+/*
+ * SPDX-License-Identifier: MIT
+ *
+ * Copyright 2020 Harry Burnett <hburnett@reese.choco>
+ */
+
+#ifndef BABELTRACE_BABY_HPP
+#define BABELTRACE_BABY_HPP
+
+#include <string>
+#include <unordered_set>
+#include <utility>
+
+namespace life {
+
+class Toy;
+
+/*
+ * A baby is a little human.
+ */
+class Baby : public Human
+{
+public:
+ using Toys = std::unordered_set<Toy>;
+
+ enum class Gender
+ {
+ MALE,
+ FEMALE,
+ UNKNOWN,
+ };
+
+ Baby() = default;
+ explicit Baby(const Toys& toys);
+ Baby(const Baby&) = delete;
+ Baby(Baby&&) = delete;
+ Baby& operator=(const Baby&) = delete;
+ Baby& operator=(Baby&&) = delete;
+
+protected:
+ explicit Baby(Gender initialGender = Gender::UNKNOWN);
+
+public:
+ /*
+ * Eats `weight` grams of food.
+ */
+ void eat(unsigned long weight);
+
+ /*
+ * Sleeps for `duration` seconds.
+ */
+ void sleep(double duration);
+
+ /*
+ * Sets this baby's name to `name`.
+ */
+ void name(std::string name)
+ {
+ _mName = std::move(name);
+ }
+
+ /*
+ * This baby's name.
+ */
+ const std::string& name() const noexcept
+ {
+ return _mName;
+ }
+
+protected:
+ void _addTeeth(unsigned long index);
+ void _grow(double size) override;
+
+private:
+ std::string _mName {"Paul"};
+ Toys _mToys;
+};
+
+} // namespace life
+
+#endif // BABELTRACE_BABY_HPP
+----
+====
projects / babeltrace.git / blobdiff