1 // Render with Asciidoctor
19 https://ci.lttng.org/job/lttng-tools_master_linuxbuild/[image:https://img.shields.io/jenkins/build.svg?jobUrl=https://ci.lttng.org/job/lttng-tools_master_linuxbuild/[Jenkins, title="Jenkins"]]
20 https://scan.coverity.com/projects/lttng-tools[image:https://img.shields.io/coverity/scan/lttng-tools.svg[Coverity, title="Coverity"]]
23 _**{lt}**_ is a set of components to control https://lttng.org/[LTTng]
28 * The LTTng https://lttng.org/man/8/lttng-sessiond/[session daemon].
30 * The LTTng consumer daemon.
32 * The LTTng https://lttng.org/man/8/lttng-relayd/[relay daemon].
34 * {lib}, a library with a C{nbsp}API used to communicate with
37 * Python{nbsp}3 bindings of liblttng{nbh}ctl.
39 * https://lttng.org/man/1/lttng/[`lttng`], a command-line tool over
42 * https://lttng.org/man/1/lttng-crash/[`lttng{nbh}crash`], a command-line
43 tool to recover and view LTTng{nbsp}2 trace buffers in the event of a
50 == Required and optional dependencies
52 You need the following dependencies to build and run the {lt}
55 * **Linux kernel{nbsp}≥{nbsp}2.6.30**
57 * **http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.14.0**.
59 Debian/Ubuntu package: `liburcu{nbh}dev`.
61 * **popt{nbsp}≥{nbsp}1.13**
63 Debian/Ubuntu package: `libpopt{nbh}dev`.
65 * **http://xmlsoft.org/[Libxml2]{nbsp}≥{nbsp}2.7.6**
67 Debian/Ubuntu package: `libxml2{nbh}dev`
69 The following dependencies are optional:
71 * **https://babeltrace.org/[Babeltrace{nbsp}2]**: default viewer
72 of the https://lttng.org/man/1/lttng-view/[`lttng view`] command,
73 `make{nbsp}check` and tests.
75 Debian/Ubuntu package: `babeltrace2 libbabeltrace2-dev`
77 * **https://lttng.org/[LTTng{nbh}UST]** (same minor version as {lt}):
78 LTTng user space tracing (applications and libraries).
80 Debian/Ubuntu package: `liblttng{nbh}ust{nbh}dev`
82 * **https://www.python.org/[Python]{nbsp}≥{nbsp}3.4**:
83 `make{nbsp}check` and tests.
85 Debian/Ubuntu package: `python3`
87 * **http://www.swig.org/[SWIG]{nbsp}≥{nbsp}2.0** and
88 **Python{nbsp}3 development headers**: Python bindings
89 (enabled at <<configure,build configuration>> time with the
90 `{nbh}{nbh}enable{nbh}python{nbh}bindings` option).
92 Debian/Ubuntu packages: `swig2.0` and `python3{nbh}dev`
95 **https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/[kmod]{nbsp}≥{nbsp}22**:
96 automatic LTTng kernel modules loading (kernel tracing).
98 * **Bash**: `make{nbsp}check`.
100 * **http://man7.org/linux/man-pages/man1/man.1.html[`man`]**
101 (manual pager): view `lttng` command manual
102 pages with the `{nbh}{nbh}help` option or with the
103 https://lttng.org/man/1/lttng-help/[`lttng{nbsp}help`] command.
105 NOTE: You can use the <<configure,build configuration>> option
106 `{nbh}{nbh}enable{nbh}embedded{nbh}help` to embed the manual pages into
107 the `lttng`, `lttng{nbh}sessiond`, `lttng{nbh}relayd`, and
108 `lttng{nbh}crash` programs so that you don't need `man` to view them.
110 * **http://perfmon2.sourceforge.net/[libpfm]{nbsp}≥{nbsp}4.0**:
111 perf regression test suite.
113 Debian/Ubuntu package: `libpfm4-dev`
115 {lt} supports both the LTTng Linux kernel tracer and LTTng user space
116 tracer sharing the same _minor_ version. While some minor releases do
117 not change the tracer ABIs and _could_ work, no testing is performed to
118 ensure that cross-version compatibility is maintained.
120 You don't need to rebuild or modify applications instrumented with older
121 versions of the LTTng{nbh}UST project to make them work with the
122 components of the latest {lt} release.
124 See the https://lttng.org/docs/[LTTng Documentation] for more
125 information on versioning.
131 You need the following tools to build {lt}:
133 * **https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html[GNU{nbsp}Autotools]**
134 (**Automake{nbsp}≥{nbsp}1.12**,
135 **Autoconf{nbsp}≥{nbsp}2.64**, and **Autoheader{nbsp}≥{nbsp}2.50**)
137 * **http://www.gnu.org/software/autoconf/[GNU{nbsp}Libtool]{nbsp}≥{nbsp}2.2**
139 * **https://github.com/westes/flex/[Flex]{nbsp}≥{nbsp}2.5.35**
141 * **https://www.gnu.org/software/bison/[Bison]{nbsp}≥{nbsp}2.4**
143 To build the {lt} manual pages:
145 * **https://asciidoc.org/[AsciiDoc]{nbsp}≥{nbsp}8.4.5**
147 NOTE: Previous versions could work, but were not tested.
149 * **https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.21**
151 NOTE: Previous versions could work, but were not tested.
153 If you use GNU{nbsp}gold, which is _not_ mandatory:
155 * **GNU{nbsp}gold{nbsp}≥{nbsp}2.22**
157 NOTE: With GNU{nbsp}gold, you might need to add
158 `-L/usr/local/lib` to the `LDFLAGS` environment variable.
162 . **If you have the {lt} Git source**, run:
168 This script creates the `configure` script.
170 . [[configure]]Configure the build:
177 If you want the {lib} Python bindings, use the
178 `{nbh}{nbh}enable{nbh}python{nbh}bindings` option. See also the `PYTHON`
179 and `PYTHON_CONFIG` environment variables in
180 `./configure{nbsp}{nbh}{nbh}help`.
182 If you don't want to build the manual pages, use the
183 `{nbh}{nbh}disable{nbh}man{nbh}pages` option.
185 If you want to embed the manual pages into the `lttng`,
186 `lttng{nbh}sessiond`, `lttng{nbh}relayd`, and `lttng{nbh}crash` programs
187 so that you don't need `man` to view them, use the
188 `{nbh}{nbh}enable{nbh}embedded{nbh}help` option.
190 This build configuration script finds LTTng{nbh}UST with
191 https://www.freedesktop.org/wiki/Software/pkg-config/[pkg{nbh}config]:
192 set the `PKG_CONFIG_PATH` environment variable accordingly if
193 pkg{nbh}config cannot find the `lttng{nbh}ust` package information.
195 See `./configure{nbsp}{nbh}{nbh}help` for the complete list of options.
204 . Install the project:
213 See the https://lttng.org/docs/#doc-controlling-tracing[Tracing control]
214 section of the LTTng Documentation to learn how to use the {lt}
217 See also the https://lttng.org/man/[LTTng manual pages] (all
218 section{nbsp}1 and{nbsp}8 pages).
220 As there's no official {lib} Python bindings yet, see
221 link:doc/python-howto.txt[`doc/python-howto.txt`] to understand how to
224 == Supported versions
226 The LTTng project supports the last two released stable versions
227 (e.g. stable-2.13 and stable-2.12).
229 Fixes are backported from the master branch to the last stable version unless
230 those fixes would break the ABI or API. Those fixes may be backported to the
231 second-last stable version, depending on complexity and ABI/API compatibility.
233 Security fixes are backported from the master branch to both of the last stable
234 version and the second-last stable version.
236 New features are integrated into the master branch and not backported to the
242 https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
243 (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org])
246 irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
249 https://bugs.lttng.org/projects/lttng-tools[{lt} bug tracker]
252 https://github.com/lttng/lttng-tools/[lttng/lttng{nbh}tools]
254 Continuous integration::
255 https://ci.lttng.org/job/lttng-tools_master_build/[{lt}'s master build]
259 https://review.lttng.org/q/project:lttng-tools[_lttng{nbh}tools_ project]
262 Contributor's guide::
263 https://github.com/lttng/lttng-tools/blob/master/CONTRIBUTING.md