sessiond: Replace uses of session_trylock_list by a dedicated assert macro
[lttng-tools.git] / README.adoc
CommitLineData
ae403e46
PP
1// Render with Asciidoctor
2
3:nbh: ‑
4:lt: LTTng{nbh}tools
5:lib: liblttng{nbh}ctl
6
7ifdef::env-github[]
8:toc: macro
9endif::env-github[]
10
11ifndef::env-github[]
12:toc: left
13endif::env-github[]
14
15= {lt}
165 May 2020
17
18[.normal]
19https://ci.lttng.org/job/lttng-tools_master_build/[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/lttng-tools_master_build.svg[Jenkins, title="Jenkins"]]
20https://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]
24tracing.
25
26The 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
46ifdef::env-github[]
47toc::[]
48endif::env-github[]
49
50== Required and optional dependencies
51
52You need the following dependencies to build and run the {lt}
53components:
54
8a880a84 55* **Linux kernel{nbsp}≥{nbsp}2.6.30**
ae403e46 56
87900062 57* **http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.11.0**.
ae403e46
PP
58+
59Debian/Ubuntu package: `liburcu{nbh}dev`.
60
61* **popt{nbsp}≥{nbsp}1.13**
62+
63Debian/Ubuntu package: `libpopt{nbh}dev`.
64
65* **http://xmlsoft.org/[Libxml2]{nbsp}≥{nbsp}2.7.6**
66+
67Debian/Ubuntu package: `libxml2{nbh}dev`
68
69The following dependencies are optional:
70
71* **https://babeltrace.org/[Babeltrace{nbsp}2]**: default viewer
c125de8f
FD
72 of the https://lttng.org/man/1/lttng-view/[`lttng view`] command,
73 `make{nbsp}check` and tests.
ae403e46
PP
74+
75Debian/Ubuntu package: `babeltrace2`
76
77* **https://lttng.org/[LTTng{nbh}UST]** (same minor version as {lt}):
78 LTTng user space tracing (applications and libraries).
79+
80Debian/Ubuntu package: `liblttng{nbh}ust{nbh}dev`
81
82* **Perl**: `make{nbsp}check` and tests.
83
84* **https://www.python.org/[Python]{nbsp}≥{nbsp}3.0**:
85 `make{nbsp}check` and tests.
86+
87Debian/Ubuntu package: `python3`
88
89* **http://www.swig.org/[SWIG]{nbsp}≥{nbsp}2.0** and
90 **Python{nbsp}3 development headers**: Python bindings
91 (enabled at <<configure,build configuration>> time with the
92 `{nbh}{nbh}enable{nbh}python{nbh}bindings` option).
93+
94Debian/Ubuntu packages: `swig2.0` and `python3{nbh}dev`
95
96* **modprobe** and/or
97 **https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/[kmod]{nbsp}≥{nbsp}22**:
98 automatic LTTng kernel modules loading (kernel tracing).
99
100* **Bash**: `make{nbsp}check`.
101
102* **http://man7.org/linux/man-pages/man1/man.1.html[`man`]**
103 (manual pager): view `lttng` command manual
104 pages with the `{nbh}{nbh}help` option or with the
105 https://lttng.org/man/1/lttng-help/[`lttng{nbsp}help`] command.
106+
107NOTE: You can use the <<configure,build configuration>> option
108`{nbh}{nbh}enable{nbh}embedded{nbh}help` to embed the manual pages into
109the `lttng`, `lttng{nbh}sessiond`, `lttng{nbh}relayd`, and
110`lttng{nbh}crash` programs so that you don't need `man` to view them.
111
112* **http://perfmon2.sourceforge.net/[libpfm]{nbsp}≥{nbsp}4.0**:
113 perf regression test suite.
114+
115Debian/Ubuntu package: `libpfm4-dev`
116
117{lt} supports both the LTTng Linux kernel tracer and LTTng user space
118tracer sharing the same _minor_ version. While some minor releases do
119not change the tracer ABIs and _could_ work, no testing is performed to
120ensure that cross-version compatibility is maintained.
121
122You don't need to rebuild or modify applications instrumented with older
123versions of the LTTng{nbh}UST project to make them work with the
124components of the latest {lt} release.
125
126See the https://lttng.org/docs/[LTTng Documentation] for more
127information on versioning.
128
129== Build from source
130
131=== Dependencies
132
133You need the following tools to build {lt}:
134
135* **https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html[GNU{nbsp}Autotools]**
136 (**Automake{nbsp}≥{nbsp}1.10**,
137 **Autoconf{nbsp}≥{nbsp}2.64**, and **Autoheader{nbsp}≥{nbsp}2.50**)
138
139* **http://www.gnu.org/software/autoconf/[GNU{nbsp}Libtool]{nbsp}≥{nbsp}2.2**
140
141* **https://github.com/westes/flex/[Flex]{nbsp}≥{nbsp}2.5.35**
142
143* **https://www.gnu.org/software/bison/[Bison]{nbsp}≥{nbsp}2.4**
144
145To build the {lt} manual pages:
146
147* **https://www.methods.co.nz/asciidoc/[AsciiDoc]{nbsp}≥{nbsp}8.4.5**
148+
149NOTE: Previous versions could work, but were not tested.
150
151* **https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.21**
152+
153NOTE: Previous versions could work, but were not tested.
154
155If you use GNU{nbsp}gold, which is _not_ mandatory:
156
157* **GNU{nbsp}gold{nbsp}≥{nbsp}2.22**
158
159NOTE: With GNU{nbsp}gold, you might need to add
160`-L/usr/local/lib` to the `LDFLAGS` environment variable.
161
162=== Build steps
163
164. **If you have the {lt} Git source**, run:
165+
166----
167$ ./bootstrap
168----
169+
170This script creates the `configure` script.
171
172. [[configure]]Configure the build:
173+
174--
175----
176$ ./configure
177----
178
179If you want the {lib} Python bindings, use the
180`{nbh}{nbh}enable{nbh}python{nbh}bindings` option. See also the `PYTHON`
181and `PYTHON_CONFIG` environment variables in
182`./configure{nbsp}{nbh}{nbh}help`.
183
184If you don't want to build the manual pages, use the
185`{nbh}{nbh}disable{nbh}man{nbh}pages` option.
186
187If you want to embed the manual pages into the `lttng`,
188`lttng{nbh}sessiond`, `lttng{nbh}relayd`, and `lttng{nbh}crash` programs
189so that you don't need `man` to view them, use the
190`{nbh}{nbh}enable{nbh}embedded{nbh}help` option.
191
ae403e46
PP
192This build configuration script finds LTTng{nbh}UST with
193https://www.freedesktop.org/wiki/Software/pkg-config/[pkg{nbh}config]:
194set the `PKG_CONFIG_PATH` environment variable accordingly if
195pkg{nbh}config cannot find the `lttng{nbh}ust` package information.
196
197See `./configure{nbsp}{nbh}{nbh}help` for the complete list of options.
198--
199
200. Build the project:
201+
202----
203$ make
204----
205
206. Install the project:
207+
208----
209$ sudo make install
210$ sudo ldconfig
211----
212
213== Usage
214
215See the https://lttng.org/docs/#doc-controlling-tracing[Tracing control]
216section of the LTTng Documentation to learn how to use the {lt}
217components.
218
219See also the https://lttng.org/man/[LTTng manual pages] (all
220section{nbsp}1 and{nbsp}8 pages).
221
222As there's no official {lib} Python bindings yet, see
223link:doc/python-howto.txt[`doc/python-howto.txt`] to understand how to
224use them.
225
226== Community
227
228Mailing list::
229 https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
230 (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org])
231
232IRC channel::
233 irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
234
235Bug tracker::
236 https://bugs.lttng.org/projects/lttng-tools[{lt} bug tracker]
237
238GitHub project::
239 https://github.com/lttng/lttng-tools/[lttng/lttng{nbh}tools]
240
241Continuous integration::
242 https://ci.lttng.org/job/lttng-tools_master_build/[{lt}'s master build]
243 on LTTng's CI
244
245Code review::
246 https://review.lttng.org/q/project:lttng-tools[_lttng{nbh}tools_ project]
247 on LTTng Review
This page took 0.038364 seconds and 4 git commands to generate.