| 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. |