docs: describe how OpenVINO paths are found (#62)

`openvino-finder` encodes some rather complex logic to find OpenVINO
files over several versions. This change describes that logic (and the
rationale for it) in more detail and moves this text to the Rust
documentation, closer to the code.

Author: abrown

README.md

@@ -17,35 +17,41 @@ crate (high-level, ergonomic bindings) for accessing OpenVINO™ functionality i
 
 ### Prerequisites
 
-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.
-
-This repo currently uses [git-lfs](https://git-lfs.github.com/) for large file storage. If you
-[install it](https://github.com/git-lfs/git-lfs/wiki/Installation) before cloning this repository,
-it should have downloaded all large files. To check this, verify that `find crates/openvino -name
-*.bin | xargs ls -lhr` returns `.bin` files of tens of megabytes. If not, download the large files
-with:
-
-```shell
-git lfs fetch
-git lfs checkout
-```
+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 repo currently uses [git-lfs](https://git-lfs.github.com/) for large file storage. If you
+   [install it](https://github.com/git-lfs/git-lfs/wiki/Installation) before cloning this
+   repository, it should have downloaded all large files. To check this, verify that `find
+   crates/openvino -name *.bin | xargs ls -lhr` returns `.bin` files of tens of megabytes. If not,
+   download the large files with:
+
+   ```shell
+   git lfs fetch
+   git lfs checkout
+   ```
+
+3. 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][openvino-finder-docs].
 
+[openvino-finder-docs]: https://docs.rs/openvino-finder
 
 ### Build from an OpenVINO™ installation
 
 ```shell script
 cargo build
-source /opt/intel/openvino/setupvars.sh
 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][install-apt]). The build script will
+of OpenVINO™ (see, e.g., [installing from an APT repository][install-apt]). 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.
+`setupvars.sh` script will do this automatically (e.g., `source /opt/intel/openvino/setupvars.sh`).
 
 [install-apt]: https://docs.openvinotoolkit.org/latest/openvino_docs_install_guides_installing_openvino_apt.html
 
@@ -54,17 +60,17 @@ installation. Ensure that the correct libraries are available on the system's lo
 ### Build for runtime linking
 
 ```shell script
-cargo build --features openvino-sys/runtime-linking
-source /opt/intel/openvino/setupvars.sh
-cargo test --features openvino-sys/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.
+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.
 
 
 

crates/openvino-finder/README.md

@@ -1,19 +1,7 @@
 openvino-finder
 ===============
 
-A utility for locating OpenVINO™ libraries on a host system. It will attempt to find the OpenVINO
-shared libraries in:
-- the `OPENVINO_BUILD_DIR` environment variable (pointed at a locally-built OpenVINO repository)
-- the `OPENVINO_INSTALL_DIR` environment variable (pointed at the top-level OpenVINO installation,
-  e.g., `/opt/intel/openvino`)
-- the `INTEL_OPENVINO_DIR` environment variable (same as above; this is set by OpenVINO setup
-  scripts)
-- the environment's library path (e.g., `LD_LIBRARY_PATH` in Linux; this is also set by the OpenVINO
-  setup scripts)
-- OpenVINO's default installation paths for the OS (a best effort attempt)
+A utility for locating OpenVINO™ files on a host system. Consult the [docs] for an in-depth
+description of how to use this crate (and troubleshoot issues).
 
-### Use
-
-```Rust
-let path = openvino_finder::find("inference_engine_c_api").unwrap();
-```
+[docs]: https://docs.rs/openvino-finder

crates/openvino-finder/src/lib.rs

@@ -1,4 +1,36 @@
-//! Provides a mechanism for locating the OpenVINO shared libraries installed on a system.
+//! This crate provides a mechanism for locating the OpenVINO files installed on a system.
+//!
+//! OpenVINO can be installed several ways: [from an archive][install-archive], [from an APT
+//! repository][install-apt], [via Python `pip`][install-pip]. The Rust bindings need to be able to:
+//!  1. locate the shared libraries (e.g., `libopenvino_c.so` on Linux) — see [`find`]
+//!  2. locate the plugin configuration file (i.e., `plugins.xml`) — see [`find_plugins_xml`].
+//! These files are located in different locations based on the installation method, so this crate
+//! encodes "how to find" OpenVINO files. This crate's goal is to locate __only the latest version__
+//! of OpenVINO; older versions may continue to be supported on a best-effort basis.
+//!
+//! [install-archive]: https://docs.openvino.ai/latest/openvino_docs_install_guides_installing_openvino_from_archive_linux.html
+//! [install-apt]: https://docs.openvino.ai/latest/openvino_docs_install_guides_installing_openvino_apt.html
+//! [install-pip]: https://docs.openvino.ai/latest/openvino_docs_install_guides_installing_openvino_pip.html
+//!
+//! Problems with the OpenVINO bindings are most likely to be due to "finding" the right files. Both
+//! [`find`] and [`find_plugins_xml`] provide various ways of configuring the search paths, first by
+//! examining _special environment variables_ and then by looking in _known installation locations_.
+//! When [installing from an archive][install-archive], OpenVINO provides a setup script (e.g.,
+//! `source /opt/intel/openvino/setupvars.sh`) that sets these special environment variables. Note
+//! that you may need to have the OpenVINO environment ready both when building (`cargo build`) and
+//! running (e.g., `cargo test`) when the libraries are linked at compile-time (the default). By
+//! using the `runtime-linking` feature, the libraries are only searched for at run-time.
+//!
+//! If you do run into problems, the following chart summarizes some of the known installation
+//! locations of the OpenVINO files as of version `2022.3.0`:
+//!
+//! | Installation Method | Path                                               | Available on          | Notes                            |
+//! | ------------------- | -------------------------------------------------- | --------------------- | -------------------------------- |
+//! | Archive (`.tar.gz`) | `<extracted folder>/runtime/lib/<arch>`            | Linux, MacOS          | `<arch>`: `intel64,armv7l,arm64` |
+//! | Archive (`.zip`)    | `<unzipped folder>/runtime/bin/<arch>/Release`     | Windows               | `<arch>`: `intel64,armv7l,arm64` |
+//! | PyPI                | `<pip install folder>/site-packages/openvino/libs` | Linux, MacOS, Windows | Find install folder with `pip show openvino` |
+//! | DEB                 | `/usr/lib/x86_64-linux-gnu/openvino-<version>/`    | Linux (APT-based)     | This path is for plugins; the libraries are one directory above |
+//! | RPM                 | `/usr/lib64/`                                      | Linux (YUM-based)     |                                  |
 
 #![deny(missing_docs)]
 #![deny(clippy::all)]
@@ -22,11 +54,33 @@ macro_rules! check_and_return {
     };
 }
 
-/// Find the path to an OpenVINO library. This will try:
-/// - the `OPENVINO_INSTALL_DIR` environment variable with several subdirectories appended
-/// - the `INTEL_OPENVINO_DIR` environment variable with several subdirectories appended
-/// - the environment's library path (e.g. `LD_LIBRARY_PATH` in Linux)
-/// - OpenVINO's default installation paths for the OS
+/// Find the path to an OpenVINO library.
+///
+/// Because OpenVINO can be installed in quite a few ways (see module documentation), this function
+/// attempts the difficult and thankless task of locating the installation's shared libraries for
+/// use in the Rust bindings (i.e., [openvino] and [openvino-sys]). It uses observations from
+/// various OpenVINO releases across several operating systems and conversations with the OpenVINO
+/// development team, but it may not perfectly locate the libraries in every environment &mdash;
+/// hence the `Option<PathBuf>` return type.
+///
+/// [openvino]: https://docs.rs/openvino
+/// [openvino-sys]: https://docs.rs/openvino-sys
+///
+/// This function will probe:
+/// - the `OPENVINO_BUILD_DIR` environment variable with known build subdirectories appended &mdash;
+///   this is useful for finding libraries built from source
+/// - the `OPENVINO_INSTALL_DIR`, `INTEL_OPENVINO_DIR`, and `LD_LIBRARY_PATH` (or OS-equivalent)
+///   environment variables with known install subdirectories appended &mdash; one of these is set
+///   by a version of OpenVINO's environment script (e.g., `source
+///   /opt/intel/openvino/setupvars.sh`)
+/// - OpenVINO's package installation paths for the OS (e.g., `/usr/lib64`) &mdash; this is useful
+///   for DEB or RPM installations
+/// - OpenVINO's documented extract paths &mdash; this is useful for users who extract the TAR or
+///   ZIP archive to the default locations or use the Docker images
+///
+/// The locations above may change over time. As OpenVINO has released new versions, the documented
+/// locations of the shared libraries has changed. New versions of this function will reflect this,
+/// removing older, unused locations over time.
 pub fn find(library_name: &str) -> Option<PathBuf> {
     let file = format!(
         "{}{}{}",
@@ -177,11 +231,11 @@ const KNOWN_BUILD_SUBDIRECTORIES: &[&str] = &[
 /// DEB/RPM installations, it is found in a version-suffixed directory beside the OpenVINO libraries
 /// (e.g., `openvino-2022.3.0/plugins.xml`).
 ///
-/// This function will check:
-/// - the `OPENVINO_PLUGINS_XML` environment variable--this is specific to this library
+/// This function will probe:
+/// - the `OPENVINO_PLUGINS_XML` environment variable &mdash; this is specific to this library
 /// - the same directory as the `openvino_c` shared library, as discovered by [find]
 /// - the latest version directory beside the `openvino_c` shared library (i.e.,
-///   `openvino-<version>/`)
+///   `openvino-<latest version>/`)
 pub fn find_plugins_xml() -> Option<PathBuf> {
     const FILE_NAME: &str = "plugins.xml";
 

crates/xtask/src/bump.rs

@@ -16,7 +16,7 @@ pub struct BumpCommand {
     /// 'Release v[bumped version]'`.
     #[structopt(long)]
     git: bool,
-    /// What part of the semver version to change: major | minor | patch | <version string>
+    /// What part of the semver version to change: major | minor | patch | [version string]
     #[structopt(name = "KIND")]
     bump: Bump,
 }