Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
1 | --- |
2 | id: building-tracepoint-providers-and-user-application | |
3 | --- | |
4 | ||
5 | This section explains the final step of using LTTng-UST for tracing | |
6 | a user space C application (beside running the application): building and | |
7 | linking tracepoint providers and the application itself. | |
8 | ||
9 | As discussed above, the macros used by the user-written tracepoint provider | |
10 | header file are useless until actually used to create probes code | |
11 | (global data structures and functions) in a translation unit (C source file). | |
12 | This is accomplished by defining `TRACEPOINT_CREATE_PROBES` in a translation | |
13 | unit and then including the tracepoint provider header file. | |
14 | When `TRACEPOINT_CREATE_PROBES` is defined, macros used and included by | |
47bfcb75 | 15 | the tracepoint provider header produce actual source code needed by any |
5e0cbfb0 PP |
16 | application using the defined tracepoints. Defining |
17 | `TRACEPOINT_CREATE_PROBES` produces code used when registering | |
18 | tracepoint providers when the tracepoint provider package loads. | |
19 | ||
20 | The other important definition is `TRACEPOINT_DEFINE`. This one creates | |
21 | global, per-tracepoint structures referencing the tracepoint providers | |
22 | data. Those structures are required by the actual functions inserted | |
23 | where `tracepoint()` macros are placed and need to be defined by the | |
24 | instrumented application. | |
25 | ||
26 | Both `TRACEPOINT_CREATE_PROBES` and `TRACEPOINT_DEFINE` need to be defined | |
27 | at some places in order to trace a user space C application using LTTng. | |
28 | Although explaining their exact mechanism is beyond the scope of this | |
29 | document, the reason they both exist separately is to allow the trace | |
30 | providers to be packaged as a shared object (dynamically loaded library). | |
31 | ||
32 | There are two ways to compile and link the tracepoint providers | |
33 | with the application: _[statically](#doc-static-linking)_ or | |
34 | _[dynamically](#doc-dynamic-linking)_. Both methods are covered in the | |
35 | following subsections. |