X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=README.md;h=2a2c0c802bc4f0cd756d8d6cee940ae586d7eeb3;hb=refs%2Fheads%2FC-0001;hp=b58c133b284c6723fa2e381ceb0a57239fe4a768;hpb=2a86ff153399cefcd0a96f0e2499a71e6a1ab695;p=deliverable%2Fbarectf.git diff --git a/README.md b/README.md index b58c133..2a2c0c8 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,89 @@ ![Icon made by Freepik from www.flaticon.com](https://lttng.org/blog/images/barectf.png) +:bangbang: | ATTENTION: barectf is currently transitioning from v2 to v3. In the meantime, this README might be incorrect. New documentation will be written. +:---: | :--- + [![](https://img.shields.io/pypi/v/barectf.svg)](https://pypi.python.org/pypi/barectf) -[![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/barectf.svg)](https://ci.lttng.org/job/barectf) +[![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/barectf_master_build.svg)](https://ci.lttng.org/job/barectf_master_build) -**barectf** is a command-line utility which generates C99 -code that is able to write native [Common Trace Format](http://diamon.org/ctf) -(CTF) binary streams. +_**barectf**_ is a command-line generator of ANSI C tracers which output +[Common Trace Format](http://diamon.org/ctf) packets natively. You will find barectf interesting if: 1. You need to trace an application. - 2. You need tracing to be efficient, yet flexible: - record integers of custom sizes, custom floating point numbers, - enumerations supported by a specific integer type, and - null-terminated UTF-8/ASCII strings (C strings). + 2. You need tracing to be efficient, yet flexible: record integers of + custom sizes and alignments, floating point numbers, enumerations + supported by a specific integer type, and null-terminated + UTF-8/ASCII strings (C strings). 3. You need to be able to convert the recorded binary events to human-readable text, as well as analyze them with Python scripts ([Babeltrace](http://diamon.org/babeltrace/) does all that, - given a CTF input). + given a CTF input). [Trace Compass](http://tracecompass.org/) is + another CTF-compatible application. 4. You _cannot_ use [LTTng](http://lttng.org/), an efficient tracing - framework for the Linux kernel and Linux/BSD user applications, which - also outputs CTF. + framework for the Linux kernel and Linux/BSD user applications, + which also outputs CTF traces. -The target audience of barectf is developers who need to trace bare metal -systems (without an operating system). The code produced by barectf -is pure C99 and can be lightweight enough to fit on a tiny microcontroller. +The target audience of barectf is developers who need to trace [bare +metal](https://en.wikipedia.org/wiki/Bare_machine) systems. The code +produced by barectf is pure ANCI C (with one exception, see the current +limitations below) and can be lightweight enough to fit on a tiny +microcontroller. **Key features**: * Single input: easy-to-write [YAML configuration - file](https://github.com/efficios/barectf/wiki/Writing-the-YAML-configuration-file) - * 1-to-1 mapping from tracing function parameters to event fields + file](https://github.com/efficios/barectf/wiki/Writing-the-YAML-configuration-file). + * 1-to-1 mapping from tracing function parameters to event fields. * Custom and bundled [_platforms_](https://github.com/efficios/barectf/wiki/barectf-platform) hiding the details of opening/closing packets and writing them to a back-end (continuous tracing), getting the clock values, etc.: - * _linux-fs_: basic Linux application tracing writing stream files to - the file system for demonstration purposes - * _parallella_: Adapteva Epiphany/[Parallella](http://parallella.org/) - with host-side consumer - * CTF metadata generated by the command-line tool (automatic trace UUID, - stream IDs, and event IDs) + * _linux-fs_: basic Linux application tracing platform which writes + stream files to the file system for demonstration purposes. + * _parallella_: Adapteva + Epiphany/[Parallella](http://parallella.org/) with host-side + consumer. + * CTF metadata is generated by the command-line tool (automatic trace + UUID, stream IDs, and event IDs). * All basic CTF types are supported: integers, floating point numbers, - enumerations, and null-terminated strings (C strings) - * Binary streams produced by the generated C code and metadata file - produced by barectf are CTF 1.8-compliant - * Human-readable error reporting + enumerations, and null-terminated strings (C strings). + * Binary streams produced by the generated tracer and metadata file + produced by barectf are CTF 1.8-compliant. + * Human-readable error reporting at generation time. + * barectf is written in Python 3, hence you can run the tool on + various platforms. + * Generated tracers are known to build with `gcc` (tested with the + IA-32, x86-64, MIPS, ARM, and AVR architectures), `g++`, `clang`, + `clang++`, [`8cc`](https://github.com/rui314/8cc), + [`tcc`](http://bellard.org/tcc/), VS2008 (with a custom `stdint.h`), + and VS2010. **Current limitations**: As of this version: * All the generated tracing C functions, for a given barectf - stream-specific context, need to be called from the same thread, and cannot - be called from an interrupt handler, unless a user-provided + stream-specific context, need to be called from the same thread, and + cannot be called from an interrupt handler, _unless_ a user-provided synchronization mechanism is used. - * CTF compound types (array, sequence, structure, variant) are not supported - yet, except at some very specific locations in the metadata. - * The current generated C code is not strictly C99 compliant: - [statement expressions](https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html) - and the - [`typeof` keyword](https://gcc.gnu.org/onlinedocs/gcc/Typeof.html) - GCC extensions are used in the generated bitfield macros. The - generated C code is known to be compiled with no warnings using - both GCC and Clang. - -barectf is written in Python 3. + * The generated C code needs the `stdint.h` header, which is new in + C99. If your standard C library does not have this header, + you can create one yourself and put it in one of your include + directories to define the following types according to your + architecture: + * `int8_t` + * `int16_t` + * `int32_t` + * `int64_t` + * `uint8_t` + * `uint16_t` + * `uint32_t` + * `uint64_t` + * CTF compound types (array, sequence, structure, variant) are not + supported yet, except at some very specific locations in the + metadata. ## Installing @@ -77,7 +95,22 @@ Note that you may pass the `--user` argument to `pip install` to install the tool in your home directory (instead of installing globally). -**Latest Ubuntu**: +**Ubuntu 14.04 and 16.04**: + +It is recommended to use the +[barectf PPA](https://launchpad.net/~lttng/+archive/ubuntu/barectf), +which also installs the man page: + + sudo apt-add-repository ppa:lttng/barectf + sudo apt-get update + sudo apt-get install python3-barectf + +Otherwise, you can always use `pip3`: + + sudo apt-get install python3-pip + sudo pip3 install barectf + +**Other, recent Ubuntu**: sudo apt-get install python3-pip sudo pip3 install barectf @@ -100,10 +133,19 @@ installing globally). **Arch Linux**: +It is recommended to use the +[AUR package](https://aur.archlinux.org/packages/barectf/), which also +installs the man page. If you have +[yaourt](https://archlinux.fr/yaourt-en): + + sudo yaourt -Sy barectf + +Otherwise, you can always use `pip`: + sudo pacman -S python-pip sudo pip install barectf -**OS X** +**macOS (OS X)**: With [Homebrew](http://brew.sh/):