README.md

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