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