refactor: gate preload_dylib behind separate feature

now that we exclusively use statically-linked `libonnxruntime`. It would be silly to require the whole library be dynamically linked in order to use preloading.

Author: decahedron1

Cargo.toml

@@ -61,7 +61,8 @@ tracing = [ "dep:tracing" ]
 
 fetch-models = [ "std", "dep:ureq", "dep:sha2" ]
 download-binaries = [ "ort-sys/download-binaries" ]
-load-dynamic = [ "std", "libloading", "ort-sys/disable-linking" ]
+preload-dylibs = [ "dep:libloading" ]
+load-dynamic = [ "std", "preload-dylibs", "ort-sys/disable-linking" ]
 copy-dylibs = [ "ort-sys/copy-dylibs" ]
 
 tls-rustls = [ "ort-sys/tls-rustls", "ureq?/rustls" ]

docs/content/setup/cargo-features.mdx

@@ -11,6 +11,7 @@ title: Cargo features
 - ✅ **`copy-dylibs`**: In case dynamic libraries are used (like with the CUDA execution provider), creates a symlink to them in the relevant places in the `target` folder to make [compile-time dynamic linking](/setup/linking#compile-time-dynamic-linking) work.
 - ⚒️ **`half`**: Enables support for creating & extracting float16/bfloat16 tensors via the [`half`](https://crates.io/crates/half) crate. ONNX models that are converted to 16-bit precision will typically convert to/from 32-bit floats at the input/output, so you will likely never actually need to interact with a 16-bit tensor on the Rust side.
 - ⚒️ **`num-complex`**: Enables support for creating & extracting complex32/complex64 tensors via the [`num-complex`](https://crates.io/crates/num-complex) crate.
+- ⚒️ **`preload-dylibs`**: Enables [dynamic library preloading](https://docs.rs/ort/2.0.0-rc.10/ort/util/fn.preload_dylib.html); useful if you want to ship CUDA alongside your application instead of requiring the user to install it themselves.
 - ⚒️ **`load-dynamic`**: Enables [runtime dynamic linking](/setup/linking#runtime-loading-with-load-dynamic), which alleviates many of the troubles with compile-time dynamic linking and offers greater flexibility.
 - ⚒️ **`alternative-backend`**: Disables linking to ONNX Runtime, allowing you to instead configure an [alternative backend](/backends).
 - ⚒️ **`fetch-models`**: Enables the [`SessionBuilder::commit_from_url`](https://docs.rs/ort/2.0.0-rc.10/ort/session/builder/struct.SessionBuilder.html#method.commit_from_url) method, allowing you to quickly download & run a model from a URL. This should only be used for quick testing.

src/execution_providers/cuda.rs

@@ -391,6 +391,8 @@ impl ExecutionProvider for CUDAExecutionProvider {
 	}
 }
 
+// Take care in how these are ordered, since some of them depend on each other. Dependencies need to be loaded before
+// their dependents.
 #[cfg(windows)]
 pub const CUDA_DYLIBS: &[&str] = &["cudart64_12.dll", "cublasLt64_12.dll", "cublas64_12.dll", "cufft64_11.dll"];
 #[cfg(not(windows))]
@@ -444,8 +446,8 @@ pub const CUDNN_DYLIBS: &[&str] = &[
 /// // Only preload cuDNN
 /// let _ = cuda::preload_dylibs(None, Some(cudnn_root));
 /// ```
-#[cfg(feature = "load-dynamic")]
-#[cfg_attr(docsrs, doc(cfg(feature = "load-dynamic")))]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "preload-dylibs", feature = "load-dynamic"))))]
+#[cfg(feature = "preload-dylibs")]
 pub fn preload_dylibs(cuda_root_dir: Option<&std::path::Path>, cudnn_root_dir: Option<&std::path::Path>) -> Result<()> {
 	use crate::util::preload_dylib;
 	if let Some(cuda_root_dir) = cuda_root_dir {

src/util/mod.rs

@@ -47,7 +47,8 @@ pub(crate) use self::{
 /// let application_dir = current_exe().unwrap();
 /// let _ = ort::util::preload_dylib(application_dir.join("DirectML.dll"));
 /// ```
-#[cfg(feature = "load-dynamic")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "preload-dylibs", feature = "load-dynamic"))))]
+#[cfg(feature = "preload-dylibs")]
 pub fn preload_dylib<P: AsRef<std::ffi::OsStr>>(path: P) -> Result<(), libloading::Error> {
 	let library = unsafe { libloading::Library::new(path) }?;
 	// Do not run `FreeLibrary` so the library remains in the loaded modules list.