-###########################################
-Babeltrace |version| legacy Python bindings
-###########################################
-
-Generated on |today|.
-
+.. include:: common.rst
Welcome!
========
+Welcome to the `Babeltrace 2 <https://babeltrace.org/>`_ Python |~| 3
+bindings documentation (version |version|).
-Welcome to `Babeltrace <http://www.efficios.com/babeltrace>`_'s
-*legacy* Python bindings' documentation!
+.. note::
-Babeltrace is a trace format converter. It is able to read and write
-different trace formats, such as the
-`Common Trace Format <http://www.efficios.com/ctf>`_ (CTF).
-Babeltrace also acts as the CTF reference implementation.
+ This documentation (text and illustrations) is licensed under a
+ `Creative Commons Attribution-ShareAlike 4.0 International
+ <https://creativecommons.org/licenses/by-sa/4.0/legalcode>`_ license.
-The Babeltrace legacy Python bindings rely on the ``libbabeltrace``
-library, the public C API of Babeltrace.
+.. attention::
+ This documentation is **incomplete**.
+ In the meantime:
-Installing
-==========
+ * See :ref:`examples` to learn how to accomplish common tasks.
-The bindings may be enabled when configuring Babeltrace's build::
+ * Have a look at the
+ :bt2link:`Babeltrace 2 C API documentation <https://babeltrace.org/docs/v@ver@/libbabeltrace2/>`.
- ./configure --enable-python-bindings
+ The Babeltrace |~| 2 Python bindings wrap all the functionalities
+ of libbabeltrace2 in a reasonably systematic manner.
-On Debian and Ubuntu, the bindings are available in the
-``python3-babeltrace`` package.
+**Contents**:
-.. note::
+.. toctree::
+ :maxdepth: 2
- Currently, the Babeltrace legacy Python bindings only works
- with Python 3.
+ installation
+ examples
+What's Babeltrace 2?
+--------------------
+Babeltrace 2 is an open-source software project by
+`EfficiOS <https://www.efficios.com/>`_; its purpose
+is to process or convert
+`traces <https://en.wikipedia.org/wiki/Tracing_(software)>`_.
-Bindings
-========
+The Babeltrace |~| 2 project contains:
-The Babeltrace legacy Python bindings are available as a single Python
-package, :py:mod:`babeltrace`.
+* A **library**,
+ :bt2link:`libbabeltrace2 <https://babeltrace.org/docs/v@ver@/libbabeltrace2/>`,
+ which all the other parts rely on.
-The Babeltrace legacy Python bindings' API is divided into two parts:
+ libbabeltrace2 offers a C99 interface.
-* The :ref:`reader API <reader-api>` is exposed by the
- :mod:`babeltrace.reader` module, a set of classes used to
- open a collection of different traces and iterate on their events.
-* The :ref:`CTF writer API <ctf-writer-api>` is exposed by the
- :mod:`babeltrace.writer` module, which makes it possible to
- write a complete `CTF <http://www.efficios.com/ctf>`_ trace from
- scratch.
+* A **command-line program**, :bt2man:`babeltrace2(1)`, which can
+ convert and manipulate traces.
-.. note::
+* **Python 3 bindings** which offer a Pythonic interface of
+ libbabeltrace2.
- For backward compatibility reasons, the reader API is imported in the
- package itself. The CTF writer API is imported in the package itself
- too, as :mod:`~babeltrace.CTFWriter`. It is, however, strongly
- recommended to import and use the three modules
- (:mod:`babeltrace.common`, :mod:`babeltrace.reader`, and
- :mod:`babeltrace.writer`) explicitly, since there is no long-term
- plan to maintain the compatibility layer.
+ This documentation is about those bindings.
-**Contents**:
+* "Standard" **plugins** which ship with the project.
-.. toctree::
- :numbered:
+ `Common Trace Format <https://diamon.org/ctf/>`_ (CTF) input and
+ output,
+ :bt2link:`plain text <https://babeltrace.org/docs/v@ver@/man7/babeltrace2-plugin-text.7/>`
+ input and output, and various
+ :bt2link:`utilities <https://babeltrace.org/docs/v@ver@/man7/babeltrace2-plugin-utils.7/>`
+ are part of those plugins.
- constants
- reader
- writer
- examples
+With the Babeltrace |~| 2 Python bindings, you can write programs to
+do everything you can do, and more, with libbabeltrace2, that is:
+
+* Write custom source, filter, and sink *component classes* which
+ you can package as Python *plugins*.
+
+ Component classes are instantiated as components within a *trace
+ processing graph* and are assembled to accomplish a trace manipulation
+ or conversion job.
+
+* Load plugins (compiled shared object or Python modules), instantiate
+ their component classes within a trace processing graph, connect the
+ components as needed, and run the graph to accomplish a trace
+ manipulation or conversion job.
+
+ This is what the :command:`babeltrace2` CLI tool's ``convert`` and
+ ``run`` commands do, for example.
+
+A trace processing graph contains connected components. The specific
+component topology determines the trace processing task to realize.
+
+.. figure:: images/basic-convert-graph.png
+
+ A *conversion graph*, a specific trace processing graph.
+
+Between the components of a trace processing graph, *messages* flow from
+output ports to input ports following the configured connections through
+*message iterators*. There are many types of messages, chief amongst
+which is the *event message*.
+
+With the Babeltrace |~| 2 Python bindings, you can also query some
+specific object from a component class (for example, the available LTTng
+live sessions of an `LTTng <https://lttng.org/>`_ relay daemon). This is
+what the :command:`babeltrace2` CLI tool's ``query`` command does, for example.
+
+Make sure to read the :bt2man:`babeltrace2-intro(7)`
+manual page to learn even more about the Babeltrace |~| 2 project and
+its core concepts.
projects / babeltrace.git / blobdiff