Ditto Rust SDK

Overview

Describes the different layers of the Ditto Rust SDK.

Ditto's core codebase is written in Rust. Currently, however, Rust does not have a stable ABI suitable for directly linking. Therefore the Rust SDK, like the other Ditto SDKs is exposed through an external interface that uses the C ABI calling conventions. This core library is compiled as a both a static and dynamic library for a variety of architectures. The dittolive-ditto-sys crate contains Rust bindings to this C ABI library. It will attempt to identify the proper library binary for the host environment, download it from Ditto, and link to it. The Rust SDK includes this -sys crate as a dependency and then exposes an idiomatic Rust interface on top of this library.

Compilation

1. Obtain a valid Ditto License token.
2. Create a new Rust project with cargo new --bin
3. Specify the crate dittolive-ditto as a dependency in your new projects Cargo.toml file.
4. Run cargo build to attempt to build your skeleton project. This will fetch dittolive-ditto-sys from crates.io, which in turn will attempt to download the appropriate Ditto binary for your platform. If you want to cross-compile for a different rustc target, you may need to manually download the appropriate binary.
5. There are several places the Ditto binary can be placed to ensure it can be discovered by rustc and the build.rs script. The easiest location is in your projects CARGO_TARGET_DIR (ie. target/release or target/debug). You can also place the library in the source tree of dittolive-ditto-sys. Lastly you can manually specify the precise directory to search with the env var DITTOFFI_SEARCH_PATH. This last technique is especially useful if you're cross compiling for multiple environments.

Configuration

The following env vars are commonly used to configure the Ditto SDK.

• RUST_SDK_LOG_LEVEL - Sets the log level of the Ditto libraries internal logger. Values are error, warn, info, debug, and verbose. Default is "info".
• DITTOFFI_SEARCH_PATH - Explicitly define where to look for libdittoffi for your platform.
• DITTO_DB_PATH - The absolute path where Ditto should store local copies of documents and attachments. This can also be provided programatically.

Common config patterns

The following are common patterns used to configure test and example apps

• DITTO_LICENSE - EnvVar containing a valid Ditto license token.
• DITTO_APP_NAME - The full name of your app. Typically defined in reverse DNS format (ie. "live.ditto.carsapp").
• DITTO_SITE_ID - A 64 bit unique identifier of this specific instance of your app. Often associated with a Security subject or Identity.
• DITTO_BINDIP - The IP and/or Port (ie. 0.0.0.0:8080) where Ditto should listen for TCP or WebSocket Transport traffic.