README.adoc

   1 // Render with Asciidoctor
   2
   3 :version: 3.0
   4
   5 ifndef::env-github[]
   6 :toc: left
   7 endif::env-github[]
   8
   9 = barectf
  10 25 September 2020
  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/view/barectf/job/barectf_stable-{version}_linuxbuild/[image:https://img.shields.io/jenkins/build?jobUrl=https%3A%2F%2Fci.lttng.org%2Fview%2Fbarectf%2Fjob%2Fbarectf_stable-{version}_linuxbuild%2F[]]
  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)[tracers] that produce
  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/2.3/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/barectf/{version}/[barectf documentation website].
  62
  63 You can refer to this component version in your
  64 https://docs.antora.org/antora/2.3/playbook/[Antora playbook file],
  65 for example:
  66
  67 [source,yaml]
  68 ----
  69 site:
  70   # ...
  71 content:
  72   sources:
  73     - url: https://github.com/efficios/barectf
  74       branches: [stable-3.0]
  75       start_path: docs
  76     # ...
  77 ui:
  78   # ...
  79 ----
  80
  81 == Test barectf
  82
  83 To run the barectf tests:
  84
  85 . Make sure you have the testing requirements:
  86 ** A little-endian architecture.
  87 +
  88 YAML configuration files of tracing tests use a little-endian
  89 native byte order.
  90
  91 ** https://tox.wiki/en/latest/installation.html[tox]
  92 ** A C{nbsp}compiler.
  93 +
  94 If your C{nbsp}compiler is not the command `cc`, then set the `CC`
  95 environment variable to your compiler's path and export it to run
  96 the barectf tests.
  97
  98 ** https://www.gnu.org/software/make/[GNU Make]
  99
 100 . Run the tests:
 101 +
 102 ----
 103 $ tox
 104 ----
 105
 106 == Get help
 107
 108 See the barectf documentation's
 109 https://barectf.org/docs/barectf/{version}/get-help.html[Get help]
 110 page.