doc/man/lttng-gen-tp.1.txt

   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)