Fix: Mark libxml2 as a mandatory dependency
[lttng-tools.git] / README.md
1 LTTng-tools
2 ===========
3
4 LTTng-tools is a set of tools to control [LTTng](https://lttng.org/)
5 tracing. The project includes the LTTng session daemon, consumer damon
6 and relay daemon, as well as `liblttng-ctl`, a C library used to
7 communicate with the session daemon, and `lttng`, a command line
8 interface to `liblttng-ctl`.
9
10
11 Requirements and optional dependencies
12 --------------------------------------
13
14 The following items are _required_ to build and run LTTng-tools
15 components:
16
17 - **Linux kernel >= 2.6.27**: for `epoll()` support, at least this
18 version is needed. However, `poll()` is also supported by
19 configuring LTTng-tools with the `--disable-epoll` option. Using
20 that, the kernel version may probably be older, but we can't provide
21 any guarantee. Please let us know if you are able to go lower
22 without any problems.
23 - **[`liburcu`](http://urcu.so/) >= 0.8.0**: userspace RCU library,
24 by Mathieu Desnoyers and Paul E. McKenney.
25 - **`libpopt` >= 1.13**: command line arguments parsing library.
26 - Debian/Ubuntu package: `libpopt-dev`
27 - **`libuuid`**: universally unique ID library
28 - Debian/Ubuntu package: `uuid-dev`
29 - **`libxml2` >= 2.7.6**: XML document parsing library. Needed for
30 tracing session configuration saving/loading and machine interface
31 output support.
32 - Debian/Ubuntu package: `libxml2-dev`
33
34
35 The following items are _optional_ dependencies:
36
37 - **[Babeltrace](https://lttng.org/babeltrace)**: trace viewer.
38 Enables the use of `lttng view` command.
39 - Debian/Ubuntu package: `babeltrace`
40 - **Perl**: needed for `make check` and tests.
41 - **Python >= 3.0**: needed for `make check` and tests.
42 - Debian/Ubuntu package: `python3`
43 - **SWIG >= 2.0** and **Python 3 development headers**: needed for
44 Python bindings
45 (enabled at configure time with the `--enable-python-bindings` option).
46 - Debian/Ubuntu packages: `swig2.0` and `python3-dev`
47 - **modprobe**: needed for automatic LTTng kernel modules loading
48 (kernel tracing).
49 - **bash**: needed for running `make check`.
50
51
52 Building
53 --------
54
55 This source tree is based on the Autotools suite from GNU to simplify
56 portability. Here are some things you should have on your system in
57 order to compile the Git repository tree:
58
59 - GNU Autotools (Automake >= 1.10, Autoconf >= 2.50,
60 Autoheader >= 2.50; make sure your system-wide `automake` points to
61 a recent version!)
62 - [GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2
63 - Flex >= 2.5.35
64 - Bison >= 2.4
65
66 If you use GNU gold, which is _not_ mandatory, make sure you have this
67 version:
68
69 - GNU gold >= 2.22
70
71 Before this version of GNU gold, we hit a
72 [known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317).
73 Be advised that with GNU gold, you might have to specify
74 `-L/usr/local/lib` in `LDFLAGS`.
75
76 If you get the tree from the Git repository, you will need to run
77
78 ./bootstrap
79
80 in its root. It calls all the GNU tools needed to prepare the tree
81 configuration.
82
83 To build LTTng-tools, do:
84
85 ./configure
86 make
87 sudo make install
88 sudo ldconfig
89
90 If you want Python bindings, add the `--enable-python-bindings` option
91 to `configure`. Please note that some distributions will need the
92 following environment variables set before running configure:
93
94 export PYTHON="python3"
95 export PYTHON_CONFIG="/usr/bin/python3-config"
96
97
98 Using
99 -----
100
101 Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started
102 with LTTng tracing. You can also use the `-h` or `--help` option of
103 any `lttng` command, e.g.:
104
105 lttng enable-event --help
106
107 A network streaming HOWTO can be found in
108 [`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly
109 helps you understand how to stream a LTTng 2.x trace.
110
111 A Python binding HOWTO can be found in
112 [`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you
113 understand how to use the Python module to control LTTng.
114
115
116 Contact
117 -------
118
119 Maintainer: [Jérémie Galarneau](mailto:jeremie.galarneau@efficios.com)
120
121 Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
122
123
124 Package contents
125 ----------------
126
127 This package contains the following elements:
128
129 - `doc`: LTTng-tools documentation.
130 - `include`: the public header files that will be installed on the system.
131 - `src/bin`: source code of LTTng-tools programs.
132 - `lttng-consumerd`: consumer daemon.
133 - `lttng-relayd`: relay daemon.
134 - `lttng-sessiond`: session daemon.
135 - `lttng`: command line interface for LTTng tracing control.
136 - `src/common`: common LTTng-tools source code.
137 - `compat`: compatibility library mostly for FreeBSD and Linux.
138 - `config`: tracing session configuration saving/loading.
139 - `hashtable`: library wrapper over Userspace RCU hashtables.
140 - `health`: health check subsytem.
141 - `index`: CTF index utilities.
142 - `kernel-consumer`: Linux kernel consumer.
143 - `kernel-ctl`: Linux kernel tracer control.
144 - `relayd`: relay daemon control.
145 - `sessiond-comm`: session daemon communication.
146 - `ust-consumer`: user space consumer.
147 - `src/lib`: source code of LTTng-tools libraries.
148 - `lttng-ctl`: LTTng control library.
149 - `tests`: various test programs.
This page took 0.034065 seconds and 6 git commands to generate.