C/C++ (outdated)#

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.

This library will become a dynamic runtime dependency of your instrumented program. Your program will need to be able to find this library in order to run successfully, both within the Antithesis environment, and in local testing. Your container building process must install this library at /usr/lib/libvoidstar.so, and your system must be configured so that this location is on your library search path.

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

Warning

Please do NOT add the -fsanitize-coverage=trace-pc-guard argument to your link flags as doing so will cause coverage instrumentation to fail at runtime.

Be careful! Many build systems automatically add all compile flags to your link flags.

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.