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)
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)
10 You will find barectf interesting if:
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,
21 4. You _cannot_ use [LTTng](http://lttng.org/), an efficient tracing
22 framework for the Linux kernel and Linux/BSD user applications, which
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.
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
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
50 **Current limitations**:
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)
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
68 barectf is written in Python 3.
73 Make sure you have Python 3 and `pip` for Python 3 installed, then
76 Note that you may pass the `--user` argument to
77 `pip install` to install the tool in your home directory (instead of
82 sudo apt-get install python3-pip
83 sudo pip3 install barectf
85 **Ubuntu 12.04 and lower**:
87 sudo apt-get install python3-setuptools
88 sudo easy_install3 pip
89 sudo pip3 install barectf
93 sudo apt-get install python3-pip
94 sudo pip3 install barectf
98 sudo yum install python3-pip
99 sudo pip3 install barectf
103 sudo pacman -S python-pip
104 sudo pip install barectf
108 With [Homebrew](http://brew.sh/):
116 See the [CTF in a nutshell](http://diamon.org/ctf/#ctf-in-a-nutshell)
117 section of CTF's website to understand the basics of this
120 The most important thing to understand about CTF, for barectf use
121 cases, is the layout of a binary stream packet:
123 * Packet header (defined at the trace level)
124 * Packet context (defined at the stream level)
125 * Sequence of events (defined at the stream level):
126 * Event header (defined at the stream level)
127 * Stream event context (defined at the stream level)
128 * Event context (defined at the event level)
129 * Event payload (defined at the event level)
131 The following diagram, stolen without remorse from CTF's website, shows
134 ![](http://diamon.org/ctf/img/ctf-stream-packet.png)
136 Any of those six dynamic scopes, if defined at all, has an associated
137 CTF type. barectf requires them to be structure types.
142 See the [project's wiki](https://github.com/efficios/barectf/wiki) which
143 contains all the information needed to use barectf.
148 Bash is required for testing barectf.
150 The barectf tests execute the `barectf` command available in your
151 `$PATH`. The best way to test a specific version of barectf is to create
152 a Python 3 [virtual environment](https://virtualenv.pypa.io/en/latest/),
153 install the appropriate version, and then run the tests.
155 In the barectf source tree root, do:
157 virtualenv --python=python3 virt
158 . ./virt/bin/activate
159 rehash # if using zsh
161 (cd tests && ./test.bash)
163 You can specify [Bats](https://github.com/sstephenson/bats) options to
164 `./test.bash`, like `--tap` to get a [TAP](https://testanything.org/)
167 You can exit the virtual environment by running `deactivate`.