rust_icu: ICU 库的 Rust 语言的低级绑定

条目	描述
测试
源码	https://github.com/google/rust_icu
README	https://github.com/google/rust_icu/blob/main/README.md
覆盖率	查看报告
文档	https://docs.rs/crate/rust_icu

这是一个为 C (即 ICU4C) 的 Unicode 国际组件 (ICU) 库提供的低级本地 Rust 语言绑定的库。

如果您只需要快速了解如何下载和安装的说明，请参阅 快速入门指南

有关 ICU 库的详细信息，请参阅 ICU 项目主页。库源代码可以在 Github 上查看。

此文件的最新版本可在 https://github.com/google/rust_icu 上找到。

这不是一个官方支持的 Google 产品。

为什么包装 ICU (而不是做其他事情)？

• Rust 语言的 国际化 页面确认，Rust 中的 ICU 支持不完整，因此拥有一个功能性的包装器有助于推动技术的发展。

• 像 Fuchsia 这样的项目已经依赖于 ICU，而 Rust 绑定提供了一种无需承担更多依赖项即可轻松使用 Unicode 算法的方法。

• 与 ICU4X 等项目在接口上的合作可能允许在未来无缝过渡到全部 Rust 实现。

仓库结构

仓库按照Rust crates的cargo工作空间组织。每个crate对应ICU4C库的C API中的相应头文件。有关头文件中函数覆盖的详细信息，请参考覆盖率报告。

局限性

目前生成的 Rust 语言绑定方法限制了语言绑定可用性，仅限于可用的 C API。ICU 库的 C API（在文档中有时称为 ICU4C）与 ICU C++ API 不同。

此库提供的绑定适用性有限，这意味着它可能无法直接适用于您的情况。如果您遇到此类情况，请随时 提交一个错误报告 以供我们修复。拉取请求 欢迎接受。

我们目前了解到的局限性如下

• 没有保证的功能一致性。 一些在 C++ 中实现的算法在 C 中没有等效的算法，反之亦然。如果您使用 C++ 库，这通常不是问题，因为您可以选择任何适合您的 API 界面。但对于 Rust 绑定来说，这是一个问题，因为我们目前只能使用 C API。

• 新算法的 C++ 实现并不一定总是反映在 C API 中，导致 C 和 C++ API 界面之间的功能差异。例如，请参见 此错误。

• 虽然使用 icu_config 功能可能会让您在一定程度上自由地自动为您自己的库版本生成绑定，但我们仍然需要列出明确支持的 ICU 版本来确保包装器的稳定性。

兼容性

兼容性保证如下

1. 对最后三个主要 ICU 库版本的感兴趣的所有功能组合都执行了自动测试。
2. 对文档.rs 系统使用的 ICU 库版本执行了自动测试（因此可以构建文档）。

功能

rust_icu 库旨在与 cargo 一起编译，并启用以下功能之一。使用 cargo 进行编译使我们能够在 rust_icu_sys 库中的自定义 build.rs 文件中进行一些库检测，并适应您的构建环境。然而，由于并非每个开发环境都会使用相同的设置，我们选择提供以下某些功能作为配置选项。

虽然我们的目的是保持以下功能列表与 实际 Cargo.toml 中的列表 保持更新，但该列表可能会偶尔过时。

要使用任何功能，您需要在打算使用的所有 rust_icu_ 软件包中激活功能。未这样做会导致编译结果令人困惑。

先决条件

必需

• rust_icu 源代码

  使用 git 进行克隆

  git clone https://github.com/google/rust_icu.git
  

• rustup

  从 https://rustup.rs 安装。用于设置工具链默认值。这将安装 cargo。

• Clang

  您必须安装 Clang 以访问正确的头文件。

• ICU 库开发环境

  您将需要访问 ICU 库，以便将 rust_icu 绑定链接到。有关如何构建和安装 ICU 的信息，请参阅 ICU 简介。

  有时，ICU 库可能已预安装在您的系统上，或者您可以从您的包管理程序中提取库。然而，这个库并不一定是你需要链接到正在开发的程序中的库。简而言之，您有责任在系统上的某个位置有 ICU 的开发者版本。

  我们有一个 快速入门安装，它可能会在您的环境与我们的环境非常相似的情况下使您顺利开始，如果您想从源代码构建 ICU。

可选

• 如果您想使用基于 make 的构建和测试，请安装 GNU Make。

  安装 GNU Make 超出了此文件的范围。请参阅您操作系统的安装说明。

• 如果您决定使用基于 docker 的构建和测试，请安装 docker。

  安装 docker 超出了此文件的范围，请参阅 docker 安装说明 以获取详细信息。由于安装 docker 会干扰主机机器，您的公司可能有关于如何正确安装 docker 的内部文档。

• 如果使用 icu_config 功能，请安装 icu-config 实用程序。

  您需要在系统中安装 ICU 库，以便在 icu-config 二进制文件存在于您的 $PATH 路径中。构建脚本将使用它来发现库设置并生成正确的链接脚本。如果您使用了该功能但未找到 icu-config，

• 如果使用了 bindgen 功能，将使用 bindgen 工具。

  bindgen 用户指南 提供了如何安装它的说明。

