README.adoc

   1 // Render with Asciidoctor
   2
   3 ifndef::env-github[]
   4 :toc: left
   5 endif::env-github[]
   6
   7 = barectf
   8 8 March 2022
   9 Philippe Proulx
  10
  11 image::https://barectf.org/barectf-logo.svg[{nbsp}]
  12
  13 https://pypi.python.org/pypi/barectf[image:https://img.shields.io/pypi/v/barectf.svg[]]
  14 https://ci.lttng.org/view/barectf/job/barectf_master_linuxbuild/[image:https://img.shields.io/jenkins/build?jobUrl=https%3A%2F%2Fci.lttng.org%2Fview%2Fbarectf%2Fjob%2Fbarectf_master_linuxbuild%2F[]]
  15
  16 [.lead]
  17 https://barectf.org/[**_barectf_**] (from _bare_ metal and _CTF_)
  18 is a generator of
  19 https://en.wikipedia.org/wiki/Tracing_(software)[tracers] that produce
  20 https://diamon.org/ctf/[CTF] data streams.
  21
  22 [NOTE]
  23 ====
  24 This README mostly documents barectf development.
  25
  26 To learn how to use barectf, read its
  27 https://barectf.org/docs/[documentation].
  28 ====
  29
  30 == Install barectf
  31
  32 See the barectf documentation's
  33 https://barectf.org/docs/barectf/3.1/install.html[Install barectf]
  34 page.
  35
  36 == Build barectf
  37
  38 barectf is a https://python-poetry.org/[Poetry] project.
  39
  40 To build barectf from this repository:
  41
  42 . https://python-poetry.org/docs/#installation[Install Poetry].
  43
  44 . Build the project:
  45 +
  46 ----
  47 $ poetry build
  48 ----
  49 +
  50 The `dist` directory contains the distribution archives.
  51
  52 == Build the barectf documentation
  53
  54 This repository contains an
  55 https://docs.antora.org/antora/latest/component-version/[Antora
  56 documentation component version] under the `docs` directory.
  57
  58 This component version is the source of the
  59 https://barectf.org/docs/[barectf documentation website].
  60
  61 You can refer to this component version in your
  62 https://docs.antora.org/antora/latest/playbook/[Antora playbook file],
  63 for example:
  64
  65 [source,yaml]
  66 ----
  67 site:
  68   # ...
  69 content:
  70   sources:
  71     - url: https://github.com/efficios/barectf
  72       branches: [stable-3.1]
  73       start_path: docs
  74     # ...
  75 ui:
  76   # ...
  77 ----
  78
  79 == Test barectf
  80
  81 To run the barectf tests:
  82
  83 . Make sure you have the testing requirements:
  84 ** A little-endian architecture.
  85 +
  86 YAML configuration files of tracing tests use a little-endian
  87 native byte order.
  88
  89 ** https://tox.wiki/en/latest/installation.html[tox]
  90 ** A C{nbsp}compiler.
  91 +
  92 If your C{nbsp}compiler is not the command `cc`, then set the `CC`
  93 environment variable to your compiler's path and export it to run
  94 the barectf tests.
  95
  96 ** https://www.gnu.org/software/make/[GNU Make]
  97
  98 . Run the tests:
  99 +
 100 ----
 101 $ tox
 102 ----
 103
 104 == Get help
 105
 106 See the barectf documentation's
 107 https://barectf.org/docs/barectf/3.1/get-help.html[Get help] page.