docs: clarity

Cargo.toml

@@ -25,7 +25,6 @@ features = [ "half", "fetch-models", "copy-dylibs", "disable-build-script" ]
 
 [features]
 default = [ "half", "fetch-models", "copy-dylibs" ]
-use-half-intrinsics = [ "half/use-intrinsics" ]
 # used to prevent issues with docs.rs
 disable-build-script = []
 
@@ -38,7 +37,6 @@ prefer-compile-strategy = []
 prefer-system-strategy = []
 prefer-dynamic-libs = []
 minimal-build = []
-training = []
 experimental = []
 mimalloc = []
 compile-static = []

README.md

@@ -1,23 +1,25 @@
 <div align=center>
 	<h1><code>ort</code> - ONNX Runtime Rust bindings</h1>
-    <a href="https://app.codecov.io/gh/pykeio/ort" target="_blank"><img alt="Coverage Results" src="https://img.shields.io/codecov/c/gh/pykeio/ort?style=for-the-badge"></a> <a href="https://github.com/pykeio/ort/actions/workflows/test.yml"><img alt="GitHub Workflow Status" src="https://img.shields.io/github/workflow/status/pykeio/ort/Run%20cargo%20tests?style=for-the-badge"></a>
+    <a href="https://app.codecov.io/gh/pykeio/ort" target="_blank"><img alt="Coverage Results" src="https://img.shields.io/codecov/c/gh/pykeio/ort?style=for-the-badge"></a> <a href="https://github.com/pykeio/ort/actions/workflows/test.yml"><img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/pykeio/ort/test.yml?branch=main&style=for-the-badge"></a><a href="https://crates.io/crates/ort" target="_blank"><img alt="Crates.io" src="https://img.shields.io/crates/d/ort?style=for-the-badge"></a>
 </div>
 
 `ort` is yet another ONNX Runtime wrapper for Rust based on [`onnxruntime-rs`](https://github.com/nbigaouette/onnxruntime-rs). `ort` is updated for ONNX Runtime 1.13.1 and contains many API improvements & fixes.
 
+See [the docs](https://docs.rs/ort) and [`examples/`](https://github.com/pykeio/ort/tree/main/examples) for more detailed information.
+
 ## Cargo features
 - `fetch-models`: Enables fetching models from the ONNX Model Zoo; not recommended for production.
 - `generate-bindings`: Update/generate ONNX Runtime bindings with `bindgen`. Requires [libclang](https://clang.llvm.org/doxygen/group__CINDEX.html).
-- `copy-dylibs`: Copy dynamic libraries to the Cargo `target` folder. Highly recommended on Windows, where the operating system may have an older version of ONNX Runtime bundled.
-- `prefer-system-strategy`: Uses the `system` compile strategy by default; requires users to provide ONNX Runtime libraries.
+- `copy-dylibs`: Copy dynamic libraries to the Cargo `target` folder.
+- `prefer-system-strategy`: Uses the `system` compile [strategy](#strategies) by default; requires users to provide ONNX Runtime libraries.
     - `prefer-dynamic-libs`: By default, if the path pointed to by `ORT_LIB_LOCATION` contains static libraries, `ort` will link to them rather than dynamic libraries. This feature prefers linking to dynamic libraries instead.
-- `prefer-compile-strategy`: Uses the `compile` strategy by default; will take a *very* long time and is currently untested, but allows for easy static linking, avoiding [the DLL hell](#shared-library-hell).
+- `prefer-compile-strategy`: Uses the `compile` [strategy](#strategies) by default; will take a *very* long time, but allows for easy static linking, avoiding [the DLL hell](#shared-library-hell).
+    - *These features only apply when using the compile strategy:*
     - `compile-static`: Compiles ONNX Runtime as a static library.
     - `mimalloc`: Uses the (usually) faster mimalloc memory allocation library instead of the platform default.
     - `experimental`: Compiles Microsoft experimental operators.
-    - `training`: Enables training via ONNX Runtime. Currently unavailable through high-level bindings.
-    - `minimal-build`: Builds ONNX Runtime without ONNX model loading. Drastically reduces size. Recommended for release builds.
-- **Execution providers**: These are required for both building **and** using execution providers. Do not enable any of these features unless you are using the `compile` strategy or you are using the `system` strategy with binaries that support these execution providers, otherwise you'll run into linking errors.
+    - `minimal-build`: Builds ONNX Runtime without RTTI, `.onnx` model format support, runtime optimizations, or dynamically-registered EP kernels. Drastically reduces binary size, recommended for release builds (if possible).
+- **Execution providers**: These are required for both building **and** using execution providers. Do not enable any of these features unless you are using the `compile` [strategy](#strategies) or you are using the `system` strategy with binaries that support these execution providers, otherwise you'll run into linking errors.
     - `cuda`: Enables the CUDA execution provider for Maxwell (7xx) NVIDIA GPUs and above. Requires CUDA v11.6+.
     - `tensorrt`: Enables the TensorRT execution provider for GeForce 9xx series NVIDIA GPUs and above; requires CUDA v11.6+ and TensorRT v8.4+.
     - `openvino`: Enables the OpenVINO execution provider for 6th+ generation Intel Core CPUs.
@@ -36,25 +38,37 @@
     - `vitis`: Enables Xilinx's Vitis-AI execution provider for U200/U250 accelerators.
     - `cann`: Enables the Huawei Compute Architecture for Neural Networks (CANN) execution provider.
 - `half`: Builds support for `float16`/`bfloat16` ONNX tensors.
-- `use-half-intrinsics`: Use intrinsics in the `half` crate for faster operations when dealing with `float16`/`bfloat16` ONNX tensors.
+
+## Strategies
+There are 3 'strategies' for obtaining and linking ONNX Runtime binaries. The strategy can be set with the `ORT_STRATEGY` environment variable.
+- **`download` (default)**: Downloads prebuilt ONNX Runtime from Microsoft. These binaries [may collect telemetry](https://github.com/microsoft/onnxruntime/blob/main/docs/Privacy.md).
+- **`compile`**: Clones & compiles ONNX Runtime from source. This is currently untested and **extremely slow**! It's recommended to use `system` instead.
+- **`system`**: Links to ONNX Runtime binaries provided by the system or a path pointed to by the `ORT_LIB_LOCATION` environment variable. `ort` will link to static or dynamic libraries depending on what is available in the `ORT_LIB_LOCATION` folder (see the `prefer-dynamic-libs` feature).
 
 ## Execution providers
-To use other execution providers, you must explicitly enable them via their Cargo features. Using the `compile` strategy, everything should just work™️. Using the `system` strategy, ensure that the binaries you are linking to have been built with the execution providers you want to use, otherwise you'll get linking errors. After that, configuring & enabling these execution providers can be done through `SessionBuilder::execution_providers()`.
+To use other execution providers, you must explicitly enable them via their Cargo features. Using the `compile` [strategy](#strategies), everything should just work™️. If using the `system` strategy, ensure that the binaries you are linking to have been built with the execution providers you want to use, otherwise you may get linking errors. After that, configuring & enabling these execution providers can be done through `SessionBuilder::execution_providers()`.
 
 Requesting an execution provider via e.g. `ExecutionProviderBuilder::cuda()` will silently fail if that EP is not available on the system or encounters an error and falls back to the next requested execution provider or to the CPU provider if no requested providers are available. If you must know why the execution provider is unavailable, use `ExecutionProviderBuilder::try_*()`, e.g. `try_cuda()`.
 
-For prebuilt Microsoft binaries, you can enable the CUDA or TensorRT execution providers for Windows and Linux via the `cuda` and `tensorrt` Cargo features respectively. **No other execution providers are supported** in these binaries and enabling other features will fail. To use other execution providers, you must build ONNX Runtime yourself to be able to use them.
+For prebuilt Microsoft binaries, you can enable the CUDA or TensorRT execution providers for Windows and Linux via the `cuda` and `tensorrt` Cargo features respectively. **No other execution providers** as prebuilt binaries, and thus enabling other EP features will fail when `ORT_STRATEGY=download`. To use other execution providers, you must build ONNX Runtime from source.
 
 ## Shared library hell
 Because compiling ONNX Runtime from source takes so long (and static linking is not recommended by Microsoft), it may be easier to compile ONNX Runtime as a shared library or use prebuilt DLLs. However, this can cause some issues with library paths and load orders.
 
 ### Windows
-Some versions of Windows come bundled with `onnxruntime.dll` in the System32 folder. On Windows 11 build 22598.1, `onnxruntime.dll` is on version 1.10.0, while `ort` requires 1.13.1, so execution will fail because [system DLLs take precedence](https://learn.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order). Luckily though, DLLs in the same folder as the application have higher priority; `ort` can automatically copy the DLLs to the Cargo target folder when the `copy-dylibs` feature is enabled.
+Some versions of Windows come bundled with an older vesrion of `onnxruntime.dll` in the System32 folder, which will cause an assertion error at runtime:
+```
+The given version [13] is not supported, only version 1 to 10 is supported in this build.
+thread 'main' panicked at 'assertion failed: `(left != right)`
+  left: `0x0`,
+ right: `0x0`', src\lib.rs:50:5
+note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+```
 
-Note that, when running tests/benchmarks for the first time, you'll have to manually copy the `target/debug/onnxruntime*.dll` files to `target/debug/deps/`, or `target/debug/examples/` for examples. It should Just Work™️ when building/running a binary, however.
+The fix is to copy the ONNX Runtime DLLs into the same directory as the binary. `ort` can automatically copy the DLLs to the Cargo target folder when the `copy-dylibs` feature is enabled, though this only fixes binary targets. When running tests/benchmarks/examples for the first time, you'll have to manually copy the `target/debug/onnxruntime*.dll` files to `target/debug/deps/` for tests & benchmarks or `target/debug/examples/` for examples.
 
 ### Linux
-You'll either have to copy `libonnxruntime.so` to a known lib location (e.g. `/usr/lib`) or enable rpath if you have the `copy-dylibs` feature enabled.
+Running a binary via `cargo run` should work without `copy-dylibs`. If you'd like to use the produced binaries outside of Cargo, you'll either have to copy `libonnxruntime.so` to a known lib location (e.g. `/usr/lib`) or enable rpath to load libraries from the same folder as the binary and place `libonnxruntime.so` alongside your binary.
 
 In `Cargo.toml`:
 ```toml
@@ -76,7 +90,7 @@ rustflags = [ "-Clink-args=-Wl,-rpath,\\$ORIGIN" ]
 ```
 
 ### macOS
-macOS follows the same procedure as Linux, except the rpath should point to `@loader_path` rather than `$ORIGIN`:
+macOS has the same limitations as Linux. If enabling rpath, note that the rpath should point to `@loader_path` rather than `$ORIGIN`:
 
 ```toml
 # .cargo/config.toml