• 如果使用了 bindgen 功能，将使用 rustfmt 工具。

  有关安装说明，请参阅 https://github.com/rust-lang/rustfmt。

测试

运行 rust_icu 的测试有几个选项。

Cargo

使用 cargo 构建 和 测试 是构建和测试 Rust 代码的规范方法。

对于 rust_icu 库，您可能会发现系统默认的 ICU 开发包很古老，在这种情况下，您将需要构建自己的 ICU4C 库（有关说明见下文）。这将使您必须传递 PKG_CONFIG_PATH 和 LD_LIBRARY_PATH 环境变量，以帮助构建代码定位和使用您构建的库，而不是系统默认的库。

以下测试都应该构建并通过。请注意，由于所需的库位于自定义位置，我们在运行测试时需要设置 LD_LIBRARY_PATH，以及 PKG_CONFIG_PATH。

如果您发现可以使用系统默认的 ICU 安装，则可以安全地省略这两个库。

env PKG_CONFIG_PATH="$HOME/local/lib/pkgconfig" \
    LD_LIBRARY_PATH="$HOME/local/lib" \
        bash -c 'cargo test'

如果您认为上述方法太麻烦，请考虑尝试 基于 Docker 的方法。

GNU Make

如果您喜欢 GNU 的做事方式，可能会喜欢 GNU Make 方法。

最简单的方法是使用 GNU Make 并运行

make test

如果您在 rust_icu 上工作，已经设置了所有开发环境，并希望有一个简短的方式来运行测试，则可能想要使用此方法。

基于 Docker 的

请参阅上方的 可选依赖部分。

要运行对 rust_icu 源代码的密封构建和测试，请发出以下命令

make docker-test

这将在本地的机器上运行基于 Docker 的源代码构建和测试。这是一种测试您的代码是否与特定的 ICU 参考版本兼容的好方法。

现有技术

已经考虑了大量的现有技术

• https://github.com/servo/rust-icu
• https://github.com/open-i18n/rust-unic
• https://github.com/fullcontact/icu-sys
• https://github.com/rust-locale
• https://github.com/unicode-rs

目前的情况是，我首先想做一些自己的实验，然后看看这些工作是否可以合并到上述任何一项工作中。

另请参阅

• https://github.com/rust-lang/rfcs/issues/797
• https://unicode-rs.github.io
• https://github.com/i18n-concept/rust-discuss

假设

对于 ICU 绑定，存在几种竞争方法。然而，根据 rust 的 RFC 存储库中可用的信息，似乎在 Rust 中对 ICU 的支持工作仍在进行中。

以下是创建此库时所做的假设

• 我们需要一个完整、可重用且易于使用的 Rust 低级 ICU 库。

  例如，这意味着我们必须依赖于外部 ICU 库，而不是将库本身捆绑在绑定代码中。这种模块化允许库的最终用户使用他们选择的 ICU 库，并将其纳入他们各自的系统中。

• 本库的开发工作中不会重新实现 ICU 算法。

  ICU 的重新实现可能需要数千个工程师年的工作才能完成。对于一个像 ICU 这样微妙且复杂的 API，我认为维护单一集中实现可能是更好的投资回报。

  此外，本库的存在并不会阻止重新实现。如果有人想尝试重新实现 ICU，那也很好。

• 本库应作为 rust 实现的低级基础。

  低级 ICU API 可能不适合最终用户。应该在这些绑定之上构建一个 rust-ful API。可能将功能细分为 crates 是一个好主意，以符合 rust 开发者的期望。

  我很乐意重用上述项目中已经做出的逻辑划分。

• 我想探讨将现有实现结合起来的方法，以构建 rust 的完整 ICU 支持。

  希望有可能将今天所有 rust 绑定的优点结合成一个统一的 rust 库。我随时可以讨论选项。

  我之所以开始一个单独的努力，而不是为“先前艺术”部分中列出的任何项目做出贡献，仅仅是因为我想尝试 rust 中生成的库会是什么样子。

其他说明

快速入门指南

在开始之前，请确保满足以下先决条件

• 您已安装 docker 并在您的系统上运行。
• 您有 GNU Make。
• 您有 git。
• 您有足够的磁盘空间。构建环境的 docker 镜像相当大，所以需要几个 GiB 的空间来容纳所有镜像。
• 您有互联网连接。

然后，以下命令序列将检出、构建和测试 rust_icu 源代码。

mkdir -p ~/tmp
cd tmp
git clone https://github.com/google/rust_icu
cd rust_icu
make docker-test

现在您可以修改代码和测试。您可以通过运行 make docker-test 来重新运行编译和测试周期。

ICU 安装说明

以下说明遵循 ICU 仓库中的“树外”构建说明 ICU 仓库。

假设

以下说明不是自包含的。它们假定

• 您已经设置了系统，以便有效地遵循 ICU 构建说明。这需要一些前期时间投资。
• 您可以从源代码构建 ICU，并且您的项目可以访问 ICU 源代码。
• 您的设置是 Linux，有一些非常具体的设置适用于我。您可能能够将它们修改为适用于您的情况。

