| 1 | // SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com> |
| 2 | // SPDX-License-Identifier: CC-BY-4.0 |
| 3 | // |
| 4 | lttng-gen-tp(1) |
| 5 | =============== |
| 6 | :object-type: program |
| 7 | |
| 8 | |
| 9 | NAME |
| 10 | ---- |
| 11 | lttng-gen-tp - Generate LTTng-UST tracepoint provider code |
| 12 | |
| 13 | |
| 14 | SYNOPSIS |
| 15 | -------- |
| 16 | [verse] |
| 17 | *lttng-gen-tp* [option:--verbose] [option:--output='FILE'.c] |
| 18 | [option:--output='FILE'.h] [option:--output='FILE'.o] 'TEMPLATE' |
| 19 | |
| 20 | |
| 21 | DESCRIPTION |
| 22 | ----------- |
| 23 | The `lttng-gen-tp` tool simplifies the generation of LTTng-UST |
| 24 | tracepoint provider files. It takes a simple template file, 'TEMPLATE', |
| 25 | and generates the necessary C code to use the defined tracepoints in |
| 26 | your application. See the <<template-file-format,Template file format>> |
| 27 | section below for more information about the format of 'TEMPLATE'. |
| 28 | |
| 29 | Currently, `lttng-gen-tp` can generate the `.h`, `.c`, and `.o` files |
| 30 | associated with your tracepoint provider. The generated `.h` file can be |
| 31 | included directly in your application. You can let `lttng-gen-tp` |
| 32 | generate the `.o` file or compile the `.c` file yourself. See |
| 33 | man:lttng-ust(3) for more information about compiling LTTng-UST |
| 34 | tracepoint providers. |
| 35 | |
| 36 | By default, `lttng-gen-tp` generates the `.h`, `.c`, and `.o` files, |
| 37 | their basename being the basename of 'TEMPLATE'. You can generate one or |
| 38 | more specific file types with the option:--output option, repeated if |
| 39 | needed. |
| 40 | |
| 41 | |
| 42 | [[template-file-format]] |
| 43 | Template file format |
| 44 | ~~~~~~~~~~~~~~~~~~~~ |
| 45 | The template file, which usually has the `.tp` extension, contains a |
| 46 | list of `LTTNG_UST_TRACEPOINT_EVENT()` definitions and other optional |
| 47 | definition entries, like `LTTNG_UST_TRACEPOINT_LOGLEVEL()`. See |
| 48 | man:lttng-ust(3) for the complete list of available definitions. |
| 49 | |
| 50 | The `LTTNG_UST_TRACEPOINT_EVENT()` definitions are written as you would |
| 51 | write them in an LTTng-UST template provider header file. C comments are |
| 52 | supported (`/* */` and `//`), as well as lines starting with `#`. |
| 53 | |
| 54 | NOTE: The provider name (the first argument of |
| 55 | `LTTNG_UST_TRACEPOINT_EVENT()`) must be the same in all the |
| 56 | `LTTNG_UST_TRACEPOINT_EVENT()` macros of 'TEMPLATE'. |
| 57 | |
| 58 | Here's an example: |
| 59 | |
| 60 | --------------------------------------- |
| 61 | LTTNG_UST_TRACEPOINT_EVENT( |
| 62 | // Tracepoint provider name |
| 63 | my_provider, |
| 64 | |
| 65 | // Tracepoint/event name |
| 66 | my_event, |
| 67 | |
| 68 | // Tracepoint arguments (input) |
| 69 | LTTNG_UST_TP_ARGS(char *, text), |
| 70 | |
| 71 | // Tracepoint/event fields (output) |
| 72 | LTTNG_UST_TP_FIELDS( |
| 73 | lttng_ust_field_string(message, text) |
| 74 | ) |
| 75 | ) |
| 76 | --------------------------------------- |
| 77 | |
| 78 | |
| 79 | OPTIONS |
| 80 | ------- |
| 81 | option:-o, option:--output='FILE':: |
| 82 | Do not generate default files: generate 'FILE'. |
| 83 | + |
| 84 | The extension of 'FILE' determines what is generated, amongst `.h`, |
| 85 | `.c`, and `.o`. This option can be used more than one time to generate |
| 86 | different file types. |
| 87 | |
| 88 | option:-v, option:--verbose:: |
| 89 | Increase verbosity. |
| 90 | |
| 91 | option:-h, option:--help:: |
| 92 | Show command help. |
| 93 | |
| 94 | |
| 95 | ENVIRONMENT VARIABLES |
| 96 | --------------------- |
| 97 | `CC`:: |
| 98 | C compiler to use. Default: `cc`, then `gcc` if `cc` is not found. |
| 99 | This option is only relevant when generating the `.o` file. |
| 100 | |
| 101 | `CFLAGS`:: |
| 102 | Flags and options passed directly to the compiler (`$CC`). |
| 103 | This option is only relevant when generating the `.o` file. |
| 104 | |
| 105 | |
| 106 | EXIT STATUS |
| 107 | ----------- |
| 108 | *0*:: |
| 109 | Success |
| 110 | |
| 111 | *Non-zero*:: |
| 112 | Error |
| 113 | |
| 114 | |
| 115 | include::common-footer.txt[] |
| 116 | |
| 117 | |
| 118 | COPYRIGHTS |
| 119 | ---------- |
| 120 | `lttng-gen-tp` is part of the LTTng-UST project. |
| 121 | |
| 122 | `lttng-gen-tp` is distributed under the |
| 123 | http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html[GNU General |
| 124 | Public License, version 2]. See the |
| 125 | https://github.com/lttng/lttng-ust/blob/v{lttng_version}/COPYING[`COPYING`] file |
| 126 | for more details. |
| 127 | |
| 128 | |
| 129 | AUTHOR |
| 130 | ------ |
| 131 | `lttng-gen-tp` was originally written by |
| 132 | mailto:yannick.brosseau@gmail.com[Yannick Brosseau]. It is currently |
| 133 | maintained by mailto:mathieu.desnoyers@efficios.com[Mathieu Desnoyers]. |
| 134 | |
| 135 | |
| 136 | SEE ALSO |
| 137 | -------- |
| 138 | man:lttng-ust(3) |