Ditto(Live) 的 Rust SDK

请访问 https://docs.ditto.live/ 了解更多关于 Ditto 及其 Rust 文档的信息。

注意：由于历史原因，该 SDK 在 2022 年和 2023 年上半年仅进行了最小维护。我们逐渐能够改进这一点，特别是自 2024 年以来，我们非常重视此 SDK，以保持其与客户可以从我们其他 SDK（如 Swift 和 Javascript）期望的高质量标准相匹配。

• 这主要体现在与某些 Rust 工具链的链接或 ABI 不兼容性上，这些问题已经得到解决。

尽管如此，当时的一些技术债务可能仍然会持续几个月，直到一切得到妥善清理（这将会伴随着对 API 中某些较粗糙部分的重大更新和清理）。

我们对此造成的不便表示歉意。

关于使用 Rust 封装的 C 库的一些注意事项

Ditto 的核心功能以 C 库的形式发布和打包，然后通过 ::dittolive-ditto-sys 包导入 Rust。

下载伴随的二进制工件

此类包将在构建时从 https://software.ditto.live/rust/Ditto/<version>/<target>/release/[lib]dittoffi.{a,so,dylib,dll,lib} 下载适当的二进制工件。

• 例如： https://software.ditto.live/rust/Ditto/4.5.4/aarch64-apple-darwin/release/libdittoffi.so

如果您想避免这种情况，您必须自己处理

1. 下载适当的二进制工件；

2. 通过设置 DITTOFFI_SEARCH_PATH 来指导 ::dittolive-ditto-sys 的 build.rs 脚本（使用绝对路径是推荐的）。

更准确地说，库搜索的解析顺序如下

1. $DITTOFFI_SEARCH_PATH（如果已设置）
2. $OUT_DIR（例如，${CARGO_TARGET_DIR}/<profile>/build/dittolive-ditto-sys-.../out）
3. 当前工作目录（$PWD）
4. $CARGO_TARGET_DIR
5. 主机内置默认值（例如，/usr/lib，/lib，/usr/local/lib，$HOME/lib），由（系统）链接器设置控制。

如果库工件在这些位置中的任何位置都没有找到，构建脚本将尝试将其下载到$OUT_DIR（并使用该路径）。

链接

C链接通常伴随着一些特殊性，例如符号冲突或路径解析错误。

首要问题是关于动态与静态链接。

• 静态链接libdittoffi（默认；推荐）

  这发生在LIBDITTO_STATIC被明确设置为1或未设置的情况下。

  如果您有指向libdittoffi.a/dittoffi.lib文件（分别在Unix和Windows上）的特殊路径，则可以使用DITTOFFI_SEARCH_PATH环境变量来指向其位置（使用绝对路径），在链接时间（在cargo build时专用）。

• 动态链接（高级）

  您可以通过设置环境变量LIBDITTO_STATIC=0来选择此行为。

  选择此选项时，您将必须处理库路径解析到libdittoffi.so/libdittoffi.dylib/dittoffi.dll文件（分别在Linux、macOS和Windows上）。

  也就是说，虽然DITTOFFI_SEARCH_PATH对于帮助cargo build / 链接步骤解析动态库仍然很重要，但该文件的实际使用发生在运行时，当执行使用::dittolive_ditto的（Rust）二进制文件时。

  因此，建议将C动态库工件安装在系统文件夹之一下，例如Unix上的/usr/lib等。

  否则，您将必须

  • 可以通过修改链接时标志来在二进制文件中设置特定于操作系统的加载器元数据，例如 R{,UN}PATH / install_path，特别注意绝对路径、二进制相对路径（如 Linux 上的 $ORIGIN/…），甚至工作目录相对路径的选择；

  • 或者为动态加载器使用环境变量指令，例如 macOS 上的 DYLD_FALLBACK_LIBRARY_PATH，或 Linux 上的 LD_LIBRARY_PATH。

  （对于技术高手，在 macOS 上，我们的 .dylib 艺术品的 install_path 被设置为 $rpath/libdittoffi.dylib）。