README.md

   1 ![Icon made by Freepik from www.flaticon.com](https://lttng.org/blog/images/barectf.png)
   2
   3 :bangbang: | ATTENTION: barectf is currently transitioning from v2 to v3. In the meantime, this README might be incorrect. New documentation will be written.
   4 :---: | :---
   5
   6 [![](https://img.shields.io/pypi/v/barectf.svg)](https://pypi.python.org/pypi/barectf)
   7 [![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/barectf_master_build.svg)](https://ci.lttng.org/job/barectf_master_build)
   8
   9 _**barectf**_ is a command-line generator of ANSI C tracers which output
  10 [Common Trace Format](http://diamon.org/ctf) packets natively.
  11
  12 You will find barectf interesting if:
  13
  14   1. You need to trace an application.
  15   2. You need tracing to be efficient, yet flexible: record integers of
  16      custom sizes and alignments, floating point numbers, enumerations
  17      supported by a specific integer type, and null-terminated
  18      UTF-8/ASCII strings (C strings).
  19   3. You need to be able to convert the recorded binary events to
  20      human-readable text, as well as analyze them with Python scripts
  21      ([Babeltrace](http://diamon.org/babeltrace/) does all that,
  22      given a CTF input). [Trace Compass](http://tracecompass.org/) is
  23      another CTF-compatible application.
  24   4. You _cannot_ use [LTTng](http://lttng.org/), an efficient tracing
  25      framework for the Linux kernel and Linux/BSD user applications,
  26      which also outputs CTF traces.
  27
  28 The target audience of barectf is developers who need to trace [bare
  29 metal](https://en.wikipedia.org/wiki/Bare_machine) systems. The code
  30 produced by barectf is pure ANCI C (with one exception, see the current
  31 limitations below) and can be lightweight enough to fit on a tiny
  32 microcontroller.
  33
  34 **Key features**:
  35
  36   * Single input: easy-to-write [YAML configuration
  37     file](https://github.com/efficios/barectf/wiki/Writing-the-YAML-configuration-file).
  38   * 1-to-1 mapping from tracing function parameters to event fields.
  39   * Custom and bundled
  40     [_platforms_](https://github.com/efficios/barectf/wiki/barectf-platform)
  41     hiding the details of opening/closing packets and writing them to a
  42     back-end (continuous tracing), getting the clock values, etc.:
  43     * _linux-fs_: basic Linux application tracing platform which writes
  44       stream files to the file system for demonstration purposes.
  45     * _parallella_: Adapteva
  46       Epiphany/[Parallella](http://parallella.org/) with host-side
  47       consumer.
  48   * CTF metadata is generated by the command-line tool (automatic trace
  49     UUID, stream IDs, and event IDs).
  50   * All basic CTF types are supported: integers, floating point numbers,
  51     enumerations, and null-terminated strings (C strings).
  52   * Binary streams produced by the generated tracer and metadata file
  53     produced by barectf are CTF 1.8-compliant.
  54   * Human-readable error reporting at generation time.
  55   * barectf is written in Python 3, hence you can run the tool on
  56     various platforms.
  57   * Generated tracers are known to build with `gcc` (tested with the
  58     IA-32, x86-64, MIPS, ARM, and AVR architectures), `g++`, `clang`,
  59     `clang++`, [`8cc`](https://github.com/rui314/8cc),
  60     [`tcc`](http://bellard.org/tcc/), VS2008 (with a custom `stdint.h`),
  61     and VS2010.
  62
  63 **Current limitations**:
  64
  65 As of this version:
  66
  67   * All the generated tracing C functions, for a given barectf
  68     stream-specific context, need to be called from the same thread, and
  69     cannot be called from an interrupt handler, _unless_ a user-provided
  70     synchronization mechanism is used.
  71   * The generated C code needs the `stdint.h` header, which is new in
  72     C99. If your standard C library does not have this header,
  73     you can create one yourself and put it in one of your include
  74     directories to define the following types according to your
  75     architecture:
  76     * `int8_t`
  77     * `int16_t`
  78     * `int32_t`
  79     * `int64_t`
  80     * `uint8_t`
  81     * `uint16_t`
  82     * `uint32_t`
  83     * `uint64_t`
  84   * CTF compound types (array, sequence, structure, variant) are not
  85     supported yet, except at some very specific locations in the
  86     metadata.
  87
  88
  89 ## Installing
  90
  91 Make sure you have Python 3 and `pip` for Python 3 installed, then
  92 install barectf.
  93
  94 Note that you may pass the `--user` argument to
  95 `pip install` to install the tool in your home directory (instead of
  96 installing globally).
  97
  98 **Ubuntu 14.04 and 16.04**:
  99
 100 It is recommended to use the
 101 [barectf PPA](https://launchpad.net/~lttng/+archive/ubuntu/barectf),
 102 which also installs the man page:
 103
 104     sudo apt-add-repository ppa:lttng/barectf
 105     sudo apt-get update
 106     sudo apt-get install python3-barectf
 107
 108 Otherwise, you can always use `pip3`:
 109
 110     sudo apt-get install python3-pip
 111     sudo pip3 install barectf
 112
 113 **Other, recent Ubuntu**:
 114
 115     sudo apt-get install python3-pip
 116     sudo pip3 install barectf
 117
 118 **Ubuntu 12.04 and lower**:
 119
 120     sudo apt-get install python3-setuptools
 121     sudo easy_install3 pip
 122     sudo pip3 install barectf
 123
 124 **Debian**:
 125
 126     sudo apt-get install python3-pip
 127     sudo pip3 install barectf
 128
 129 **Fedora 20 and up**:
 130
 131     sudo yum install python3-pip
 132     sudo pip3 install barectf
 133
 134 **Arch Linux**:
 135
 136 It is recommended to use the
 137 [AUR package](https://aur.archlinux.org/packages/barectf/), which also
 138 installs the man page. If you have
 139 [yaourt](https://archlinux.fr/yaourt-en):
 140
 141     sudo yaourt -Sy barectf
 142
 143 Otherwise, you can always use `pip`:
 144
 145     sudo pacman -S python-pip
 146     sudo pip install barectf
 147
 148 **macOS (OS X)**:
 149
 150 With [Homebrew](http://brew.sh/):
 151
 152     brew install python3
 153     pip3 install barectf
 154
 155
 156 ### Man page
 157
 158 Since the philosophy of setuptools packages is to include everything
 159 within the package, the barectf man page is not installed on the system
 160 when installing barectf with `pip` or with `setup.py`. This would be the
 161 job of distribution packages.
 162
 163 You can install it manually:
 164
 165     wget https://raw.githubusercontent.com/efficios/barectf/vVERSION/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1
 166
 167 Replace `VERSION` with the desired version, for example:
 168
 169     wget https://raw.githubusercontent.com/efficios/barectf/v2.1.4/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1
 170
 171
 172 ## What is CTF?
 173
 174 See the [CTF in a nutshell](http://diamon.org/ctf/#ctf-in-a-nutshell)
 175 section of CTF's website to understand the basics of this
 176 trace format.
 177
 178 The most important thing to understand about CTF, for barectf use
 179 cases, is the layout of a binary stream packet:
 180
 181   * Packet header (defined at the trace level)
 182   * Packet context (defined at the stream level)
 183   * Sequence of events (defined at the stream level):
 184     * Event header (defined at the stream level)
 185     * Stream event context (defined at the stream level)
 186     * Event context (defined at the event level)
 187     * Event payload (defined at the event level)
 188
 189 The following diagram, stolen without remorse from CTF's website, shows
 190 said packet layout:
 191
 192 ![](http://diamon.org/ctf/img/ctf-stream-packet.png)
 193
 194 Any of those six dynamic scopes, if defined at all, has an associated
 195 CTF type. barectf requires them to be structure types.
 196
 197
 198 ## Using
 199
 200 See the [project's wiki](https://github.com/efficios/barectf/wiki) which
 201 contains all the information needed to use barectf.
 202
 203
 204 ## Testing
 205
 206 Bash is required for testing barectf.
 207
 208 The barectf tests execute the `barectf` command available in your
 209 `$PATH`. The best way to test a specific version of barectf is to create
 210 a Python 3 [virtual environment](https://virtualenv.pypa.io/en/latest/),
 211 install the appropriate version, and then run the tests.
 212
 213 In the barectf source tree root, do:
 214
 215     virtualenv --python=python3 virt
 216     . ./virt/bin/activate
 217     rehash # if using zsh
 218     ./setup.py install
 219     (cd tests && ./test.bash)
 220
 221 You can specify [Bats](https://github.com/sstephenson/bats) options to
 222 `./test.bash`, like `--tap` to get a [TAP](https://testanything.org/)
 223 output.
 224
 225 You can exit the virtual environment by running `deactivate`.
 226
 227
 228 ## Community
 229
 230 Since the barectf community is small, it's sharing the communication
 231 channels of the [LTTng](http://lttng.org/) project,
 232 as [EfficiOS](http://www.efficios.com/) is the main sponsor of both
 233 projects. It goes like this:
 234
 235 | Item | Location | Notes |
 236 | --- | --- | --- |
 237 | Mailing list | [lttng-dev](https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev) (`lttng-dev@lists.lttng.org`) | Preferably, use the `[barectf]` subject prefix |
 238 | IRC | [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network | More specifically, query `eepp` (barectf's maintainer) on this network or on freenode |
 239 | Code contribution | Create a new GitHub [pull request](https://github.com/efficios/barectf/pulls) | |
 240 | Bug reporting | Create a new GitHub [issue](https://github.com/efficios/barectf/issues/new) | |
 241 | Continuous integration | [barectf item on LTTng's CI](https://ci.lttng.org/job/barectf/) | |
 242 | Blog | The [LTTng blog](http://lttng.org/blog/) contains many posts about barectf | |