projects / babeltrace.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
include/babeltrace2/types.h: remove unused `bt_event_header_field`
[babeltrace.git] / README.adoc
diff --git a/README.adoc b/README.adoc
index 6290e9d95f70a7f71df8a5dae04b84a49fd4a863..b47dd1d846ccba2da3ba5173cd6cea8e7db183ae 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -1,17 +1,22 @@
 // Render with Asciidoctor
 
 // Render with Asciidoctor
 
-= Babeltrace
-13 April 2020
+= Babeltrace 2
+4 March 2024
 :btversion: 2.0
 :bt2: Babeltrace{nbsp}2
 :btversion: 2.0
 :bt2: Babeltrace{nbsp}2
-
+ifdef::env-github[]
+:toc: macro
+endif::[]
+ifndef::env-github[]
+:toc: left
+endif::[]
 
 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.
 
 
 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://ci.lttng.org/job/babeltrace_master_linuxbuild[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_linuxbuild.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://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]]
 
 The **_{bt2}_** project offers a library with a
@@ -22,34 +27,45 @@ https://babeltrace.org/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.
 
 (CLI) which makes it very easy for mere mortals to view, convert,
 transform, and analyze traces.
 
+image::doc/api/libbabeltrace2/images/basic-convert-graph.png[A basic {bt2} conversion graph]
+
 {bt2} is also the reference parser implementation of the
 {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://diamon.org/ctf/[Common Trace Format] (CTF), a flexible
+trace format which various tracers and tools such as
 https://lttng.org/[LTTng] and
 https://lttng.org/[LTTng] and
-https://barectf.org/[barectf]. The {bt2} library and its Python bindings
-can read and write CTF traces.
+https://barectf.org/[barectf] produce natively.
+The {bt2} library and its Python bindings can read and write CTF traces.
 
 
-See Babeltrace's https://babeltrace.org[official website], in
+See the {bt2} https://babeltrace.org[official website], in
 particular the
 https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`]
 manual page, to learn more about the project.
 
 [NOTE]
 particular the
 https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`]
 manual page, to learn more about the project.
 
 [NOTE]
+ifdef::env-github[]
+.**Babeltrace{nbsp}1 vs. {bt2}**
+endif::[]
+ifndef::env-github[]
 .Babeltrace{nbsp}1 vs. {bt2}
 .Babeltrace{nbsp}1 vs. {bt2}
+endif::[]
 ====
 ====
