From adf4e918ebd23dd313553f0b11753f8d6b369d9e Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Wed, 17 Sep 2014 15:33:10 -0400 Subject: [PATCH] Modernize README with Markdown This commit also: * adds a project description at the top * fixes a few grammar mistakes here and there * updates the Package contents list Signed-off-by: Philippe Proulx Signed-off-by: David Goulet --- INSTALL | 8 +- README | 187 ---------------------------------------- README.md | 148 +++++++++++++++++++++++++++++++ doc/quickstart.txt | 2 +- doc/streaming-howto.txt | 2 +- 5 files changed, 154 insertions(+), 193 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/INSTALL b/INSTALL index 7d1c323be..e146eab3d 100644 --- a/INSTALL +++ b/INSTALL @@ -14,7 +14,7 @@ Basic Installation Briefly, the shell commands `./configure; make; make install' should configure, build, and install this package. The following -more-detailed instructions are generic; see the `README' file for +more-detailed instructions are generic; see the `README.md' file for instructions specific to this package. Some packages provide this `INSTALL' file but do not implement all of the features documented below. The lack of an optional feature in a given package is not @@ -38,7 +38,7 @@ cache files. If you need to do unusual things to compile the package, please try to figure out how `configure' could check whether to do them, and mail -diffs or instructions to the address given in the `README' so they can +diffs or instructions to the address given in the `README.md' so they can be considered for the next release. If you are using the cache, and at some point `config.cache' contains results you don't want to keep, you may remove or edit it. @@ -200,8 +200,8 @@ option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. `configure', where FEATURE indicates an optional part of the package. They may also pay attention to `--with-PACKAGE' options, where PACKAGE is something like `gnu-as' or `x' (for the X Window System). The -`README' should mention any `--enable-' and `--with-' options that the -package recognizes. +`README.md' should mention any `--enable-' and `--with-' options that +the package recognizes. For packages that use the X Window System, `configure' can usually find the X include and library files automatically, but if it doesn't, diff --git a/README b/README deleted file mode 100644 index 43fd0c5cb..000000000 --- a/README +++ /dev/null @@ -1,187 +0,0 @@ -LTTng Trace Control ----------------- - -Please visit https://lttng.org for more information. The current maintainer is -David Goulet . - -Latest development can be found at: - - * Gitweb : https://git.lttng.org/?p=lttng-tools.git;a=summary - * Git : git://git.lttng.org/lttng-tools.git - -REQUIREMENTS: - - - Linux kernel >= 2.6.27 - For epoll() support, at least this version is needed. However, poll() is - also supported by running "./configure --disable-epoll". Using that, the - kernel version can probably be older but we can't provide any guarantee. - Please let us know if you are able to go lower without any problems. - - - liburcu >= 0.8.0 - Userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney - - -> Tested with liburcu 0.8.x stable. - - * Debian/Ubuntu package: liburcu-dev - * Git : git://git.lttng.org/userspace-rcu.git - * Website: https://lttng.org/urcu - - - libpopt >= 1.13 - Library for parsing command line parameters - - * Debian/Ubuntu package: libpopt-dev - - - libuuid - Universally unique id library - - * Debian/Ubuntu package: uuid-dev - - - Babeltrace (optional) - Trace viewer. Enable the use of "lttng view" command - - * Debian/Ubuntu package: babeltrace - - - libxml2 >= 2.7.6 - XML document parsing library. - - * Debian/Ubuntu package: libxml2-dev - - - Perl (optional) - Needed for make check and tests. - - - Python >= 3.0 (optional) - Needed for make check and tests. - - * Debian/Ubuntu package: python3 - - - SWIG >= 2.0 (optional) - Needed for Python bindings (--enable-python-bindings). - - * Debian/Ubuntu package: swig2.0 - - - python-dev (optional) - Python headers - - * Debian/Ubuntu package: python3-dev - - - For kernel tracing: modprobe - - - bash - Needed for running "make check". - -For developers using the git tree: - -This source tree is based on the autotools suite from GNU to simplify -portability. Here are some things you should have on your system in order to -compile the git repository tree : - -- GNU autotools (automake >=1.10, autoconf >=2.50, autoheader >=2.50) - (make sure your system wide "automake" points to a recent version!) -- GNU Libtool >=2.2 - (for more information, go to https://www.gnu.org/software/autoconf/) -- flex >= 2.5.35 -- bison >= 2.4 - -If you use GNU gold, which is NOT mandatory, make sure you have this version: -- GNU gold >= 2.22 -(Before this version we hit a known bug documented at: - http://sourceware.org/bugzilla/show_bug.cgi?id=11317) -Be advise that with GNU gold, you'll might have to specify -L/usr/local/lib in -LDFLAGS. - -If you get the tree from the repository, you will need to use the "bootstrap" -script in the root of the tree. It calls all the GNU tools needed to prepare -the tree configuration. - -INSTALLATION INSTRUCTIONS: - - - Download, compile and install the prerequisites. - Then: - $ ./boostrap - $ ./configure - $ make - $ sudo make install - $ sudo ldconfig - - If compiling from the git repository, run ./bootstrap before running - the configure script, to generate it. - - If you want Python bindings, run ./configure --enable-python-bindings. - Please note that some distributions will need the following - environment variables set before running configure: - - export PYTHON="python3" - export PYTHON_CONFIG="/usr/bin/python3-config" - -USAGE: - -Please see doc/quickstart.txt to help you start tracing. You can also use the --h/--help command on 'lttng' and all other commands offered in this tool (Ex: -lttng enable-event -h). - -A network streaming HOWTO can be found in doc/streaming-howto.txt which quickly -helps you understand how to stream a LTTng 2.0 trace. - -A Python HOWTO can be found in doc/python-howto.txt which quickly -helps you understand how to use the Python module to control the LTTng API. - -PACKAGE CONTENTS: - - This package contains the following elements: - - - liblttng-ctl (public API) - The LTTng tracing control library. - - - libsessiond-comm (internal) - The lttng-sessiond communication library. In order to talk with - lttng-sessiond, this library must be used. - - - libkernel-ctl (internal) - Kernel tracer control and ioctl definitions. - - - libconsumer (internal) - Library for Kernel and (optionally) UST trace consumer. - - - libkernel-consumer (internal) - Library for Kernel consumer control - - - libust-consumer (internal) - Library for UST consumer control - - - libhashtable (internal) - Library wrapper over URCU hashtables. - - - libcommon (internal) - Contains multiple useful function call used by the whole tree. - - - libcompat (internal) - Compatibility library mostly for FreeBSD and Linux. - - - librelayd (internal) - Library for all relayd interactions over the network. - - - lttng-relayd - The relay daemon used for network streaming - - - lttng-consumerd - The consumer daemon which uses libconsumer. - - - lttng-sessiond - The LTTng session daemon binary. - - - lttng - The LTTng tracer command line control tool. - - - include (installed in $(includedir)/lttng/) - The liblttngctl API header file. - - - tests - Various test programs. - - - doc - Various documentations and quickstart guide. - - - extras - Contains extra data such as bash completion file. - Note: the presence of xmllint is required for bash-completion. - Python bindings for liblttng-ctl are also available there. diff --git a/README.md b/README.md new file mode 100644 index 000000000..daeb740f0 --- /dev/null +++ b/README.md @@ -0,0 +1,148 @@ +LTTng-tools +=========== + +LTTng-tools is a set of tools to control [LTTng](https://lttng.org/) +tracing. The project includes the LTTng session daemon, consumer damon +and relay daemon, as well as `liblttng-ctl`, a C library used to +communicate with the session daemon, and `lttng`, a command line +interface to `liblttng-ctl`. + + +Requirements and optional dependencies +-------------------------------------- + +The following items are _required_ to build and run LTTng-tools +components: + + - **Linux kernel >= 2.6.27**: for `epoll()` support, at least this + version is needed. However, `poll()` is also supported by + configuring LTTng-tools with the `--disable-epoll` option. Using + that, the kernel version may probably be older, but we can't provide + any guarantee. Please let us know if you are able to go lower + without any problems. + - **[`liburcu`](http://urcu.so/) >= 0.8.0**: userspace RCU library, + by Mathieu Desnoyers and Paul E. McKenney. + - **`libpopt` >= 1.13**: command line arguments parsing library. + - Debian/Ubuntu package: `libpopt-dev` + - **`libuuid`**: universally unique ID library + - Debian/Ubuntu package: `uuid-dev` + +The following items are _optional_ dependencies: + + - **[Babeltrace](https://lttng.org/babeltrace)**: trace viewer. + Enables the use of `lttng view` command. + - Debian/Ubuntu package: `babeltrace` + - **`libxml2` >= 2.7.6**: XML document parsing library. Needed for + tracing session configuration saving/loading and machine interface + output support. + - Debian/Ubuntu package: `libxml2-dev` + - **Perl**: needed for `make check` and tests. + - **Python >= 3.0**: needed for `make check` and tests. + - Debian/Ubuntu package: `python3` + - **SWIG >= 2.0** and **Python 3 development headers**: needed for + Python bindings + (enabled at configure time with the `--enable-python-bindings` option). + - Debian/Ubuntu packages: `swig2.0` and `python3-dev` + - **modprobe**: needed for automatic LTTng kernel modules loading + (kernel tracing). + - **bash**: needed for running `make check`. + + +Building +-------- + +This source tree is based on the Autotools suite from GNU to simplify +portability. Here are some things you should have on your system in +order to compile the Git repository tree: + + - GNU Autotools (Automake >= 1.10, Autoconf >= 2.50, + Autoheader >= 2.50; make sure your system-wide `automake` points to + a recent version!) + - [GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2 + - Flex >= 2.5.35 + - Bison >= 2.4 + +If you use GNU gold, which is _not_ mandatory, make sure you have this +version: + + - GNU gold >= 2.22 + +Before this version of GNU gold, we hit a +[known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317). +Be advised that with GNU gold, you might have to specify +`-L/usr/local/lib` in `LDFLAGS`. + +If you get the tree from the Git repository, you will need to run + + ./bootstrap + +in its root. It calls all the GNU tools needed to prepare the tree +configuration. + +To build LTTng-tools, do: + + ./configure + make + sudo make install + sudo ldconfig + +If you want Python bindings, add the `--enable-python-bindings` option +to `configure`. Please note that some distributions will need the +following environment variables set before running configure: + + export PYTHON="python3" + export PYTHON_CONFIG="/usr/bin/python3-config" + + +Using +----- + +Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started +with LTTng tracing. You can also use the `-h` or `--help` option of +any `lttng` command, e.g.: + + lttng enable-event --help + +A network streaming HOWTO can be found in +[`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly +helps you understand how to stream a LTTng 2.x trace. + +A Python binding HOWTO can be found in +[`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you +understand how to use the Python module to control LTTng. + + +Contact +------- + +Maintainer: [David Goulet](mailto:dgoulet@efficios.com) + +Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev) + + +Package contents +---------------- + +This package contains the following elements: + + - `doc`: LTTng-tools documentation. + - `include`: the public header files that will be installed on the system. + - `src/bin`: source code of LTTng-tools programs. + - `lttng-consumerd`: consumer daemon. + - `lttng-relayd`: relay daemon. + - `lttng-sessiond`: session daemon. + - `lttng`: command line interface for LTTng tracing control. + - `src/common`: common LTTng-tools source code. + - `compat`: compatibility library mostly for FreeBSD and Linux. + - `config`: tracing session configuration saving/loading. + - `hashtable`: library wrapper over Userspace RCU hashtables. + - `health`: health check subsytem. + - `index`: CTF index utilities. + - `kernel-consumer`: Linux kernel consumer. + - `kernel-ctl`: Linux kernel tracer control. + - `relayd`: relay daemon control. + - `sessiond-comm`: session daemon communication. + - `ust-consumer`: user space consumer. + - `src/lib`: source code of LTTng-tools libraries. + - `lttng-ctl`: LTTng control library. + - `tests`: various test programs. diff --git a/doc/quickstart.txt b/doc/quickstart.txt index 50e155e85..018c27b2b 100644 --- a/doc/quickstart.txt +++ b/doc/quickstart.txt @@ -13,7 +13,7 @@ This is a quick start guide for the complete LTTng tool chain. This is divided in three sections respectively kernel tracing, user-space tracing and reading a trace. -See the README file for installation procedure or use the various Linux +See the README.md file for installation procedure or use the various Linux distribution packages. In order to trace the kernel, you'll need the lttng-modules 2.0 compiled and diff --git a/doc/streaming-howto.txt b/doc/streaming-howto.txt index a89a2c80c..9ba6fea22 100644 --- a/doc/streaming-howto.txt +++ b/doc/streaming-howto.txt @@ -5,7 +5,7 @@ STREAMING This is a brief howto for network streaming feature of lttng 2.0 toolchain. -See the README file for installation procedure or use the various Linux +See the README.md file for installation procedure or use the various Linux distribution packages. Terminology: -- 2.34.1