5 With the static linking method, compiled tracepoint providers are copied
6 into the target application. There are three ways to do this:
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).
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:
24 #define TRACEPOINT_CREATE_PROBES
25 #define TRACEPOINT_DEFINE
30 int my_func(int a, const char* b)
34 tracepoint(my_provider, my_tracepoint, buf, sz, limit, &tt)
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.
49 This translation unit may be built as an object file by making sure to
50 add `.` to the include path:
53 gcc -c <strong>-I.</strong> file.c
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:
60 #define TRACEPOINT_CREATE_PROBES
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"`:
70 #define TRACEPOINT_CREATE_PROBES
71 #define TRACEPOINT_DEFINE
76 This is actually what [`lttng-gen-tp`](#doc-lttng-gen-tp) does, and is
77 the recommended practice.
79 Build the tracepoint provider:
85 Finally, the resulting object file may be archived to create a
86 more portable tracepoint provider static library:
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
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`:
106 gcc -o app <strong>tp.o</strong> other.o files.o of.o your.o app.o <strong>-llttng-ust -ldl</strong>
112 gcc -o app <strong>tp.a</strong> other.o files.o of.o your.o app.o -llttng-ust -ldl
115 If you're using a <abbr title="Berkeley Software Distribution">BSD</abbr>
116 system, replace `-ldl` with `-lc`:
119 gcc -o app tp.a other.o files.o of.o your.o app.o -llttng-ust <strong>-lc</strong>
122 The application can be started as usual, for example:
128 The `lttng` command line tool can be used to
129 [control tracing](#doc-controlling-tracing).