By default, `aic-sdk-sys` links the native AIC SDK **statically**. Static linking is the
preferred way to use this library because it produces a self-contained binary and avoids
runtime library discovery. Two opt-in features link a shared `libaic` instead when you need
dynamic loading. They are mutually exclusive; enabling both (e.g. via `--all-features`)
selects `runtime-linking`.
| _(default)_ | static, at build time | `AIC_LIB_PATH` directory, or downloaded with `download-lib` |
| `dynamic-linking` | dynamic, at build time | same to link; then OS loader search at run time |
| `runtime-linking` | dynamic, lazy on first use | OS loader search by name, or `aic_sdk::load_library(path)` |
The two build-time modes find the SDK through `AIC_LIB_PATH=/path/to/aic-sdk/lib`, or through
`download-lib`, which fetches it. `runtime-linking` reads neither: it has no build-time link
step, so the library is located only when the program runs, as described below. Prefer the
default static link unless you specifically need to ship and load a shared library:
```bash
AIC_SDK_LICENSE="…" cargo run --example enhancement \
--features "download-lib download-model"
```
On Windows MSVC the static archive ships in a C-runtime-specific subdirectory of `lib`.
A static archive must be linked with the same CRT variant it was built against. `AIC_LIB_PATH`
and `download-lib` still name the `lib` root: the build script appends `static-crt/` when
the `crt-static` target feature is on (`RUSTFLAGS="-C target-feature=+crt-static"`) and
`dynamic-crt/` otherwise, which is the MSVC default.
# Finding the library at run time
With `dynamic-linking` and `runtime-linking`, the OS dynamic loader must locate `libaic`
when the program runs; `download-lib` only covers build time. Point the loader at the SDK
`lib` directory, ship the library next to the binary, or install it system-wide:
- **Linux:** `LD_LIBRARY_PATH=/path/to/aic-sdk/lib`, or an rpath
(`RUSTFLAGS="-C link-arg=-Wl,-rpath,\$ORIGIN"` + ship `libaic.so` beside the binary).
- **macOS:** `DYLD_LIBRARY_PATH`, `@rpath`/`@loader_path`, or a bundle layout.
- **Windows:** put `aic.dll` next to the `.exe` or on `PATH`. The import library linked
against it and the DLL loaded at run time may be in different directories. On MSVC that
import library is `aic.dll.lib`, not `aic.lib`, which is the static archive; the
`gnullvm` targets use the GNU names, `libaic.dll.a` and `libaic.a`.
- **Android:** prefer the default static link. If you opt into dynamic/runtime linking,
package `libaic.so` into the APK under the matching ABI directory, such as
`lib/arm64-v8a/`.
`runtime-linking` loads `libaic` automatically on the first SDK call, by platform default
name (`libaic.so` / `libaic.dylib` / `aic.dll`). To choose an exact file, call
`load_library` first; if the library can't be found, that first call panics with a
descriptive message:
```rust,no_run
# #[cfg(feature = "runtime-linking")]
# fn demo() -> Result<(), aic_sdk::DynamicLoadingError> {
unsafe { aic_sdk::load_library("/path/to/libaic.so")?; } // optional override
# Ok(())
# }
```