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 | ||
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). |