-The Babeltrace project exists since 2010. In 2020, {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.
+The Babeltrace project exists since 2010.
 
 
-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.
+In 2020, {bt2} was released. {bt2} is a complete rewrite of the library,
+Python bindings, and CLI. It's plugin-based and offers much more
+features and potential than Babeltrace{nbsp}1 while delivering
+comparable performance.
 
 
-This file documents the **{bt2}** project.
+Some Linux distributions still provide packages for the
+Babeltrace{nbsp}1 project. Both projects can coexist on the same system
+as there are no conflicting files.
+
+This README documents the **{bt2}** project.
 ====
 
 ====
 
+ifdef::env-github[]
+toc::[]
+endif::[]
 
 == Build Babeltrace{nbsp}{btversion} from source
 
 
 == Build Babeltrace{nbsp}{btversion} from source
 
@@ -64,14 +80,17 @@ Compiler::
 +
 https://clang.llvm.org/[Clang] is one of those.
 
 +
 https://clang.llvm.org/[Clang] is one of those.
 
+    * Any {cpp} compiler with {cpp}11 support (for example,
+      GCC{nbsp}≥{nbsp}4.8 and Clang{nbsp}≥{nbsp}3.3).
+
 Tools::
     * https://www.gnu.org/software/make/[GNU Make]
     * **If you build from a Git clone**:
 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.12
+    ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.13
     ** https://www.gnu.org/software/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.69
     ** 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/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.69
     ** 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
+    ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}2.5
 
 Libraries::
     * A C library (for example,
 
 Libraries::
     * A C library (for example,
@@ -103,6 +122,24 @@ _**If you need the `bt2` Python bindings documentation**_::
       Python{nbsp}3
       (Debian/Ubuntu/Fedora: `python3-sphinx`)
 
       Python{nbsp}3
       (Debian/Ubuntu/Fedora: `python3-sphinx`)
 
+[NOTE]
+ifdef::env-github[]
+.**Thanks for the code!**
+endif::[]
+ifndef::env-github[]
+.Thanks for the code!
+endif::[]
+====
+We'd like to thank the authors of the following projects which are
+embedded into the {bt2} source tree:
+
+* https://github.com/fmtlib/fmt[\{fmt}]
+* https://github.com/nlohmann/json[JSON for Modern {cpp}]
+* https://github.com/martinmoene/optional-lite[optional lite]
+* https://github.com/martinmoene/span-lite[span lite]
+* https://github.com/martinmoene/string-view-lite[string_view lite]
+* https://github.com/wonder-mice/zf_log[zf_log]
+====
 
 === Procedure
 
 
 === Procedure
 
@@ -130,6 +167,14 @@ The following options can modify the build:
 `--enable-api-doc`::
     Build the {bt2}{nbsp}C{nbsp}API HTML documentation.
 
 `--enable-api-doc`::
     Build the {bt2}{nbsp}C{nbsp}API HTML documentation.
 
+`--enable-built-in-plugins`::
+    Statically link the official plugins into the
+    `babeltrace2` executable.
+
+`--enable-built-in-python-plugin-support`::
+    Statically link the Python plugin provider into the
+    `babeltrace2` executable.
+
 `--enable-debug-info`::
     Build the https://lttng.org/[LTTng] debug information filter
     component class
 `--enable-debug-info`::
     Build the https://lttng.org/[LTTng] debug information filter
     component class
@@ -155,18 +200,18 @@ The following environment variables can modify the build:
 `BABELTRACE_DEBUG_MODE`::
     Set to `1` to enable the debug mode.
 +
 `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.
+The debug mode enables more run-time assertions to detect bugs while
+developing the {bt2} project.
 
 `BABELTRACE_DEV_MODE`::
     Set to `1` to enable the <<dev-mode,developer mode>>.
 +
 The {bt2} developer mode enables more precondition and postcondition
 
 `BABELTRACE_DEV_MODE`::
     Set to `1` to enable the <<dev-mode,developer mode>>.
 +
 The {bt2} developer mode enables more precondition and postcondition
-assertions to detect programming errors.
+assertions to detect C{nbsp}API usage errors.
 
 `BABELTRACE_MINIMAL_LOG_LEVEL`::
 
 `BABELTRACE_MINIMAL_LOG_LEVEL`::
-    Set the build-time, minimal logging level for all the project's
-    modules.
+    Set the build-time, minimal logging level for all the modules
+    of the project.
 +
 Set to `TRACE`, `DEBUG`, or `INFO`.
 
 +
 Set to `TRACE`, `DEBUG`, or `INFO`.
 
@@ -174,9 +219,9 @@ Set to `TRACE`, `DEBUG`, or `INFO`.
     Installation directory of {bt2} plugin providers.
 
 `BABELTRACE_PLUGINS_DIR`::
     Installation directory of {bt2} plugin providers.
 
 `BABELTRACE_PLUGINS_DIR`::
-    Installation directory of {bt2} project plugins.
+    Installation directory of {bt2} official plugins.
 
 
-See `./configure --help` to list all the available options and
+Run `./configure --help` to list all the available options and
 environment variables.
 --
 
 environment variables.
 --
 
@@ -189,28 +234,32 @@ $ make
 
 To install {bt2}:
 
 
 To install {bt2}:
 
-* Do:
+* Run:
 +
 [role="term"]
 ----
 # make install
 ----
 
 +
 [role="term"]
 ----
 # make install
 ----
 
-
 [[dev-mode]]
 === Build {bt2} for plugin or application development
 
 [[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:
+If you're developing a {bt2} plugin or an application which uses
+libbabeltrace2, we recommend to:
 
 
-* You build {bt2} from source in _developer mode_.
+* Build {bt2} from source in _developer mode_.
 +
 The {bt2} developer mode enables more precondition and postcondition
 +
 The {bt2} developer mode enables more precondition and postcondition
-assertions to detect programming errors.
+assertions to detect C{nbsp}API usage errors.
++
+The
+https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API documentation]
+always lists the precondition and postconditions of
+functions.
 +
 Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build.
 
 +
 Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build.
 
-* You use _TRACE_ as the minimal logging level at build time to have
+* 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.
 +
   access to more logging, should you need it to debug your plugin or
   application.
 +
@@ -233,46 +282,48 @@ $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
 ----
 
 See the
 ----
 
 See the
-https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API]
-documentation for more information.
-
+https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API
+documentation] for more information.
 
 == Use Babeltrace{nbsp}{btversion}
 
 
 == Use Babeltrace{nbsp}{btversion}
 
-See the https://babeltrace.org[Babeltrace website] to learn how
-to use the different parts of the project.
+See the https://babeltrace.org[{bt2} website] to learn how to use the
+different parts of the project.
 
 
+If you're new to {bt2}, make sure to read the
+https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`]
+manual page to familiarize yourself with the project.
 
 === Run-time requirements
 
 
 === 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.28
-      (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`)
+Libraries:: {empty}
++
+* A C library (for example,
+  https://www.gnu.org/software/libc/[GNU{nbsp}C Library] or
+  https://www.musl-libc.org/[musl libc])
 
 
-_**If you need the `bt2` Python bindings**_::
-    * https://www.python.org[Python]{nbsp}≥{nbsp}3.4
-      (Debian/Ubuntu/Fedora: `python3`)
+* https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
+  (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`)
 
 
-_**If you need the https://lttng.org/[LTTng] debug information filter component class (https://babeltrace.org/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`)
+_**If you need the `bt2` Python bindings**_:: {empty}
++
+* 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://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_:: {empty}
++
+* https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154
+  (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and
+  `elfutils-libelf`)
 
 == Community
 
 
 == Community
 
-[NOTE]
-====
 Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and
 Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and
-pretty-print their events.
+to pretty-print their events.
 
 
-Even though Babeltrace is independent from the LTTng project today,
-their communities remain very close, which is why they share some
-communication channels and services.
-====
+Even though {bt2} is independent 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]
 
 Mailing list::
     https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
@@ -282,15 +333,15 @@ IRC channel::
     irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
 
 Bug tracker::
     irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
 
 Bug tracker::
-    https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker]
+    https://bugs.lttng.org/projects/babeltrace[{bt2} bug tracker]
 
 GitHub project::
     https://github.com/efficios/babeltrace/[efficios/babeltrace]
 
 Continuous integration::
 
 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
+    https://ci.lttng.org/view/Babeltrace/[{bt2} jobs]
+    on the LTTng CI
 
 Code review::
 
 Code review::
-    https://review.lttng.org/q/project:babeltrace[_babeltrace_ project]
-    on LTTng Review
+    https://review.lttng.org/q/project:babeltrace[{bt2} project]
+    on LTTng Review (Gerrit)
BabelTrace - Trace Format Babel Tower
This page took 0.032968 seconds and 4 git commands to generate.