Legacy C/C++ Instrumentation

This page describes the legacy approach to instrumenting C/C++ programs. If you have found this page unintentionally, you almost certainly should look at the up-to-date instructions instead.

Prerequisites

The instrumentation process depends on an Antithesis provided library, libvoidstar.so, which can be found here. We recommend downloading and vendoring it into your source repo or otherwise caching it, so that the success of your builds does not inadvertently depend on the uptime of our website.

NaN

Build Requirements

To enable coverage instrumentation for your code, you’ll need to compile your binary using a modern version of Clang. Add the following compile flag:

    -fsanitize-coverage=trace-pc-guard

And add the following to your link flags:

    -L${PATH_TO_LIBVOIDSTAR} -lvoidstar --build-id

If your build process includes a single compile/link step, then add both compile and link flags with the following:

    -fsanitize-coverage=trace-pc-guard -L${PATH_TO_LIBVOIDSTAR} -lvoidstar -Wl,--build-id

Validation

Once the binary has been compiled, verify that it has correctly linked to the Antithesis runtime library.

Run the command ldd {binary} to identify its runtime dependencies, and a grep of the string “libvoidstar” to confirm the location of the shared object.

    $ ldd client_binary | grep "libvoidstar"
    libvoidstar.so => /usr/lib/libvoidstar.so

To confirm that the instrumentation process was successful, you should also run the command nm to list all the symbols in the binary, and a grep of the string “sanitizer_cov_trace_pc_guard” .

    $ nm client_binary | grep "sanitizer_cov_trace_pc_guard"
    U __sanitizer_cov_trace_pc_guard
    U __sanitizer_cov_trace_pc_guard_init

Notice the “U” character in the previous code block: it means the symbol is (U)ndefined, and the program needs to retrieve the symbol from a library. The instrumented program now looks for this symbol in our runtime library.

If the symbol is not “U”, you may see the character(s) “W” or “T”. Most likely, the binary is not linking to our library but linking to a statically included copy of the Clang runtime library. It may have been compiled with --sanitize, which automatically links the sanitizer runtime.

It is also possible that -fsanitize-coverage=trace-pc-guard was added to your compile flags AND to your link flags. In order for instrumentation to work, it must only be in your compile flags.

Building With Address Sanitizer

You can compile your software with both LLVM address sanitizer (ASAN) support and Antithesis instrumentation support.

Add the following compile flags:

    -fsanitize-coverage=trace-pc-guard -fsanitize=address

Add the following link flags:

    -fsanitize=address -shared-libasan -L${PATH_TO_LIBVOIDSTAR} -lvoidstar --build-id

If your build process includes a single compile/link step, then add both compile and link flags with the following:

    -fsanitize-coverage=trace-pc-guard -fsanitize=address \
    -shared-libasan -L${PATH_TO_LIBVOIDSTAR} -lvoidstar -Wl,--build-id

Finally, set the following environment variable in the container that runs your software:

    ASAN_OPTIONS=verify_asan_link_order=0

This is necessary to ensure that our instrumentation callbacks take precedence over the no-op implementations built into the Clang sanitizer runtime.

If you are also setting additional ASAN options, see here.

Symbolization

The LLVM compiler infrastructure will output debug symbols in the DWARF format. They could be separate debug info or just the original unstripped binary. These files should be symlinked (or moved) into a directory named /symbols in the root of the appropriate container image.

Help

Contact us if you have questions.