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, `TRACEPOINT_CREATE_PROBES` and `TRACEPOINT_DEFINE` must be
  43 defined in one, **and only one**, translation unit. Other C source
  44 files of the same application may include `tp.h` to use tracepoints
  45 with `tracepoint()`, but must not define
  46 `TRACEPOINT_CREATE_PROBES`/`TRACEPOINT_DEFINE` again.
  47
  48 This translation unit may be built as an object file by making sure to
  49 add `.` to the include path:
  50
  51 <pre class="term">
  52 gcc -c <strong>-I.</strong> file.c
  53 </pre>
  54
  55 The second approach is to isolate the tracepoint provider code into a
  56 separate object file by using a dedicated C source file to create probes:
  57
  58 ~~~ c
  59 #define TRACEPOINT_CREATE_PROBES
  60
  61 #include "tp.h"
  62 ~~~
  63
  64 `TRACEPOINT_DEFINE` must be defined by a translation unit of the
  65 application. Since we're talking about static linking here, it could as
  66 well be defined in the file above, before `#include "tp.h"`. This is
  67 actually what [`lttng-gen-tp`](#doc-lttng-gen-tp) does.
  68
  69 Build the tracepoint provider:
  70
  71 <pre class="term">
  72 gcc -c -I. tp.c
  73 </pre>
  74
  75 Finally, the resulting object file may be archived to create a
  76 more portable tracepoint provider static library:
  77
  78 <pre class="term">
  79 ar rc tp.a tp.o
  80 </pre>
  81
  82 Using a static library does have the advantage of centralising the
  83 tracepoint providers objects so they can be shared between multiple
  84 applications. This way, when the tracepoint provider is modified, the
  85 source code changes don't have to be patched into each application's source
  86 code tree. The applications need to be relinked after each change, but need
  87 not to be otherwise recompiled (unless the tracepoint provider's API
  88 changes).
  89
  90 Regardless of which method you choose, you end up with an object file
  91 (potentially archived) containing the trace providers assembled code.
  92 To link this code with the rest of your application, you must also link
  93 with `liblttng-ust` and `libdl`:
  94
  95 <pre class="term">
  96 gcc -o app <strong>tp.o</strong> other.o files.o of.o your.o app.o <strong>-llttng-ust -ldl</strong>
  97 </pre>
  98
  99 or
 100
 101 <pre class="term">
 102 gcc -o app <strong>tp.a</strong> other.o files.o of.o your.o app.o -llttng-ust -ldl
 103 </pre>
 104
 105 If you're using a <abbr title="Berkeley Software Distribution">BSD</abbr>
 106 system, replace `-ldl` with `-lc`:
 107
 108 <pre class="term">
 109 gcc -o app tp.a other.o files.o of.o your.o app.o -llttng-ust <strong>-lc</strong>
 110 </pre>
 111
 112 The application can be started as usual, e.g.:
 113
 114 <pre class="term">
 115 ./app
 116 </pre>
 117
 118 The `lttng` command line tool can be used to
 119 [control tracing](#doc-controlling-tracing).