README.adoc

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