contents/using-lttng/instrumenting/c-application/building-linking/intro.md

   1 ---
   2 id: building-tracepoint-providers-and-user-application
   3 ---
   4
   5 This section explains the final step of using LTTng-UST for tracing
   6 a user space C application (beside running the application): building and
   7 linking tracepoint providers and the application itself.
   8
   9 As discussed above, the macros used by the user-written tracepoint provider
  10 header file are useless until actually used to create probes code
  11 (global data structures and functions) in a translation unit (C source file).
  12 This is accomplished by defining `TRACEPOINT_CREATE_PROBES` in a translation
  13 unit and then including the tracepoint provider header file.
  14 When `TRACEPOINT_CREATE_PROBES` is defined, macros used and included by
  15 the tracepoint provider header produce actual source code needed by any
  16 application using the defined tracepoints. Defining
  17 `TRACEPOINT_CREATE_PROBES` produces code used when registering
  18 tracepoint providers when the tracepoint provider package loads.
  19
  20 The other important definition is `TRACEPOINT_DEFINE`. This one creates
  21 global, per-tracepoint structures referencing the tracepoint providers
  22 data. Those structures are required by the actual functions inserted
  23 where `tracepoint()` macros are placed and need to be defined by the
  24 instrumented application.
  25
  26 Both `TRACEPOINT_CREATE_PROBES` and `TRACEPOINT_DEFINE` need to be defined
  27 at some places in order to trace a user space C application using LTTng.
  28 Although explaining their exact mechanism is beyond the scope of this
  29 document, the reason they both exist separately is to allow the trace
  30 providers to be packaged as a shared object (dynamically loaded library).
  31
  32 There are two ways to compile and link the tracepoint providers
  33 with the application: _[statically](#doc-static-linking)_ or
  34 _[dynamically](#doc-dynamic-linking)_. Both methods are covered in the
  35 following subsections.