docs: Add supported versions and fix-backport policy
[lttng-tools.git] / README.adoc
1 // Render with Asciidoctor
2
3 :nbh: ‑
4 :lt: LTTng{nbh}tools
5 :lib: liblttng{nbh}ctl
6
7 ifdef::env-github[]
8 :toc: macro
9 endif::env-github[]
10
11 ifndef::env-github[]
12 :toc: left
13 endif::env-github[]
14
15 = {lt}
16 5 May 2020
17
18 [.normal]
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"]]
21
22 [.lead]
23 _**{lt}**_ is a set of components to control https://lttng.org/[LTTng]
24 tracing.
25
26 The project includes:
27
28 * The LTTng https://lttng.org/man/8/lttng-sessiond/[session daemon].
29
30 * The LTTng consumer daemon.
31
32 * The LTTng https://lttng.org/man/8/lttng-relayd/[relay daemon].
33
34 * {lib}, a library with a C{nbsp}API used to communicate with
35 the session daemon.
36
37 * Python{nbsp}3 bindings of liblttng{nbh}ctl.
38
39 * https://lttng.org/man/1/lttng/[`lttng`], a command-line tool over
40 {lib}.
41
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
44 crash.
45
46 ifdef::env-github[]
47 toc::[]
48 endif::env-github[]
49
50 == Required and optional dependencies
51
52 You need the following dependencies to build and run the {lt}
53 components:
54
55 * **Linux kernel{nbsp}≥{nbsp}2.6.30**
56
57 * **http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.14.0**.
58 +
59 Debian/Ubuntu package: `liburcu{nbh}dev`.
60
61 * **popt{nbsp}≥{nbsp}1.13**
62 +
63 Debian/Ubuntu package: `libpopt{nbh}dev`.
64
65 * **http://xmlsoft.org/[Libxml2]{nbsp}≥{nbsp}2.7.6**
66 +
67 Debian/Ubuntu package: `libxml2{nbh}dev`
68
69 The following dependencies are optional:
70
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.
74 +
75 Debian/Ubuntu package: `babeltrace2 libbabeltrace2-dev`
76
77 * **https://lttng.org/[LTTng{nbh}UST]** (same minor version as {lt}):
78 LTTng user space tracing (applications and libraries).
79 +
80 Debian/Ubuntu package: `liblttng{nbh}ust{nbh}dev`
81
82 * **https://www.python.org/[Python]{nbsp}≥{nbsp}3.4**:
83 `make{nbsp}check` and tests.
84 +
85 Debian/Ubuntu package: `python3`
86
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).
91 +
92 Debian/Ubuntu packages: `swig2.0` and `python3{nbh}dev`
93
94 * **modprobe** and/or
95 **https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/[kmod]{nbsp}≥{nbsp}22**:
96 automatic LTTng kernel modules loading (kernel tracing).
97
98 * **Bash**: `make{nbsp}check`.
99
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.
104 +
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.
109
110 * **http://perfmon2.sourceforge.net/[libpfm]{nbsp}≥{nbsp}4.0**:
111 perf regression test suite.
112 +
113 Debian/Ubuntu package: `libpfm4-dev`
114
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.
119
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.
123
124 See the https://lttng.org/docs/[LTTng Documentation] for more
125 information on versioning.
126
127 == Build from source
128
129 === Dependencies
130
131 You need the following tools to build {lt}:
132
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**)
136
137 * **http://www.gnu.org/software/autoconf/[GNU{nbsp}Libtool]{nbsp}≥{nbsp}2.2**
138
139 * **https://github.com/westes/flex/[Flex]{nbsp}≥{nbsp}2.5.35**
140
141 * **https://www.gnu.org/software/bison/[Bison]{nbsp}≥{nbsp}2.4**
142
143 To build the {lt} manual pages:
144
145 * **https://asciidoc.org/[AsciiDoc]{nbsp}≥{nbsp}8.4.5**
146 +
147 NOTE: Previous versions could work, but were not tested.
148
149 * **https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.21**
150 +
151 NOTE: Previous versions could work, but were not tested.
152
153 If you use GNU{nbsp}gold, which is _not_ mandatory:
154
155 * **GNU{nbsp}gold{nbsp}≥{nbsp}2.22**
156
157 NOTE: With GNU{nbsp}gold, you might need to add
158 `-L/usr/local/lib` to the `LDFLAGS` environment variable.
159
160 === Build steps
161
162 . **If you have the {lt} Git source**, run:
163 +
164 ----
165 $ ./bootstrap
166 ----
167 +
168 This script creates the `configure` script.
169
170 . [[configure]]Configure the build:
171 +
172 --
173 ----
174 $ ./configure
175 ----
176
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`.
181
182 If you don't want to build the manual pages, use the
183 `{nbh}{nbh}disable{nbh}man{nbh}pages` option.
184
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.
189
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.
194
195 See `./configure{nbsp}{nbh}{nbh}help` for the complete list of options.
196 --
197
198 . Build the project:
199 +
200 ----
201 $ make
202 ----
203
204 . Install the project:
205 +
206 ----
207 $ sudo make install
208 $ sudo ldconfig
209 ----
210
211 == Usage
212
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}
215 components.
216
217 See also the https://lttng.org/man/[LTTng manual pages] (all
218 section{nbsp}1 and{nbsp}8 pages).
219
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
222 use them.
223
224 == Supported versions
225
226 The LTTng project supports the last two released stable versions
227 (e.g. stable-2.13 and stable-2.12).
228
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.
232
233 Security fixes are backported from the master branch to both of the last stable
234 version and the second-last stable version.
235
236 New features are integrated into the master branch and not backported to the
237 last stable branch.
238
239 == Community
240
241 Mailing list::
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])
244
245 IRC channel::
246 irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
247
248 Bug tracker::
249 https://bugs.lttng.org/projects/lttng-tools[{lt} bug tracker]
250
251 GitHub project::
252 https://github.com/lttng/lttng-tools/[lttng/lttng{nbh}tools]
253
254 Continuous integration::
255 https://ci.lttng.org/job/lttng-tools_master_build/[{lt}'s master build]
256 on LTTng's CI
257
258 Code review::
259 https://review.lttng.org/q/project:lttng-tools[_lttng{nbh}tools_ project]
260 on LTTng Review
261
262 Contributor's guide::
263 https://github.com/lttng/lttng-tools/blob/master/CONTRIBUTING.md
This page took 0.036028 seconds and 4 git commands to generate.