doc/man/lttng-gen-tp.1

   1 .TH "LTTNG-GEN-TP" "1" "February 16, 2012" "" ""
   2
   3 .SH "NAME"
   4 lttng-gen-tp \(em LTTng UST 2.x tracepoint code generator
   5
   6 .SH "SYNOPSIS"
   7
   8 .PP
   9 .nf
  10 lttng\-gen\-tp [OPTIONS] TEMPLATE_FILE
  11 .fi
  12 .SH "DESCRIPTION"
  13
  14 .PP
  15 The LTTng project aims at providing highly efficient tracing tools for Linux.
  16 It's tracers help tracking down performance issues and debugging problems
  17 involving multiple concurrent processes and threads. Tracing across multiple
  18 systems is also possible.
  19
  20 The \fBlttng\-gen\-tp\fP tool simplify the generation of the UST tracepoint
  21 files. It takes a simple template file and generate the necessary code to use the defined tracepoints in your application.
  22 The section TEMPLATE FILE FORMAT describe the content of the template file.
  23
  24 Currently, the tool can generate the .h, .c and .o associated to your
  25 tracepoint. The generated .h can be directly included in your application.
  26 You can let the tool generate the .o or compile the .c yourself.
  27 You can compile the .c into a .o, .a or .so at your choice and
  28 link it with your application.
  29 Refer to the UST documentation for the
  30 advantages and disadvantage of each form.
  31 To compile the resulting .c file, you need to add the options
  32 "\-llttng-ust \-I.".
  33 Note for C++ support: although an application instrumented with
  34 tracepoints can be compiled with g++, tracepoint probes should be
  35 compiled with gcc (only tested with gcc so far).
  36
  37 .SH "OPTIONS"
  38
  39 .PP
  40 This program follow the usual GNU command line syntax with long options starting with
  41 two dashes. Below is a summary of the available options.
  42 .PP
  43
  44 .TP
  45 .BR "\-h, \-\-help"
  46 Show summary of possible options and commands.
  47 .TP
  48 .BR "\-v, \-\-verbose"
  49 Increase verbosity.
  50 .TP
  51 .BR "\-o, \-\-output"
  52 Specify the generated file. The type of the generated file depend on the file
  53 extension (.h, .c, .o).
  54 This option can be specfied multiple times to generate different file type.
  55
  56 .PP
  57 When no output is specified de default files are generated with the same base filename as the template file. The default files are: .h, .c, .o.
  58
  59 .SH "TEMPLATE FILE FORMAT"
  60
  61 The template file, which has the usual extension \fB.tp\fP, contains a list of
  62 TRACEPOINT_EVENT definitions and other optional definition entries like
  63 TRACEPOINT_LOGLEVEL.
  64 (See lttng-ust(3) for the complete list of available definition.)
  65
  66 You write them as you would write them in a C header file. You can add
  67 comments with \fB/* */\fP, \fB//\fP and \fB#\fP.
  68
  69 The provider name (the first field of TRACEPOINT_EVENT) must be
  70 the same for the whole file.
  71
  72 .TP
  73 .SH "Example"
  74 .TP
  75 .nf
  76 TRACEPOINT_EVENT(
  77     sample_tracepoint,
  78     message, // Comment
  79     TP_ARGS(char *, text),
  80     /* Next are the fields */
  81     TP_FIELDS(
  82         ctf_string(message, text)
  83     )
  84 )
  85 .SH "ENVIRONMENT VARIABLES"
  86
  87 .PP
  88 When the tool generate an .o file, it will look for the following environment variables
  89 .PP
  90
  91 .PP
  92 .IP "CC"
  93 Specifer which C compiler to use. If the variable is not specified, the
  94 tool will try "cc" and "gcc"
  95
  96 .IP "CFLAGS"
  97 Flags directly passed to the compiler
  98 .SH "SEE ALSO"
  99
 100 .PP
 101 lttng-ust(3), lttng(1)
 102 .PP
 103 .SH "BUGS"
 104
 105 .PP
 106 If you encounter any issues or usability problem, please report it on our
 107 mailing list <lttng-dev@lists.lttng.org> to help improve this project.
 108 .SH "CREDITS"
 109
 110 .PP
 111 lttng\-gen\-tp is distributed under the GNU General Public License version 2. See the file
 112 COPYING for details.
 113 .PP
 114 A Web site is available at http://lttng.org for more information on the LTTng
 115 project.
 116 .PP
 117 You can also find our git tree at http://git.lttng.org.
 118 .PP
 119 Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
 120 .PP
 121 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
 122 .PP
 123 .SH "AUTHORS"
 124
 125 .PP
 126 lttng\-gen\-tp is written by Yannick Brosseau <yannick.brosseau@gmail.com>.
 127 .PP