Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
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 | ||
cd41f97c PP |
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 | |
5e0cbfb0 PP |
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 | |
cd41f97c PP |
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. | |
5e0cbfb0 PP |
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 | ||
4d46e8c0 | 122 | The application can be started as usual, for example: |
5e0cbfb0 PP |
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). |