doc/api/libbabeltrace2/dox/main-page.dox

   1 /*!
   2 @mainpage Välkommen!
   3
   4 @note
   5 This documentation (text and illustrations) is licensed under a
   6 <a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode">Creative
   7 Commons Attribution-ShareAlike 4.0 International</a> license.
   8
   9 Welcome to the
  10 <strong><em>\bt_api</em></strong> (libbabeltrace2) documentation!
  11
  12 To get an idea of how to use the libbabeltrace2 API, have a look at
  13 the \ref guides "guides" and \ref examples "examples".
  14 That being said, we recommend that you read the \ref api-fund to
  15 understand what the API expects exactly.
  16
  17 If you are developing a \bt_name \bt_plugin or an application which
  18 uses libbabeltrace2, we recommend that you
  19 \ref guide-build-bt2-dev "build the \bt_name library for development".
  20
  21 @section main-bt2-nutshell \bt_name in a nutshell
  22
  23 <a href="https://babeltrace.org/"><strong><em>\bt_name</em></strong></a>
  24 is an open-source software project by
  25 <a href="https://www.efficios.com/">EfficiOS</a>; its purpose is to
  26 process or convert
  27 <a href="https://en.wikipedia.org/wiki/Tracing_(software)">traces</a>.
  28
  29 The \bt_name project contains:
  30
  31 - A library, libbabeltrace2, which all the other parts rely on.
  32
  33   libbabeltrace2 offers a
  34   <a href="https://en.wikipedia.org/wiki/C99">C99</a> interface.
  35
  36   This documentation is about libbabeltrace2's API.
  37
  38 - A command-line program, \bt_cli, which can convert and manipulate
  39   traces.
  40
  41 - Python&nbsp;3 bindings which offer a Pythonic interface of
  42   libbabeltrace2.
  43
  44 - "Standard" plugins which ship with the project.
  45
  46   <a href="https://diamon.org/ctf/">Common Trace Format</a> (CTF) input
  47   and output, plain text input and output, and various utilities are
  48   part of those plugins.
  49
  50 With the \bt_name library, you can:
  51
  52 - Write custom \ref api-comp-cls-src "source",
  53   \ref api-comp-cls-flt "filter", \ref api-comp-cls-sink "sink"
  54   component classes which you can package as \bt_p_plugin.
  55
  56   Component classes are instantiated as \bt_p_comp within a trace
  57   processing \bt_graph and components are assembled to accomplish a
  58   trace manipulation or conversion job.
  59
  60 - Load \bt_p_plugin, instantiate their component classes within a
  61   trace processing \bt_graph, connect the components as needed, and
  62   run the graph to accomplish a trace manipulation or conversion job.
  63
  64   This is what the \bt_cli CLI tool's
  65   <a href="https://babeltrace.org/docs/v\bt_version_min_maj/man1/babeltrace2-convert.1"><code>convert</code></a>
  66   and
  67   <a href="https://babeltrace.org/docs/v\bt_version_min_maj/man1/babeltrace2-run.1"><code>run</code></a>
  68   commands do, for example.
  69
  70 A trace processing \bt_graph contains connected components. The specific
  71 component topology determines the trace processing task to realize.
  72
  73 @image html basic-convert-graph.png "A conversion graph, a specific trace processing graph."
  74
  75 Between the components of a trace processing graph, \bt_p_msg flow from
  76 \bt_p_oport to \bt_p_iport following the configured \bt_p_conn through
  77 \bt_p_msg_iter. There are many types of messages, chief amongst which is
  78 the \bt_ev_msg.
  79
  80 With libbabeltrace2, you can also \ref api-qexec "query" some specific
  81 object from a component class (for example, the available LTTng live sessions
  82 of an <a href="https://lttng.org">LTTng</a> relay daemon).
  83 This is what the \bt_cli CLI tool's
  84 <a href="https://babeltrace.org/docs/v\bt_version_min_maj/man1/babeltrace2-query.1"><code>query</code></a>
  85 command does, for example.
  86
  87 Make sure to read \bt_man{babeltrace2-intro,7}
  88 to learn even more about the \bt_name project and its core concepts.
  89
  90 @section main-contents What's in this documentation?
  91
  92 <dl>
  93   <dt>\ref api-fund</dt>
  94   <dd>
  95     Explains the basic principles of the \bt_api.
  96
  97     Make sure you understand this section as you need this knowledge to
  98     use the API correctly.
  99   </dd>
 100
 101   <dt>\ref guides</dt>
 102   <dd>
 103     Shows how to achieve common tasks with libbabeltrace2.
 104
 105     Guides help you navigate through the most important features of
 106     the library and its API.
 107   </dd>
 108
 109   <dt>\ref examples</dt>
 110   <dd>
 111     Contains simple and more complex examples which apply the different
 112     parts of the API to accomplish real tasks.
 113   </dd>
 114
 115   <dt><a class="el" href="modules.html">API reference</a></dt>
 116   <dd>
 117     Documents all the \bt_name C functions, definitions, macros,
 118     enumerators, and types.
 119
 120     Each documentation module describes its API thoroughly and how it's
 121     related to other modules.
 122   </dd>
 123 </dl>
 124 */