From ae403e46640d0614bd6e7df6a04b19093c770124 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Tue, 5 May 2020 15:37:30 -0400 Subject: [PATCH] Convert `README.md` to `README.adoc` MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Asciidoctor offers more features than Markdown which this README can benefit from (attributes, table of contents, description lists, and non-HTML internal anchors to name a few). On GitHub, the table of contents is placed right after the preamble, before the first section's heading. Otherwise, it's placed on the left for increased readability (not supported by GitHub). Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau Change-Id: Id4965abaa7151cb0fc3caca290fcf5d3669f0b80 --- INSTALL | 12 +- Makefile.am | 2 +- README.adoc | 253 ++++++++++++++++++++++++++++++++++++++++ README.md | 217 ---------------------------------- doc/quickstart.txt | 2 +- doc/streaming-howto.txt | 2 +- 6 files changed, 262 insertions(+), 226 deletions(-) create mode 100644 README.adoc delete mode 100644 README.md diff --git a/INSTALL b/INSTALL index e146eab3d..0d6fc07ef 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.md' file for +more-detailed instructions are generic; see the `README.adoc' 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,10 +38,10 @@ 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.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. +diffs or instructions to the address given in the `README.adoc' 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. The file `configure.ac' (or `configure.in') is used to create `configure' by a program called `autoconf'. You need `configure.ac' if @@ -200,7 +200,7 @@ 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.md' should mention any `--enable-' and `--with-' options that +`README.adoc' should mention any `--enable-' and `--with-' options that the package recognizes. For packages that use the X Window System, `configure' can usually diff --git a/Makefile.am b/Makefile.am index 3001e2d37..0240558c8 100644 --- a/Makefile.am +++ b/Makefile.am @@ -12,7 +12,7 @@ endif dist_doc_DATA = LICENSE \ ChangeLog \ - README.md + README.adoc dist_noinst_DATA = CodingStyle diff --git a/README.adoc b/README.adoc new file mode 100644 index 000000000..24d85c1ac --- /dev/null +++ b/README.adoc @@ -0,0 +1,253 @@ +// Render with Asciidoctor + +:nbh: ‑ +:lt: LTTng{nbh}tools +:lib: liblttng{nbh}ctl + +ifdef::env-github[] +:toc: macro +endif::env-github[] + +ifndef::env-github[] +:toc: left +endif::env-github[] + += {lt} +5 May 2020 + +[.normal] +https://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"]] +https://scan.coverity.com/projects/lttng-tools[image:https://img.shields.io/coverity/scan/lttng-tools.svg[Coverity, title="Coverity"]] + +[.lead] +_**{lt}**_ is a set of components to control https://lttng.org/[LTTng] +tracing. + +The project includes: + +* The LTTng https://lttng.org/man/8/lttng-sessiond/[session daemon]. + +* The LTTng consumer daemon. + +* The LTTng https://lttng.org/man/8/lttng-relayd/[relay daemon]. + +* {lib}, a library with a C{nbsp}API used to communicate with + the session daemon. + +* Python{nbsp}3 bindings of liblttng{nbh}ctl. + +* https://lttng.org/man/1/lttng/[`lttng`], a command-line tool over + {lib}. + +* https://lttng.org/man/1/lttng-crash/[`lttng{nbh}crash`], a command-line + tool to recover and view LTTng{nbsp}2 trace buffers in the event of a + crash. + +ifdef::env-github[] +toc::[] +endif::env-github[] + +== Required and optional dependencies + +You need the following dependencies to build and run the {lt} +components: + +* **Linux kernel{nbsp}≥{nbsp}2.6.27** ++ +Use `{nbh}{nbh}disable{nbh}epoll` at <> +time to build {lt} for an older kernel. However, note that we can't +provide any guarantee below 2.6.27. + +* **http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.9.0**. ++ +Debian/Ubuntu package: `liburcu{nbh}dev`. + +* **popt{nbsp}≥{nbsp}1.13** ++ +Debian/Ubuntu package: `libpopt{nbh}dev`. + +* **http://xmlsoft.org/[Libxml2]{nbsp}≥{nbsp}2.7.6** ++ +Debian/Ubuntu package: `libxml2{nbh}dev` + +The following dependencies are optional: + +* **https://babeltrace.org/[Babeltrace{nbsp}2]**: default viewer + of the https://lttng.org/man/1/lttng-view/[`lttng view`] command. ++ +Debian/Ubuntu package: `babeltrace2` + +* **https://lttng.org/[LTTng{nbh}UST]** (same minor version as {lt}): + LTTng user space tracing (applications and libraries). ++ +Debian/Ubuntu package: `liblttng{nbh}ust{nbh}dev` + +* **Perl**: `make{nbsp}check` and tests. + +* **https://www.python.org/[Python]{nbsp}≥{nbsp}3.0**: + `make{nbsp}check` and tests. ++ +Debian/Ubuntu package: `python3` + +* **http://www.swig.org/[SWIG]{nbsp}≥{nbsp}2.0** and + **Python{nbsp}3 development headers**: Python bindings + (enabled at <> time with the + `{nbh}{nbh}enable{nbh}python{nbh}bindings` option). ++ +Debian/Ubuntu packages: `swig2.0` and `python3{nbh}dev` + +* **modprobe** and/or + **https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/[kmod]{nbsp}≥{nbsp}22**: + automatic LTTng kernel modules loading (kernel tracing). + +* **Bash**: `make{nbsp}check`. + +* **http://man7.org/linux/man-pages/man1/man.1.html[`man`]** + (manual pager): view `lttng` command manual + pages with the `{nbh}{nbh}help` option or with the + https://lttng.org/man/1/lttng-help/[`lttng{nbsp}help`] command. ++ +NOTE: You can use the <> option +`{nbh}{nbh}enable{nbh}embedded{nbh}help` to embed the manual pages into +the `lttng`, `lttng{nbh}sessiond`, `lttng{nbh}relayd`, and +`lttng{nbh}crash` programs so that you don't need `man` to view them. + +* **http://perfmon2.sourceforge.net/[libpfm]{nbsp}≥{nbsp}4.0**: + perf regression test suite. ++ +Debian/Ubuntu package: `libpfm4-dev` + +{lt} supports both the LTTng Linux kernel tracer and LTTng user space +tracer sharing the same _minor_ version. While some minor releases do +not change the tracer ABIs and _could_ work, no testing is performed to +ensure that cross-version compatibility is maintained. + +You don't need to rebuild or modify applications instrumented with older +versions of the LTTng{nbh}UST project to make them work with the +components of the latest {lt} release. + +See the https://lttng.org/docs/[LTTng Documentation] for more +information on versioning. + +== Build from source + +=== Dependencies + +You need the following tools to build {lt}: + +* **https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html[GNU{nbsp}Autotools]** + (**Automake{nbsp}≥{nbsp}1.10**, + **Autoconf{nbsp}≥{nbsp}2.64**, and **Autoheader{nbsp}≥{nbsp}2.50**) + +* **http://www.gnu.org/software/autoconf/[GNU{nbsp}Libtool]{nbsp}≥{nbsp}2.2** + +* **https://github.com/westes/flex/[Flex]{nbsp}≥{nbsp}2.5.35** + +* **https://www.gnu.org/software/bison/[Bison]{nbsp}≥{nbsp}2.4** + +To build the {lt} manual pages: + +* **https://www.methods.co.nz/asciidoc/[AsciiDoc]{nbsp}≥{nbsp}8.4.5** ++ +NOTE: Previous versions could work, but were not tested. + +* **https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.21** ++ +NOTE: Previous versions could work, but were not tested. + +If you use GNU{nbsp}gold, which is _not_ mandatory: + +* **GNU{nbsp}gold{nbsp}≥{nbsp}2.22** + +NOTE: With GNU{nbsp}gold, you might need to add +`-L/usr/local/lib` to the `LDFLAGS` environment variable. + +=== Build steps + +. **If you have the {lt} Git source**, run: ++ +---- +$ ./bootstrap +---- ++ +This script creates the `configure` script. + +. [[configure]]Configure the build: ++ +-- +---- +$ ./configure +---- + +If you want the {lib} Python bindings, use the +`{nbh}{nbh}enable{nbh}python{nbh}bindings` option. See also the `PYTHON` +and `PYTHON_CONFIG` environment variables in +`./configure{nbsp}{nbh}{nbh}help`. + +If you don't want to build the manual pages, use the +`{nbh}{nbh}disable{nbh}man{nbh}pages` option. + +If you want to embed the manual pages into the `lttng`, +`lttng{nbh}sessiond`, `lttng{nbh}relayd`, and `lttng{nbh}crash` programs +so that you don't need `man` to view them, use the +`{nbh}{nbh}enable{nbh}embedded{nbh}help` option. + +If your Linux kernel is older than 2.6.27, use the +`{nbh}{nbh}disable{nbh}epoll` option. + +This build configuration script finds LTTng{nbh}UST with +https://www.freedesktop.org/wiki/Software/pkg-config/[pkg{nbh}config]: +set the `PKG_CONFIG_PATH` environment variable accordingly if +pkg{nbh}config cannot find the `lttng{nbh}ust` package information. + +See `./configure{nbsp}{nbh}{nbh}help` for the complete list of options. +-- + +. Build the project: ++ +---- +$ make +---- + +. Install the project: ++ +---- +$ sudo make install +$ sudo ldconfig +---- + +== Usage + +See the https://lttng.org/docs/#doc-controlling-tracing[Tracing control] +section of the LTTng Documentation to learn how to use the {lt} +components. + +See also the https://lttng.org/man/[LTTng manual pages] (all +section{nbsp}1 and{nbsp}8 pages). + +As there's no official {lib} Python bindings yet, see +link:doc/python-howto.txt[`doc/python-howto.txt`] to understand how to +use them. + +== Community + +Mailing list:: + https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev] + (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org]) + +IRC channel:: + irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network + +Bug tracker:: + https://bugs.lttng.org/projects/lttng-tools[{lt} bug tracker] + +GitHub project:: + https://github.com/lttng/lttng-tools/[lttng/lttng{nbh}tools] + +Continuous integration:: + https://ci.lttng.org/job/lttng-tools_master_build/[{lt}'s master build] + on LTTng's CI + +Code review:: + https://review.lttng.org/q/project:lttng-tools[_lttng{nbh}tools_ project] + on LTTng Review diff --git a/README.md b/README.md deleted file mode 100644 index 3e9f91e50..000000000 --- a/README.md +++ /dev/null @@ -1,217 +0,0 @@ -LTTng‑tools -================= - -[![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/lttng-tools_master_build.svg)](https://ci.lttng.org/job/lttng-tools_master_build/) -[![Coverity](https://img.shields.io/coverity/scan/lttng-tools.svg)](https://scan.coverity.com/projects/lttng-tools) - -_**LTTng‑tools**_ is a set of components to control -[LTTng](https://lttng.org/) tracing. - -The project includes: - -* The LTTng [session daemon](https://lttng.org/man/8/lttng-sessiond/). -* The LTTng consumer daemon. -* The LTTng [relay daemon](https://lttng.org/man/8/lttng-relayd/). -* liblttng‑ctl, a library with a C API used to communicate - with the session daemon. -* Python 3 bindings of liblttng‑ctl. -* [`lttng`](https://lttng.org/man/1/lttng/), - a command-line tool over liblttng‑ctl. -* [`lttng-crash`](https://lttng.org/man/1/lttng-crash/), a command-line - tool to recover and view LTTng 2 trace buffers in the event of - a crash. - -Required and optional dependencies ----------------------------------- -You need the following dependencies to build and run the -LTTng‑tools components: - -* **Linux kernel â‰¥ 2.6.27** - - Use `--disable-epoll` at [build configuration](#configure) time to - build LTTng‑tools for an older kernel. However, note that we - can't provide any guarantee below 2.6.27. - -* **[Userspace RCU](http://www.liburcu.org/) ≥ 0.9.0**. - - Debian/Ubuntu package: `liburcu-dev`. - -* **popt â‰¥ 1.13** - - Debian/Ubuntu package: `libpopt-dev`. - -* **[Libxml2](http://xmlsoft.org/) â‰¥ 2.7.6** - - Debian/Ubuntu package: `libxml2-dev` - -The following dependencies are optional: - -* **[Babeltrace 2](https://babeltrace.org/)**: default viewer - of the [`lttng view`](https://lttng.org/man/1/lttng-view/) - command. - - Debian/Ubuntu package: `babeltrace2` - -* **[LTTng‑UST](https://lttng.org/)** (same minor version as - LTTng‑tools): - LTTng user space tracing (applications and libraries). - - Debian/Ubuntu package: `liblttng-ust-dev` - -* **Perl**: `make check` and tests. - -* **[Python](https://www.python.org/) â‰¥ 3.0**: - `make check` and tests. - - Debian/Ubuntu package: `python3` - -* **[SWIG](http://www.swig.org/) â‰¥ 2.0** and - **Python 3 development headers**: Python bindings - (enabled at [build configuration](#configure) time with the - `--enable-python-bindings` option). - - Debian/Ubuntu packages: `swig2.0` and `python3-dev` - -* **modprobe** and/or - **[kmod](https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/) â‰¥ 22**: - automatic LTTng kernel modules loading (kernel tracing). - -* **Bash**: `make check`. - -* **[`man`](http://man7.org/linux/man-pages/man1/man.1.html)** - (manual pager): view `lttng` command manual - pages with the `--help` option or with the - [`lttng help`](https://lttng.org/man/1/lttng-help/) command. - - Note that you can use the [build configuration](#configure) option - `--enable-embedded-help` to embed the manual pages into the - `lttng`, `lttng-sessiond`, `lttng-relayd`, and `lttng-crash` programs - so that you don't need `man` to view them. - -* **[libpfm](http://perfmon2.sourceforge.net/) â‰¥ 4.0**: - perf regression test suite. - - Debian/Ubuntu package: `libpfm4-dev` - -LTTng‑tools supports both the LTTng Linux kernel tracer and LTTng -user space tracer sharing the same _minor_ version. While some minor -releases do not change the tracer ABIs and _could_ work, no testing is -performed to ensure that cross-version compatibility is maintained. - -You don't need to rebuild or modify applications instrumented with older -versions of the LTTng‑UST project to make them work with the -components of the latest LTTng‑tools release. - -See the [LTTng Documentation](https://lttng.org/docs/) for more -information on versioning. - -Build from source ------------------ -### Dependencies - -You need the following tools to build LTTng‑tools: - -* **[GNU Autotools](https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html)** - (**Automake â‰¥ 1.10**, - **Autoconf â‰¥ 2.64**, and **Autoheader â‰¥ 2.50**) - -* **[GNU Libtool](http://www.gnu.org/software/autoconf/) â‰¥ 2.2** - -* **[Flex](https://github.com/westes/flex/) â‰¥ 2.5.35** - -* **[Bison](https://www.gnu.org/software/bison/) â‰¥ 2.4** - -To build the LTTng‑tools manual pages: - -* **[AsciiDoc](https://www.methods.co.nz/asciidoc/) â‰¥ 8.4.5** - - Previous versions could work, but were not tested. - -* **[xmlto](https://pagure.io/xmlto) â‰¥ 0.0.21** - - Previous versions could work, but were not tested. - -If you use GNU gold, which is _not_ mandatory: - -* **GNU gold â‰¥ 2.22** - -Note that with GNU gold, you might have to add -`-L/usr/local/lib` to the `LDFLAGS` environment variable. - -### Build steps - -1. **If you have the LTTng‑tools Git source**, run: - - $ ./bootstrap - - This script creates the `configure` script. - -2. Configure the build: - - $ ./configure - - If you want the liblttng‑ctl Python bindings, use the - `--enable-python-bindings` option. See also the - `PYTHON` and `PYTHON_CONFIG` environment variables in - `./configure --help`. - - If you don't want to build the manual pages, use the - `--disable-man-pages` option. - - If you want to embed the manual pages into the - `lttng`, `lttng-sessiond`, `lttng-relayd`, and `lttng-crash` programs - so that you don't need `man` to view them, use the - `--enable-embedded-help` option. - - If your Linux kernel is older than 2.6.27, use the - `--enable-epoll` option. - - This build configuration script finds LTTng‑UST with - [pkg‑config](https://www.freedesktop.org/wiki/Software/pkg-config/): - set the `PKG_CONFIG_PATH` environment variable accordingly if - pkg‑config cannot find the `lttng-ust` package information. - - See `./configure --help` for the complete list of options. - -3. Build the project: - - $ make - -4. Install the project: - - $ sudo make install - $ sudo ldconfig - -Usage ------ -See the [Tracing control](https://lttng.org/docs/#doc-controlling-tracing) -section of the LTTng Documentation to learn how to use the -LTTng‑tools components. - -See also the [LTTng manual pages](https://lttng.org/man/) (all -section 1 and 8 pages). - -As there's no official liblttng‑ctl Python bindings yet, see -[`doc/python-howto.txt`](doc/python-howto.txt) to understand how to -use them. - -Community ---------- -* **Mailing list**: - [lttng‑dev](https://lists.lttng.org/cgi-bin/mailman/listinfo). - -* **IRC channel**: - [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network. - -* **Bug tracker**:: - [LTTng‑tools bug tracker](https://bugs.lttng.org/projects/lttng-tools/). - -* **GitHub project**: - [lttng/lttng‑tools](https://github.com/lttng/lttng-tools/). - -* **Continuous integration**: - [LTTng CI](https://ci.lttng.org/). - -* **Code review**: - [_lttng‑tools_ project](https://review.lttng.org/q/project:lttng-tools) - on LTTng Review. diff --git a/doc/quickstart.txt b/doc/quickstart.txt index 0e9751b59..9bcb84604 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.md file for installation procedure or use the various Linux +See the README.adoc 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 9ba6fea22..db1938dfa 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.md file for installation procedure or use the various Linux +See the README.adoc file for installation procedure or use the various Linux distribution packages. Terminology: -- 2.34.1