Usage

Byfl usage

Overview

The basic Byfl usage model is as follows:

1. Compile your application using one of Byfl's compiler wrapper scripts such as bf-clang or bf-clang++. This instruments the code to tally operations of interest.

2. Run your application as normal. A summary of the final tallies will be written to the standard output device, and detailed information will be written to a binary .byfl file.

3. Convert the .byfl file to a more usable format using one of Byfl's output postprocessors such as bfbin2xmlss or bfbin2csv.

Code instrumentation

Instrumenting an application is a simple matter of replacing the regular compiler with a wrapper script. For example, in place of running clang as the C compiler, you would run bf-clang.

Byfl instrumentation slows down code execution and increases the application's memory footprint. Hence, Byfl provides compile-time control over the set of code features to instrument. As a point example, the following are some timings from a small run of SNAP:

Instrumentation	Execution time	Factor slowdown
None	00:01.04	1.0x
Minimal	00:02.70	2.6x
Full	09:40.54	558.2x

In the preceding table, "None" refers to an ordinary, non-Byfl-instrumented version of the code. "Minimal" refers to the code instrumented with only Byfl's default instrumentation (whole-program summary information). "Full" refers to the code instrumented with almost all of the available Byfl options specified: -bf-unique-bytes -bf-vectors -bf-every-bb -bf-merge-bb=10000000 -bf-mem-footprint -bf-types -bf-inst-mix -bf-by-func -bf-data-structs -bf-inst-deps.

As a general rule of thumb, compute-intensive applications will observe greater slowdowns than memory-intensive or I/O-intensive applications when instrumented with Byfl.

Byfl options (e.g., bf-by-func) can be specified either explicitly as as flags to the compiler wrapper script or implicitly within the BF_OPTS environment variable.

In case the wrapper scripts cause problems for your build system, consider the following troubleshooting tips:

1. Pass the -bf-verbose flag to make the wrapper script additionally output the underlying shell commands that it executes.

2. Pass bf-disable=byfl to make the wrapper script merely invoke the underlying compiler without any Byfl instrumentation. This can be used to ensure that the build system works correctly with the given wrapper script.

Advanced usage

Byfl exposes a small number of API functions that applications can use explicitly to control Byfl's run-time behavior. See the Byfl API documentation for more information.