ittapi-sys

This crate contains low-level Rust bindings for the C ittapi library--you likely want to use the high-level Rust crate. The ittapi library is used for various aspects of Intel® profiling; it exposes the Instrumentation and Tracing Technology (ITT) API as well as the Just-In-Time (JIT) Profiling API. More details about ittapi are available on its README.

IMPORTANT NOTE: this crate is currently only tested on Linux, macOS, and Windows platforms but support for other platforms is intended; contributions are welcome! FreeBSD and OpenBSD are supported but untested.

If you are interested in using VTune to profile Rust applications, you may find the following guide helpful: Wasmtime Docs: Using VTune on Linux

Use

[dependencies]
ittapi-sys = "*"

Using the symbols in this crate can be tricky: ittapi consists of a static part (e.g., libittnotify.a) linked in this crate and a dynamic part (e.g., libittnotify_collector.so, VTune Profiler). The static part provides the ITT data symbols that may be subsequently resolved to actual implementations in the dynamic part--the data collector. This crate only provides symbols like __itt_task_begin_ptr__3_0, not __itt_task_begin, to avoid link errors; programs using ittapi should compile even if the dynamic part is not present. Using the high-level Rust crate avoids this complexity.

Build

cargo build

Building ittapi-sys will build the ittapi C library and link it statically into your application; see the build.rs file.

For Windows developers: this crate uses a symbolic link to access the C library it depends on. To modify this crate on Windows, either configure Git to understand POSIX symlinks or use the copy-c-library.ps1 script to temporarily copy the files.

Test

cargo test

This crate's tests ensure the ittapi-sys bindings remain up to date with the official C header files; they do not check ittapi functionality.

Regenerate Bindings

If the ittapi-sys bindings are not up to date, they can be regenerated with:

BLESS=1 cargo test

The binding generation uses bindgen. An in-depth description of how to use bindgen is available in the bindgen documentation.