Commit | Line | Data |
---|---|---|
53f7d0d7 MJ |
1 | // SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com> |
2 | // SPDX-License-Identifier: CC-BY-4.0 | |
3 | // | |
4ddbd0b7 PP |
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 | |
5b1163c6 PP |
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. | |
4ddbd0b7 | 49 | |
5b1163c6 PP |
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 `#`. | |
4ddbd0b7 | 53 | |
5b1163c6 PP |
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'. | |
4ddbd0b7 PP |
57 | |
58 | Here's an example: | |
59 | ||
60 | --------------------------------------- | |
5b1163c6 | 61 | LTTNG_UST_TRACEPOINT_EVENT( |
4ddbd0b7 PP |
62 | // Tracepoint provider name |
63 | my_provider, | |
64 | ||
65 | // Tracepoint/event name | |
66 | my_event, | |
67 | ||
68 | // Tracepoint arguments (input) | |
5b1163c6 | 69 | LTTNG_UST_TP_ARGS(char *, text), |
4ddbd0b7 PP |
70 | |
71 | // Tracepoint/event fields (output) | |
5b1163c6 PP |
72 | LTTNG_UST_TP_FIELDS( |
73 | lttng_ust_field_string(message, text) | |
4ddbd0b7 PP |
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 | |
f596de62 | 125 | https://github.com/lttng/lttng-ust/blob/v{lttng_version}/COPYING[`COPYING`] file |
4ddbd0b7 PP |
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) |