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 /#adding the ditto dependency /#organizing filesystem structure /#cross compiling with the ditto sdk /#troubleshooting for a complete overview of the platforms, transports, and devices, see the docid\ edzyoagrgnvqshqp7on2t for the sdk api reference for rust, see https //software ditto live/rust/ditto/4 7 1/x86 64 unknown linux gnu/docs/dittolive ditto/index html prerequisites before attempting to install ditto, ensure you have rust installed via rustup if you don't have the rustup command, https //rustup rs/ if you already have rustup , ensure it's updated to the latest version bash rustup self update now, verify you have both rustc and cargo available in your shell bash rustc version cargo version creating a new project using cargo, create a new binary project bash cargo new bin my project name 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 https //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 7 3 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 7 3" we recommend using the "=x y z" semver syntax to prevent implicit upgrades cargo toml \[dependencies] dittolive ditto = "=4 7 3" visit the https //docs ditto live/compatibility/rust to find the rust toolchain version you need based on the sdk version you chose for sdk version 4 7 3, you should use rust 1 74 1 create a rust toolchain file next to your cargo toml and paste the rust toolchain version you looked up from the compatibiltiy map /rust toolchain 1 74 1 save the cargo toml and rust toolchain files, then check that you can build and run the executable with cargo run bash $ cargo run info syncing channel updates for '1 74 1 aarch64 apple darwin' finished dev \[unoptimized + debuginfo] target(s) in 0 05s running `target/debug/my project name` hello, world! 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's 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 docid\ djan50yatxflapfg 5rqv ) 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 /#setting up 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 bash @executable path/ /libdittoffi dylib before distributing your app, ensure the ditto sdk shared binary library is included and accessible at the specified location and configured for your linker bash target/\<profile>/build/dittolive ditto sys\<hash>/out 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 cargo/config toml \[target 'cfg(target os = "linux")'] linker = "arm linux gnueabihf gcc" ar = "arm linux gnueabihf ar" rustflags = \[ " c", "link arg= march=armv7 a", " c", "link arg= mfpu=neon", " c", "link arg= mfloat abi=hard", ] \[target 'cfg(target os = "windows")'] linker = "x86 64 w64 mingw32 gcc" ar = "x86 64 w64 mingw32 ar" 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 "error could not find native static library dittoffi, perhaps an l flag is missing" what should i do? 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 target/\<profile>/build/dittolive ditto sys \<hash>/stderr 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 file file libdittoffi dylib otool otool l libdittoffi dylib readelf readelf a libdittoffi so verify the issue is resolved by re running cargo build and ensuring it executes successfully