> ## Legacy Rust 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 Rust programs. If you have found this page unintentionally, you almost certainly should look at the [up-to-date instructions](/docs/reference/sdk/rust/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.

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 instrumentation for your code, you'll need to compile your binary using a modern version of Cargo, and the following compile flags:

```
LD_LIBRARY_PATH=${PATH_TO_LIBVOIDSTAR} RUSTFLAGS=" \
    -Ccodegen-units=1 \
    -Cpasses=sancov-module \
    -Cllvm-args=-sanitizer-coverage-level=3 \
    -Cllvm-args=-sanitizer-coverage-trace-pc-guard \
    -Clink-args=-Wl,--build-id  \
    -L${PATH_TO_LIBVOIDSTAR} \
    -lvoidstar" \
    cargo build --bin $BINARY_NAME
```

> **Note**
>
> LLVM-instrumented binaries must have GNU build ids for symbolization to work. As long as you use the -Clink-args=-Wl,--build-id flag above, you'll be fine.

> **Warning**
>
> Please do NOT add `-Clink-args=fsanitize-coverage-trace-pc-guard` to your Cargo flags as doing so will cause coverage instrumentation to fail at runtime.

## 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.

```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. This may happen if you add `fsanitize-coverage-trace-pc-guard` to `-Clink-args` in addition to `Cllvm-args`.

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.

## 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

If you need help with this, write to us at support@antithesis.com or talk to your forward deployed engineer.