1 ![Icon made by Freepik from www.flaticon.com](https://lttng.org/blog/images/barectf.png)
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 It is recommended to use the
83 [barectf PPA](https://launchpad.net/~lttng/+archive/ubuntu/barectf),
84 which also installs the man page:
86 sudo apt-add-repository ppa:lttng/barectf
88 sudo apt-get install barectf
90 Otherwise, you can always use `pip3`:
92 sudo apt-get install python3-pip
93 sudo pip3 install barectf
95 **Ubuntu 12.04 and lower**:
97 sudo apt-get install python3-setuptools
98 sudo easy_install3 pip
99 sudo pip3 install barectf
103 sudo apt-get install python3-pip
104 sudo pip3 install barectf
106 **Fedora 20 and up**:
108 sudo yum install python3-pip
109 sudo pip3 install barectf
113 It is recommended to use the
114 [AUR package](https://aur.archlinux.org/packages/barectf/), which also
115 installs the man page. If you have
116 [yaourt](https://archlinux.fr/yaourt-en):
118 sudo yaourt -Sy barectf
120 Otherwise, you can always use `pip`:
122 sudo pacman -S python-pip
123 sudo pip install barectf
127 With [Homebrew](http://brew.sh/):
135 Since the philosophy of setuptools packages is to include everything
136 within the package, the barectf man page is not installed on the system
137 when installing barectf with `pip` or with `setup.py`. This would be the
138 job of distribution packages.
140 You can install it manually:
142 wget https://raw.githubusercontent.com/efficios/barectf/vVERSION/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1
144 Replace `VERSION` with the desired version, for example:
146 wget https://raw.githubusercontent.com/efficios/barectf/v2.1.4/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1
151 See the [CTF in a nutshell](http://diamon.org/ctf/#ctf-in-a-nutshell)
152 section of CTF's website to understand the basics of this
155 The most important thing to understand about CTF, for barectf use
156 cases, is the layout of a binary stream packet:
158 * Packet header (defined at the trace level)
159 * Packet context (defined at the stream level)
160 * Sequence of events (defined at the stream level):
161 * Event header (defined at the stream level)
162 * Stream event context (defined at the stream level)
163 * Event context (defined at the event level)
164 * Event payload (defined at the event level)
166 The following diagram, stolen without remorse from CTF's website, shows
169 ![](http://diamon.org/ctf/img/ctf-stream-packet.png)
171 Any of those six dynamic scopes, if defined at all, has an associated
172 CTF type. barectf requires them to be structure types.
177 See the [project's wiki](https://github.com/efficios/barectf/wiki) which
178 contains all the information needed to use barectf.
183 Bash is required for testing barectf.
185 The barectf tests execute the `barectf` command available in your
186 `$PATH`. The best way to test a specific version of barectf is to create
187 a Python 3 [virtual environment](https://virtualenv.pypa.io/en/latest/),
188 install the appropriate version, and then run the tests.
190 In the barectf source tree root, do:
192 virtualenv --python=python3 virt
193 . ./virt/bin/activate
194 rehash # if using zsh
196 (cd tests && ./test.bash)
198 You can specify [Bats](https://github.com/sstephenson/bats) options to
199 `./test.bash`, like `--tap` to get a [TAP](https://testanything.org/)
202 You can exit the virtual environment by running `deactivate`.
207 Since the barectf community is small, it's sharing the communication
208 channels of the [LTTng](http://lttng.org/) project,
209 as [EfficiOS](http://www.efficios.com/) is the main sponsor of both
210 projects. It goes like this:
212 | Item | Location | Notes |
214 | 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 |
215 | IRC | [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network | More specifically, query `eepp` (barectf's maintainer) on this network or on freenode |
216 | Code contribution | Create a new GitHub [pull request](https://github.com/efficios/barectf/pulls) | |
217 | Bug reporting | Create a new GitHub [issue](https://github.com/efficios/barectf/issues/new) | |
218 | Continuous integration | [barectf item on LTTng's CI](https://ci.lttng.org/job/barectf/) | |
219 | Blog | The [LTTng blog](http://lttng.org/blog/) contains many posts about barectf | |