From: Philippe Proulx Date: Fri, 11 Oct 2019 19:41:44 +0000 (-0400) Subject: Update project's README X-Git-Tag: v2.0.0-rc1~12 X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=1042d1679ad4a3a2a3dbdd5ae8db28d50556f4b7 Update project's README This patch rewrites the README file as `README.adoc`. `README.adoc` indicates: * What Babeltrace 2 is. * How Babeltrace 2 is different from Babeltrace 1. * What are the project's build-time and run-time requirements. * How to build Babeltrace 2. * How to build Babeltrace 2 for development. * Where the Babeltrace community is. The file refers to the Babeltrace website for the reader to learn more about the project. Signed-off-by: Philippe Proulx Change-Id: I1b7ce8e949fb91616f2672f94b7e8d346a6a368b Reviewed-on: https://review.lttng.org/c/babeltrace/+/2177 --- diff --git a/Makefile.am b/Makefile.am index cb1ec0f7..f49ba956 100644 --- a/Makefile.am +++ b/Makefile.am @@ -7,6 +7,6 @@ SUBDIRS = \ tests dist_doc_DATA = ChangeLog LICENSE mit-license.txt gpl-2.0.txt \ - std-ext-lib.txt README CONTRIBUTING.adoc + std-ext-lib.txt README.adoc CONTRIBUTING.adoc dist_noinst_DATA = CodingStyle diff --git a/README b/README deleted file mode 100644 index 2f304636..00000000 --- a/README +++ /dev/null @@ -1,82 +0,0 @@ -BabelTrace - Trace Format Babel Tower - -This project provides trace read and write libraries, as well as a trace -converter. A plugin can be created for any trace format to allow its conversion -to/from another trace format. - -The main format expected to be converted to/from is the Common Trace -Format (CTF). The latest version of the CTF specification can be found at: - - git tree: git://git.efficios.com/ctf.git - gitweb: http://git.efficios.com/?p=ctf.git - -The CE Workgroup of the Linux Foundation, Ericsson, and EfficiOS have -sponsored this work. - -The current maintainers are: - Jérémie Galarneau - Mathieu Desnoyers - -Questions should be addressed to this mailing list: - lttng-dev@lists.lttng.org - - -BUILDING --------- - - ./bootstrap (skip if using tarball) - ./configure - make - make install - ldconfig - - -DEPENDENCIES ------------- - -To compile Babeltrace, you will need: - - gcc 3.2 or better - libc6 development librairies - (Debian : libc6, libc6-dev) - (Fedora : glibc, glibc) - glib 2.22 or better development libraries - (Debian : libglib2.0-0, libglib2.0-dev) - (Fedora : glib2, glib2-devel) - elfutils >= 0.154 development libraries (optional) - (Debian : libelf-dev, libdw-dev) - (Fedora : elfutils-devel, elfutils-libelf-devel) - python headers (optional) - (Debian/Ubuntu : python3-dev) - swig >= 2.0 (optional) - (Debian/Ubuntu : swig2.0) - python >= 3.0 (optional) - (Debian/Ubuntu : python3) - sphinx >= 1.2 (optional) - (Debian/Ubuntu : python3-sphinx) - - 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" - -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 http://www.gnu.org/software/autoconf/) -- Flex >=2.5.35. -- Bison >=2.4. - -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. - -Running "make check": bash is required. diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..a2ac98dc --- /dev/null +++ b/README.adoc @@ -0,0 +1,297 @@ +// Render with Asciidoctor + += Babeltrace +15 October 2019 +:btversion: 2.0 +:bt2: Babeltrace{nbsp}2 + + +Babeltrace /ˈbæbəltreɪs/, an +https://efficios.com/[EfficiOS] project, is an open-source +https://en.wikipedia.org/wiki/Tracing_(software)[trace] +manipulation framework. + +https://ci.lttng.org/job/babeltrace_master_build[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_build.svg[]] +https://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]] + +The **_{bt2}_** project offers a library with a +https://diamon.org/babeltrace/docs/v{btversion}/libbabeltrace2[C{nbsp}API], +https://diamon.org/babeltrace/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings], +and a +https://diamon.org/babeltrace/docs/v{btversion}/man1/babeltrace2.1/[command-line tool] +(CLI) which makes it very easy for mere mortals to view, convert, +transform, and analyze traces. + +{bt2} is also the reference parser implementation of the +https://diamon.org/ctf/[Common Trace Format] (CTF), a versatile +trace format produced by various tracers and tools such as +https://lttng.org/[LTTng] and +https://barectf.org/[barectf]. The {bt2} library and its Python bindings +can read and write CTF traces. + +See Babeltrace's https://diamon.org/babeltrace[official website], in +particular the +https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`] +manual page, to learn more about the project. + +[NOTE] +.Babeltrace{nbsp}1 vs. {bt2} +==== +The Babeltrace project exists since 2010. In 2019, {bt2} was +released. {bt2} is a complete rewrite of the library, Python +bindings, and CLI. It is plugin-based and offers much more features and +potential than Babeltrace{nbsp}1 while showing comparable performance. + +Because {bt2} is still a young major release, some +distributions still provide packages for the Babeltrace{nbsp}1 project. +Both projects can coexist on the same system as there are no common +files. + +This file documents the **{bt2}** project. +==== + + +== Build Babeltrace{nbsp}{btversion} from source + +=== Build-time requirements + +To build Babeltrace{nbsp}{btversion}, you need: + +Compiler:: + * Any https://gcc.gnu.org/[GCC]-like compiler with C99 and + https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html[GNU extension] + support. ++ +https://clang.llvm.org/[Clang] is one of those. + +Tools:: + * https://www.gnu.org/software/make/[GNU Make] + * **If you build from a Git clone**: + ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.10 + ** https://www.gnu.org/software/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.64 + ** https://www.gnu.org/software/libtool/[GNU Libtool]{nbsp}≥{nbsp}2.2 + ** https://github.com/westes/flex[flex]{nbsp}≥{nbsp}2.5.35 + ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}2.4 + +Libraries:: + * A C library (for example, + https://www.gnu.org/software/libc/[GNU{nbsp}C Library], + https://www.musl-libc.org/[musl libc]) + * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.22 + (Debian/Ubuntu: `libglib2.0-dev`; Fedora: `glib2-devel`) + +_**If you need the `bt2` Python bindings**_:: + * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 (development + libraries and `python3-config`) + (Debian/Ubuntu: `python3-dev`; Fedora: `python3-devel`) + * http://www.swig.org[SWIG]{nbsp}≥{nbsp}3.0 + +_**If you need the https://lttng.org/[LTTng] debug information filter component class (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_:: + * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 + (Debian/Ubuntu: `libelf-dev` and `libdw-dev`; + Fedora: `elfutils-devel` and `elfutils-libelf-devel`) + +_**If you need the `bt2` Python bindings documentation**_:: + * Python{nbsp}≥{nbsp}3.4 + (Debian/Ubuntu/Fedora: `python3`) + * https://www.sphinx-doc.org/en/master/[Sphinx]{nbsp}≥{nbsp}1.6.5 + for Python{nbsp}3 (Debian/Ubuntu/Fedora: `python3-sphinx`) + +_**If you need the {bt2}{nbsp}C{nbsp}API HTML documentation**_:: + * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6 + +_**If you need the {bt2} manual pages**_:: + * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8 + * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25 + + +=== Procedure + +To build {bt2}: + +. **If you build from a Git clone**, do: ++ +[role="term"] +---- +$ ./bootstrap +---- ++ +This generates the `configure` script and other important files. + +. [[conf]]Configure the project: ++ +[role="term"] +---- +$ ./configure +---- ++ +-- +The following options can modify the build: + +`--enable-api-doc`:: + Build the {bt2}{nbsp}C{nbsp}API HTML documentation. + +`--enable-debug-info`:: + Build the https://lttng.org/[LTTng] debug information filter + component class + (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]). + +`--enable-man-pages`:: + Build the {bt2} manual pages. + +`--enable-python-bindings`:: + Build the `bt2` Python bindings. ++ +You can set the path to custom `python3` and `python3-config` programs +with the `PYTHON` and `PYTHON_CONFIG` environment variable. + +`--enable-python-bindings-doc`:: + Build the `bt2` Python bindings documentation. + +`--enable-python-plugins`:: + Build support for {bt2} Python plugins. + +The following environment variables can modify the build: + +`BABELTRACE_DEBUG_MODE`:: + Set to `1` to enable the debug mode. ++ +The debug mode enables more run-time assertions to detect bugs in the +{bt2} project. + +`BABELTRACE_DEV_MODE`:: + Set to `1` to enable the <>. ++ +The {bt2} developer mode enables more precondition and postcondition +assertions to detect programming errors. + +`BABELTRACE_MINIMAL_LOG_LEVEL`:: + Set the build-time, minimal logging level for all the project's + modules. ++ +Set to `TRACE`, `DEBUG`, or `INFO`. + +`BABELTRACE_PLUGIN_PROVIDERS_DIR`:: + Installation directory of {bt2} plugin providers. + +`BABELTRACE_PLUGINS_DIR`:: + Installation directory of {bt2} project plugins. + +See `./configure --help` to list all the available options and +environment variables. +-- + +. Build {bt2}: ++ +[role="term"] +---- +$ make +---- + +To install {bt2}: + +* Do: ++ +[role="term"] +---- +# make install +---- + + +[[dev-mode]] +=== Build {bt2} for plugin or application development + +If you are developing a {bt2} plugin or an application which uses +libbabeltrace2, we recommend that: + +* You build {bt2} from source in _developer mode_. ++ +The {bt2} developer mode enables more precondition and postcondition +assertions to detect programming errors. ++ +Set `BABELTRACE_DEV_MODE=1` when you <> the {bt2} build. + +* You use _TRACE_ as the minimal logging level at build time to have + access to more logging, should you need it to debug your plugin or + application. ++ +Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <> +the {bt2} build. + +{bt2} development build configuration command line example: + +[role="term"] +---- +$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure +---- + +{bt2} development build configuration with Python support example: + +[role="term"] +---- +$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \ + --enable-python-bindings --enable-python-plugins +---- + +See the +https://diamon.org/babeltrace/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API] +documentation for more information. + + +== Use Babeltrace{nbsp}{btversion} + +See the https://diamon.org/babeltrace[Babeltrace website] to learn how +to use the different parts of the project. + + +=== Run-time requirements + +Libraries:: + * A C library (for example, + https://www.gnu.org/software/libc/[GNU{nbsp}C Library], + https://www.musl-libc.org/[musl libc]) + * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.22 + (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`) + +_**If you need the `bt2` Python bindings**_:: + * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 + (Debian/Ubuntu/Fedora: `python3`) + +_**If you need the https://lttng.org/[LTTng] debug information filter component class (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_:: + * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 + (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and + `elfutils-libelf`) + + +== Community + +[NOTE] +==== +Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and +pretty-print their events. + +Even though Babeltrace is independant from the LTTng project today, +their communities remain very close, which is why they share some +communication channels and services. +==== + +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/babeltrace[Babeltrace bug tracker] + +GitHub project:: + https://github.com/efficios/babeltrace/[efficios/babeltrace] + +Continuous integration:: + https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build] + on LTTng's CI + +Code review:: + https://review.lttng.org/q/project:babeltrace[_babeltrace_ project] + on LTTng Review