barectf CLI tool usage

barectf ships with the barectf command-line interface (CLI) tool.

General synopses

Run a barectf command:

barectf COMMAND COMMAND-ARGUMENTS

Print the version of barectf:

barectf [--version]

Print brief general help:

barectf [--help]

General description

The barectf tool offers a Git-like user interface with the following available commands:

generate

Generates the C source and CTF metadata stream files of a tracer from a YAML configuration file.

show-effective-configuration

Prints the effective version of a YAML configuration file.

show-configuration-version

Prints the major version (2 or 3) of a YAML configuration file.

General options

-h
--help

Print brief general help and exit.

-V
--version

Print the version of barectf and exit.

generate command

Synopses

Generate files from a YAML configuration file:

barectf generate [--prefix=PREFIX] [--metadata-dir=MDIR]
                 [--headers-dir=HDIR] [--code-dir=CDIR]
                 [--include-dir=IDIR]…​
                 [--ignore-include-not-found] CONFIG-PATH

Print command’s brief help:

barectf generate --help

Command name aliases

  • gen

Description

The barectf generate command reads the YAML configuration file CONFIG-PATH to produce:

File name Description

MDIR/metadata

The CTF metadata stream file.

HDIR/FPREFIX.h

The generated tracer’s public C header file.

HDIR/FPREFIX-bitfield.h

Internal macros for the generated tracer (included by FPREFIX.c).

CDIR/FPREFIX.c

The generated tracer’s C source code.

See Build the generated C source code to learn how to build the C source which the generate command produces.

In the list above, FPREFIX is:

Without the --prefix option
If the CONFIG-PATH file has a file name prefix option

The CONFIG-PATH file’s file name prefix option.

Otherwise

barectf

With the --prefix option

PREFIX, without trailing underscores.

For example, if PREFIX is my_tracer_, then FPREFIX is my_tracer.

By default, MDIR, HDIR, and CDIR are the current working directory. Use the --metadata-dir, --headers-dir, and --code-dir to specify other output directories.

Therefore, by default, the generate command writes the metadata, barectf.h, barectf-bitfield.h, and barectf.c files to the current working directory.

If you use the --prefix option, then all the public C identifiers in FPREFIX.h and FPREFIX.c begin with PREFIX. Otherwise, they begin with:

If the CONFIG-PATH file has an identifier prefix option

The CONFIG-PATH file’s identifier prefix option.

Otherwise

barectf_

Add directories to be searched into for inclusion files before the default inclusion directories with the repeatable --include-dir option.

By default, if barectf can’t find an inclusion file while processing the CONFIG-PATH file, the command prints an error and exits with a non-zero status. Force barectf generate to continue silently instead with its --ignore-include-not-found option.

Options

-c CDIR
--code-dir=CDIR

Write the C source file to the directory CDIR instead of the current working directory.

-H HDIR
--headers-dir=HDIR

Write C header files to the directory HDIR instead of the current working directory.

-h
--help

Print the generate command’s brief help and exit.

--ignore-include-not-found

Continue to process the CONFIG-PATH file when inclusion files are not found.

-I IDIR
--include-dir=IDIR

Add IDIR to the list of directories to be searched into for inclusion files before the default inclusion directories.

The default inclusion directories are:

  1. The current working directory.

  2. The directory containing the standard partial YAML files (like stdint.yaml).

-m MDIR
--metadata-dir=MDIR

Write the CTF metadata stream file to the directory MDIR instead of the current working directory.

-p PREFIX
--prefix=PREFIX

Override the default or CONFIG-PATH file’s file and identifier prefixes with:

File name prefix

PREFIX, without trailing underscores.

Identifier prefix

PREFIX

PREFIX must be a valid C identifier.

The default file name prefix is barectf.

The default identifier prefix is barectf_.

show-effective-configuration command

Synopses

Show the effective version of a YAML configuration file:

barectf show-effective-configuration [--include-dir=IDIR]…​
        [--ignore-include-not-found] CONFIG-PATH

Print command’s brief help:

barectf show-effective-configuration --help

Command name aliases

  • show-effective-config

  • show-effective-cfg

Description

The barectf show-effective-configuration command reads the YAML configuration file CONFIG-PATH and prints an equivalent, effective YAML configuration.

See the processing stages of a YAML configuration file to learn what an effective configuration is.

Moreover, the show-effective-configuration command validates the CONFIG-PATH file. In other words, if the command exits with status 0, the generate command using the same options and CONFIG-PATH file would also succeed.

Add directories to be searched into for inclusion files before the default inclusion directories with the repeatable --include-dir option.

By default, if barectf can’t find an inclusion file while processing the CONFIG-PATH file, the command prints an error and exits with a non-zero status. Force barectf show-effective-configuration to continue silently instead with its --ignore-include-not-found option.

Options

-h
--help

Print the show-effective-configuration command’s brief help and exit.

--ignore-include-not-found

Continue to process the CONFIG-PATH file when inclusion files are not found.

-I IDIR
--include-dir=IDIR

Add IDIR to the list of directories to be searched into for inclusion files before the default inclusion directories.

The default inclusion directories are:

  1. The current working directory.

  2. The directory containing the standard partial YAML files (like stdint.yaml).

show-configuration-version command

Synopses

Show a YAML configuration file's version:

barectf show-configuration-version CONFIG-PATH

Print command’s brief help:

barectf show-configuration-version --help

Command name aliases

  • show-config-version

  • show-cfg-version

Description

The barectf show-configuration-version command reads the YAML configuration file CONFIG-PATH and prints its version, which is either 2 or 3.

The show-configuration-version does not validate the CONFIG-PATH file like the show-effective-configuration command does.

Options

-h
--help

Print the show-configuration-version command’s brief help and exit.

Exit status

0

Success

Not 0

Error