openvino-rs

This repository contains the openvino-sys crate (low-level, unsafe bindings) and the openvino crate (high-level, ergonomic bindings) for accessing OpenVINO™ functionality in Rust.

Prerequisites

1. The openvino-sys crate creates bindings to the OpenVINO™ C API using bindgen; this requires a local installation of libclang. Also, be sure to retrieve all Git submodules.

2. This library binds to OpenVINO™'s shared libraries; how those native libraries are configured and installed on your system determines how these Rust bindings work. The openvino-finder crate attempts to locate the necessary libraries and configuration; if you run into problems, you may need to understand additional details documented in the openvino-finder docs.

3. During testing only, this library will download several models for its integration tests. This relies on curl being available on the system path.

4. For macOS (homebrew) users. Install the openvino toolkit, which includes the native C library, and set DYLD_LIBRARY_PATH:

   brew install openvino
   export DYLD_LIBRARY_PATH="$(brew --prefix)/lib"
   

   Then you can build and run using runtime linking.

Build from an OpenVINO™ installation

cargo build
cargo test

The quickest method to build the openvino and openvino-sys crates is with a local installation of OpenVINO™ (see, e.g., installing from an APT repository). The build script will attempt to locate an existing installation (see openvino-finder) and link against its shared libraries. Provide the OPENVINO_INSTALL_DIR environment variable to point at a specific installation. Ensure that the correct libraries are available on the system's load path; OpenVINO™'s setupvars.sh script will do this automatically (e.g., source /opt/intel/openvino/setupvars.sh).

Build for runtime linking

cargo build --features runtime-linking
cargo test --features runtime-linking

The openvino-rs crates also support linking from a shared library at runtime (i.e. dlopen-style). This allow building the crates with no OpenVINO™ installation or source code present and only later — at runtime — providing the OpenVINO™ shared libraries. All underlying system calls are wrapped so that a call to openvino_sys::library::load will link them to their shared library implementation (using the logic in openvino-finder to locate the shared libraries). For high-level users, call openvino::Core::new first to automatically load and link the libraries.

Build from OpenVINO™ sources

First, build OpenVINO by cloning the openvino repository and following the OpenVINO™ build documentation. Then, using the top-level directory as <openvino-repo> (not the CMake build directory), build this crate:

OPENVINO_BUILD_DIR=<openvino-repo> cargo build
OPENVINO_BUILD_DIR=<openvino-repo> cargo test

Some important notes about the path passed in OPENVINO_BUILD_DIR:

• <openvino-repo> should be an absolute path (or at least a path relative to the crates/openvino-sys directory, which is the current directory when used at build time)
• <openvino-repo> should either be outside of this crate's tree or in the target directory (see the limitations on cargo:rustc-link-search).

The various OpenVINO libraries and dependencies are found using the openvino-finder crate. Turn on logging to troubleshoot any issues finding the right libraries, e.g., RUST_LOG=debug OPENVINO_BUILD_DIR=... cargo build -vv.

Build without linking to OpenVINO™

OPENVINO_SKIP_LINKING=1 cargo build -vv

In some environments it may be necessary to build the openvino-sys crate without linking to the OpenVINO libraries (e.g. for docs.rs builds). In these cases, use the OPENVINO_SKIP_LINKING environment variable to skip linking entirely. The compiled crate will likely not work as expected (e.g., for inference), but it should build.

Use

After building:

• peruse the documentation for the openvino crate; this is the library you likely want to interact with from Rust.
• follow along one with of the classification examples; these examples classifies an image using pre-built models. The examples (and all tests) are runnable using cargo test (or OPENVINO_INSTALL_DIR=/opt/intel/openvino cargo test when building from an installation).

Development

Run cargo xtask --help to read up on the in-tree development tools.

License

openvino-rs is released under the same license as OpenVINO™: the Apache License Version 2.0. By contributing to the project, you agree to the license and copyright terms therein and release your contribution under these terms.