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

   1 ---
   2 id: static-linking
   3 ---
   4
   5 With the static linking method, compiled tracepoint providers are copied
   6 into the target application. There are three ways to do this:
   7
   8   1. Use one of your **existing C source files** to create probes.
   9   2. Create probes in a separate C source file and build it as an
  10      **object file** to be linked with the application (more decoupled).
  11   3. Create probes in a separate C source file, build it as an
  12      object file and archive it to create a **static library**
  13      (more decoupled, more portable).
  14
  15 The first approach is to define `TRACEPOINT_CREATE_PROBES` and include
  16 your tracepoint provider(s) header file(s) directly into an existing C
  17 source file. Here's an example:
  18
  19 ~~~ c
  20 #include <stdlib.h>
  21 #include <stdio.h>
  22 /* ... */
  23
  24 #define TRACEPOINT_CREATE_PROBES
  25 #define TRACEPOINT_DEFINE
  26 #include "tp.h"
  27
  28 /* ... */
  29
  30 int my_func(int a, const char* b)
  31 {
  32     /* ... */
  33
  34     tracepoint(my_provider, my_tracepoint, buf, sz, limit, &tt)
  35
  36     /* ... */
  37 }
  38
  39 /* ... */
  40 ~~~
  41
  42 Again, before including a given tracepoint provider header file,
  43 `TRACEPOINT_CREATE_PROBES` and `TRACEPOINT_DEFINE` must be defined in
  44 one, **and only one**, translation unit. Other C source files of the
  45 same application may include `tp.h` to use tracepoints with
  46 the `tracepoint()` macro, but must not define
  47 `TRACEPOINT_CREATE_PROBES`/`TRACEPOINT_DEFINE` again.
  48
  49 This translation unit may be built as an object file by making sure to
  50 add `.` to the include path:
  51
  52 <pre class="term">
  53 gcc -c <strong>-I.</strong> file.c
  54 </pre>
  55
  56 The second approach is to isolate the tracepoint provider code into a
  57 separate object file by using a dedicated C source file to create probes:
  58
  59 ~~~ c
  60 #define TRACEPOINT_CREATE_PROBES
  61
  62 #include "tp.h"
  63 ~~~
  64
  65 `TRACEPOINT_DEFINE` must be defined by a translation unit of the
  66 application. Since we're talking about static linking here, it could as
  67 well be defined directly in the file above, before `#include "tp.h"`:
  68
  69 ~~~ c
  70 #define TRACEPOINT_CREATE_PROBES
  71 #define TRACEPOINT_DEFINE
  72
  73 #include "tp.h"
  74 ~~~
  75
  76 This is actually what [`lttng-gen-tp`](#doc-lttng-gen-tp) does, and is
  77 the recommended practice.
  78
  79 Build the tracepoint provider:
  80
  81 <pre class="term">
  82 gcc -c -I. tp.c
  83 </pre>
  84
  85 Finally, the resulting object file may be archived to create a
  86 more portable tracepoint provider static library:
  87
  88 <pre class="term">
  89 ar rc tp.a tp.o
  90 </pre>
  91
  92 Using a static library does have the advantage of centralising the
  93 tracepoint providers objects so they can be shared between multiple
  94 applications. This way, when the tracepoint provider is modified, the
  95 source code changes don't have to be patched into each application's source
  96 code tree. The applications need to be relinked after each change, but need
  97 not to be otherwise recompiled (unless the tracepoint provider's API
  98 changes).
  99
 100 Regardless of which method you choose, you end up with an object file
 101 (potentially archived) containing the trace providers assembled code.
 102 To link this code with the rest of your application, you must also link
 103 with `liblttng-ust` and `libdl`:
 104
 105 <pre class="term">
 106 gcc -o app <strong>tp.o</strong> other.o files.o of.o your.o app.o <strong>-llttng-ust -ldl</strong>
 107 </pre>
 108
 109 or
 110
 111 <pre class="term">
 112 gcc -o app <strong>tp.a</strong> other.o files.o of.o your.o app.o -llttng-ust -ldl
 113 </pre>
 114
 115 If you're using a <abbr title="Berkeley Software Distribution">BSD</abbr>
 116 system, replace `-ldl` with `-lc`:
 117
 118 <pre class="term">
 119 gcc -o app tp.a other.o files.o of.o your.o app.o -llttng-ust <strong>-lc</strong>
 120 </pre>
 121
 122 The application can be started as usual, for example:
 123
 124 <pre class="term">
 125 ./app
 126 </pre>
 127
 128 The `lttng` command line tool can be used to
 129 [control tracing](#doc-controlling-tracing).