Rust
This article provides step-by-step instructions on how to set up a new Rust project, integrate the Ditto SDK, cross-compile for any target platform, and more:
- Prerequisites
- Creating a New Project
- Including Ditto Dependencies
- Verifying Project Setup
- Organizing Filesystem Structure
- Cross-Compiling with the Ditto SDK
- Troubleshooting
Prerequisites
Before attempting to install Ditto, ensure you have Rust installed via rustup:
If you don’t have the rustup command, install it via the official Install Rust documentation.
If you already have rustup, ensure it’s updated to the latest version:
Now, verify you have both rustc and cargo available in your shell:
Creating a New Project
Using Cargo, create a new binary project:
Make sure to replace my_project_name with your desired project name.
Adding the Ditto Dependency
Add the Ditto SDK to your Rust project:
Visit docs.rs/dittolive-ditto to find the latest version of the Rust SDK, or the version you would like to use. For this example, let’s choose SDK version 4.8.0.
From the Cargo.toml file located in the root of your project, add a dependency on dittolive-ditto at the version chosen, in this case "=4.8.0". We recommend using the "=x.y.z" semver syntax to prevent implicit upgrades.
Visit the Rust Compatibility Map page to find the Rust Toolchain version you need based on the SDK version you chose. For SDK version 4.8.0, you should use Rust 1.74.1.
Create a rust-toolchain file next to your Cargo.tomland paste the Rust toolchain version you looked up from the compatibiltiy map:
Save the Cargo.toml and rust-toolchain files, then check that you can build and run the executable with cargo run:
The first time running cargo build or cargo run after updating the rust-toolchain file, you should see the “info: syncing channel updates” message. This is rustup magically installing the toolchain you specified in rust-toolchain behind the scenes.
Organizing Filesystem Structure
When organizing the end-user device storage directory, adhere to a filesystem structure that is clean, consistent, and easily maintained.
For guidelines to keep organized, see Components and Organization Best Practices.
Components and Organization Best Practices
The following table provides an overview of the components that make up your app’s filesystem structure and best practices for organizing the files on the filesystem of the end-user device:
| Component | Best Practice |
|---|---|
| AppRoot/AppExecutable | The executable file for your app that, unless explicitly specified, the Ditto SDK is statically linked to: - All other files and directories should be relative to this location. - Maintain a clear separation between this executable file and other libraries. - If desired, use the Ditto SDK as a separate shared library. (See Optional Dynamic Linking) |
| AppRoot/libdittoffi.dll | The Ditto SDK binary library file linking your Cargo for Rust project with Ditto.¹ By default, the Ditto SDK is statically linked to your executable. However, if desired, you can configure your build for dynamic linking by specifying the shared library version of the Ditto SDK. (See Optional Dynamic Linking) |
| AppRoot/ditto_data/ | The base directory designated for Ditto-backed app data stored locally on the end-user device: - Organize all app data within this directory rather than across the entire filesystem for your project. - Maintain a clear and consistent directory structure for your project. |
¹The path and format of the Ditto SDK binary library file vary by app target. For example, .dylib for macOS and .dll for Windows. (See Binary Library Path Formats)
Setting Up Optional Dynamic Linking
If using the Ditto SDK as a separate library from your app’s executable, ensure that, during the build process, the linker can locate the Ditto SDK shared library and link it with your app:
From the linker configuration for your project, specify the path to the Ditto SDK shared binary library.
For an overview of file paths and file extensions by target platform, see Binary Library Path Formats.
For example, to configure for the macOS target, configure the linker flag to locate the Ditto SDK shared binary library (libdittoffi.dylib) for compilation, use @executable_path to specify a relative path from the executable to the library:
Before distributing your app, ensure the Ditto SDK shared binary library is included and accessible at the specified location and configured for your linker:
Binary Library Path Formats
The following table provides an overview of the different file extensions for the binary Ditto library by target platform:
| Target | Format | Description |
|---|---|---|
| Linux | .so | Shared object (SO) |
| macOS | .dylib | Dynamic library (DL) |
| Windows | .dll | Dynamic link library (DLL) |
Cross-Compiling with the Ditto SDK
The Rust compiler, rustc, comes with native cross-compilation support for a wide range of targets, so you can write once and run on any platform without needing to alternate between development environments or libraries.
To cross-compile, specify your targets and other configuration settings as appropriate:
Open the .cargo/config.toml file located in your project root.
Specify targets, their root directories, and other configuration settings, such as POSIX C library, header files, Binutils, and a linker.
For example, the following snippet shows separate configurations for Linux and Windows targets:
Troubleshooting
During the build process, you may encounter the following error message indicating the Ditto SDK build.rs script failed to locate and download the native static library (dittoffi) containing the Ditto binary appropriate for your target:
Diagnosing build.rs Failures
The build.rs script that executes at build is responsible for setting up your build environment and ensuring necessary dependencies, including the Ditto SDK, are correctly configured and accessible for compilation.
However, several factors, such as connectivity issues and misconfigured settings, can cause this script to fail.
To diagnose this issue, check the following logs for errors:
Resolving build.rs Failures
To resolve this issue, perform the following troubleshooting steps:
Ensure your internet connection is live and the Ditto SDK version number is correct.
Using a command-line tool like file, otool, and readelf, as follows, inspect the downloaded library located in the build cache to determine if its properties meet the requirements for integration into your Rust project:
Verify the issue is resolved by re-running cargo build and ensuring it executes successfully.
Was this page helpful?