# Ditto(Live)'s Rust SDK
Please visit <https://docs.ditto.live/> for more info about Ditto, and its Rust documentation.
> Note: for historical reasons, this SDK has been minimally maintained during 2022 and the first half of 2023. We have gradually been able to improve this, and especially since 2024, we take this SDK very seriously, to keep it on par with the high quality standards that our customers can expect from us, showcased in other SDKs such as Swift and Javascript.
>
> - A main example of this has been linkage or ABI incompatibilities with certain Rust toolchains, which have since been fixed.
>
> That being said, some technical debt from that time may still linger for a few extra months, until everything is properly cleaned up (which will come with a major bump to rename and clean up certain rougher parts of the API).
>
> We apologize for the inconvenience.
## Some notes about using a Rust-wrapped C library
Ditto's core functionality is released and packaged as a C library, which is then imported into Rust _via_ the `::dittolive-ditto-sys` crate.
### Downloading the companion binary artifact
Such a crate will download —at build time— the appropriate binary artifact from `https://software.ditto.live/rust/Ditto/<version>/<target>/release/[lib]dittoffi.{a,so,dylib,dll,lib}`
- For instance: `https://software.ditto.live/rust/Ditto/4.5.4/aarch64-apple-darwin/release/libdittoffi.so`
If you wish to avoid this, you will have to do it yourself:
1. Download the proper binary artifact;
1. Instruct `::dittolive-ditto-sys`' `build.rs` script about it by setting the `DITTOFFI_SEARCH_PATH` appropriately (using an absolute path is recommended).
More precisely, the library search resolution order is as follows:
1. `$DITTOFFI_SEARCH_PATH` (if set)
1. `$OUT_DIR` (_e.g._, `${CARGO_TARGET_DIR}/<profile>/build/dittolive-ditto-sys-.../out`)
1. the current working directory (`$PWD`)
1. `$CARGO_TARGET_DIR`
1. Host built-in defaults (_e.g._, `/usr/lib`, `/lib`, `/usr/local/lib`, `$HOME/lib`) controlled by (system) linker setup.
If the library artifact is not found at any of these locations, the build script will attempt its own download into the `$OUT_DIR` (and use that path).
### Linkage
C linkage is typically accompanied with some idiosyncrasies, such as symbol conflicts, or path resolution errors.
The first and foremost question is about **dynamic** _vs._ **static** linkage.
- #### Statically linking `libdittoffi` (default; recommended)
This happens whenever the `LIBDITTO_STATIC` is explicitly set to `1`, or unset.
If you have a special path to the `libdittoffi.a`/`dittoffi.lib` file (on Unix and Windows, respectively), then you can use the `DITTOFFI_SEARCH_PATH` env var to point to its location (using an absolute path), at linkage time (during `cargo build` exclusively).
- In the unlikely case of symbol conflicts, the `LIBDITTO_STATIC_AMEND_WITH=[/abs/path/to/]objcopy` env var may be set to palliate the situation. Feel free to contact the customer support team should that happen.
- #### Dynamically linking (advanced)
You can opt into this behavior by setting the `LIBDITTO_STATIC=0` environment variable.
When opting into this, you will have to handle library path resolution to the `libdittoffi.so`/`libdittoffi.dylib`/`dittoffi.dll` file (on Linux, macOS, and Windows, respectively).
That is, whilst the `DITTOFFI_SEARCH_PATH` is still important to help the `cargo build` / linkage step resolve the dynamic library, the actual usage of this file happens at _runtime_, when the (Rust) binary using `::dittolive_ditto` is executed.
It is thus advisable to install the C dynamic library artifact under one of the system folders, such as `/usr/lib` or whatnot on Unix (lest you have to tweak link-time flags to set OS-specific loader metadata in the binary, such as the `R{,UN}PATH`, using absolute paths, or binary-relative paths (such as `$ORIGIN/…` on Linux)).