Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
1 | --- |
2 | id: dynamic-linking | |
3 | --- | |
4 | ||
5 | The second approach to package the tracepoint providers is to use | |
6 | dynamic linking: the library and its member functions are explicitly | |
7 | sought, loaded and unloaded at runtime using `libdl`. | |
8 | ||
9 | It has to be noted that, for a variety of reasons, the created shared | |
10 | library will be dynamically _loaded_, as opposed to dynamically | |
11 | _linked_. The tracepoint provider shared object is, however, linked | |
12 | with `liblttng-ust`, so that `liblttng-ust` is guaranteed to be loaded | |
13 | as soon as the tracepoint provider is. If the tracepoint provider is | |
14 | not loaded, since the application itself is not linked with | |
15 | `liblttng-ust`, the latter is not loaded at all and the tracepoint calls | |
16 | become inert. | |
17 | ||
18 | The process to create the tracepoint provider shared object is pretty | |
19 | much the same as the static library method, except that: | |
20 | ||
21 | * since the tracepoint provider is not part of the application | |
22 | anymore, `TRACEPOINT_DEFINE` _must_ be defined in one translation | |
23 | unit (C source file) of the _application_; | |
24 | * `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next to | |
25 | `TRACEPOINT_DEFINE`. | |
26 | ||
27 | `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` makes the macros included afterwards | |
28 | (by including the tracepoint provider header, which itself includes | |
29 | LTTng-UST headers) aware that the tracepoint provider is to be loaded | |
30 | dynamically and not part of the application's executable. | |
31 | ||
32 | The tracepoint provider object file used to create the shared library | |
33 | is built like it is using the static library method, only with the | |
34 | `-fpic` option added: | |
35 | ||
36 | <pre class="term"> | |
37 | gcc -c <strong>-fpic</strong> -I. tp.c | |
38 | </pre> | |
39 | ||
40 | It is then linked as a shared library like this: | |
41 | ||
42 | <pre class="term"> | |
43 | gcc <strong>-shared -Wl,--no-as-needed -o tp.so -llttng-ust</strong> tp.o | |
44 | </pre> | |
45 | ||
46 | As previously stated, this tracepoint provider shared object isn't | |
47 | linked with the user application: it will be loaded manually. This is | |
48 | why the application is built with no mention of this tracepoint | |
49 | provider, but still needs `libdl`: | |
50 | ||
51 | <pre class="term"> | |
52 | gcc -o app other.o files.o of.o your.o app.o <strong>-ldl</strong> | |
53 | </pre> | |
54 | ||
55 | Now, to make LTTng-UST tracing available to the application, | |
56 | the `LD_PRELOAD` environment variable is used to preload the | |
57 | tracepoint provider shared library _before_ the application actually | |
58 | starts: | |
59 | ||
60 | <pre class="term"> | |
61 | <strong>LD_PRELOAD=/path/to/tp.so</strong> ./app | |
62 | </pre> | |
63 | ||
0cc03080 | 64 | Your application will still work without this preloading, albeit without |
5e0cbfb0 PP |
65 | LTTng-UST tracing support: |
66 | ||
67 | <pre class="term"> | |
68 | ./app | |
69 | </pre> |