编译

mkdir -p $HOME/local
mkdir -p $HOME/tmp
cd $HOME/tmp
git clone https://github.com/unicode-org/icu.git
mkdir icu4c-build
cd icu4c-build
../icu/icu4c/source/runConfigureICU Linux \
  --prefix=$HOME/local \
  --enable-static
make
make install
make doc

如果编译成功完成，则目录 $HOME/local/bin 将包含文件 icu-config，这是发现库配置所必需的。

您还可以运行

make check

来运行单元测试。

如果您将 $HOME/local/bin 添加到 $PATH，或者将 icu-config 移动到您的 $PATH 中列出的目录，您应该可以编译 rust_icu。

ICU重建指南

如果您更改ICU库的配置，目的是从源代码重新构建库，您可能需要添加一个中间的make clean命令。

由于ICU构建不是密封的，这确保了构建目录中没有旧编译过程的残留。例如，如果您升级ICU库的主要版本，您需要这样做。如果您忘记这样做，您在编译ICU、链接或运行程序时可能会看到意外的错误。

为ICU的某个版本编译

假设

• 您已选择了功能集 [重命名,icu_version_in_env]o

或者:

• 您已手动验证兼容性矩阵中对您想要使用的ICU版本和功能集的“是”。

以下是一个测试示例。

env PKG_CONFIG_PATH="$HOME/local/lib/pkgconfig" \
    LD_LIBRARY_PATH="$HOME/local/lib" \
    RUST_ICU_MAJOR_VERSION_NUMBER=65 \
        bash -c 'cargo test'

以下是一个尚未测试的示例，说明如何针对预存在的ICU版本66编译rust_icu。

env PKG_CONFIG_PATH="$HOME/local/lib/pkgconfig" \
    LD_LIBRARY_PATH="$HOME/local/lib" \
    RUST_ICU_MAJOR_VERSION_NUMBER=66 \
        bash -c 'cargo test'

添加对ICU新版本的支持。

一般来说，只要支持icu-config方法，只要底层的C API没有太大差异，就应该能够为ICU库的新版本生成库包装器。

为ICU 65.1提供简单支持的方法包括以下步骤。以下，$RUST_ICU_SOURCE_DIR是您提取ICU源代码的目录。

• 从源代码下载新的ICU版本到$RUST_ICU_SOURCE_DIR。
• 使用新版本构建ICU库，例如，按照上面提到的编译步骤。
• 从输出目录$RUST_ICU_SOURCE_DIR/target/debug/build/rust_icu_sys-...获取文件lib.rs，将其重命名为lib_66.rs（如果您使用的是ICU版本66，否则请附加您使用的版本）。
• 将文件保存到目录$RUST_ICU_SOURCE_DIR/rust_icu_sys/bindgen中，这是包含预生成源文件的目录。

如果将build.rs更改以包含更多功能，则可能需要重新生成这些文件lib_XX.rs。

添加更多绑定

在添加更多ICU包装器时，请确保执行以下操作

• 检查rust_icu_sys/build.rs和rust_icu_sys/bindgen/run_bindgen.sh，将适当的行添加到BINDGEN_SOURCE_MODULES，然后添加到BINDGEN_ALLOWLIST_FUNCTIONS和BINDGEN_ALLOWLIST_TYPES。

开启特定功能集进行测试

以下是一个在ICU 67上运行docker测试的示例，其中启用了icu_version_in_env和renaming功能，而不是默认功能。请注意，参数大多是通过环境变量传递到运行docker-test的容器的。

make DOCKER_TEST_ENV=rust_icu_testenv-67 \
  RUST_ICU_MAJOR_VERSION_NUMBER=67 \
  DOCKER_TEST_CARGO_TEST_ARGS='--no-default-features --features icu_version_in_env,renaming' \
  docker-test

一些说明

• 环境变量 RUST_ICU_MAJOR_VERSION_NUMBER 用于功能 icu_version_in_env，以指示 cargo 使用文件 rust_icu_sys/bindgen/lib_67.rs 作为预构建的 bindgen 源文件，而不是尝试动态生成。
• 环境变量 DOCKER_TEST_CARGO_TEST_ARGS 用于将命令行参数传递到在 docker 容器中使用的 cargo test。环境变量以原始形式传递给 cargo test 而不加引号，因此环境变量中的单词最终成为 cargo test 的单独参数。
• 环境变量 DOCKER_TEST_ENV 是用于运行测试的 Docker 容器的基准名称。容器 rust_icu_testenv-67 是包含预安装环境并编译 ICU 67 版本的容器镜像。

刷新静态 bindgen 文件

需要 docker。

定期运行 make static-bindgen 以刷新静态生成的 bindgen 文件（命名格式为 lib_XX.rs，其中 XX 是 ICU 版本，例如 67），这些文件位于目录 rust_icu_sys/bindgen 中，当 bindgen 功能关闭时使用。

调用此 make 目标将修改包含较新版本的文件 lib_XX.rs 的本地检查。创建一个 pull request 并将其提交。

有关为什么需要此信息的更多信息，请参阅 bindgen README.md。