> ## Legacy C/C++ Instrumentation > Fetch the complete documentation index at: https://antithesis.com/docs/llms.txt > Use this file to discover all available pages before exploring further. --- 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](/docs/reference/sdk/cpp/instrumentation/) instead. ## Prerequisites The instrumentation process depends on an Antithesis provided library, `libvoidstar.so`, which can be found [here](/assets/instrumentation/libvoidstar.so). 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](/docs/getting_started/setup_guide/docker_compose/) 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: ```shell frame="none" -fsanitize-coverage=trace-pc-guard ``` And add the following to your link flags: ```shell frame="none" -L -lvoidstar --build-id ``` If your build process includes a single compile/link step, then add both compile and link flags with the following: ```shell frame="none" -fsanitize-coverage=trace-pc-guard -shared-libasan -L -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 ` to identify its runtime dependencies, and a `grep` of the string *"libvoidstar"* to confirm the location of the shared object. ```shell frame="none" $ 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"* . ```shell frame="none" $ 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: ```shell frame="none" -fsanitize-coverage=trace-pc-guard -fsanitize=address ``` Add the following link flags: ```shell frame="none" -fsanitize=address -shared-libasan -L -lvoidstar --build-id ``` If your build process includes a single compile/link step, then add both compile and link flags with the following: ```shell frame="none" -fsanitize-coverage=trace-pc-guard -fsanitize=address \ -shared-libasan -L -lvoidstar -Wl,--build-id ``` Finally, set the following environment variable in the [container](/docs/getting_started/setup_guide/docker_compose/) that runs your software: ```shell frame="none" 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](https://github.com/google/sanitizers/wiki/AddressSanitizerFlags). > **Note** > > If you want to use legacy instrumentation with LLVM sanitizers, please ask our customer success engineers to configure it for you. ## Symbolization The LLVM compiler infrastructure will output debug symbols in the [DWARF](https://en.wikipedia.org/wiki/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](/docs/reference/instrumentation/coverage_instrumentation/#symbolization). ## Help [Contact us](/company/contact/) if you have questions.