C2Rust

C2Rust帮助您将C99兼容代码迁移到Rust。转换器（或转换器），c2rust transpile，生成与输入C代码非常接近的不安全Rust代码。转换器的主要目标是保持功能；测试套件在转换后应继续通过。

从C生成安全且符合习惯的Rust代码最终需要人工努力。我们目前正在努力分析，以自动化将不安全Rust提升到安全Rust类型所需的部分工作。这项工作仍处于早期阶段；如果您对此感兴趣，请与我们联系！我们之前维护了一个可脚本化的重构工具，c2rust refactor，它减少了重构的繁琐性，但现在这个工具已弃用，以便我们可以与最新的Rust工具链一起前进。

这里是全景图

要了解更多信息，请观看我们在YouTube上的RustConf'18演讲，并尝试在线使用C2Rust转换器c2rust.com。

文档

要了解更多关于使用和开发C2Rust的信息，请参阅手册。手册仍在进行中，因此如果您找不到某些内容，请告诉我们。

安装

先决条件

C2Rust 需要 LLVM 7 或更高版本，以及相应的 clang 编译器和库。还需要 Python 3.6 或更高版本、CMake 3.4.3 或更高版本和 openssl (1.0)。这些先决条件可以通过以下命令安装，具体取决于您的平台：

• Ubuntu 18.04、Debian 10 及更高版本

  apt install build-essential llvm clang libclang-dev cmake libssl-dev pkg-config python3 git
  

根据 LLVM 发行版的不同，可能还需要 llvm-dev 包。例如，来自 apt.llvm.org 的官方 LLVM 软件包需要安装 llvm-dev。

• Arch Linux

  pacman -S base-devel llvm clang cmake openssl python
  

• NixOS / nix

  nix-shell
  

• macOS: 需要Xcode命令行工具和最近的 LLVM（我们推荐使用 Homebrew 版本）。

  xcode-select --install
  brew install llvm python3 cmake openssl
  

C2Rust 转换器现在使用稳定的 Rust 编译器进行构建。如果您正在开发其他功能，您可能需要安装正确的 nightly 编译器版本。

从 crates.io 安装

cargo install c2rust

如果您安装了多个版本，也可以显式设置 LLVM 版本，如下所示

LLVM_CONFIG_PATH=llvm-config-14 cargo install c2rust

在 macOS 上使用 Homebrew LLVM，需要将构建系统指向 LLVM 安装位置。安装路径依赖于架构

• Intel Macs

  LLVM_CONFIG_PATH=/usr/local/opt/llvm/bin/llvm-config cargo install c2rust
  

• Apple Silicon Macs

  LLVM_CONFIG_PATH=/opt/homebrew/opt/llvm/bin/llvm-config cargo install c2rust
  

在 Linux 上使用 Linuxbrew LLVM，需要按照以下方式将构建系统指向 LLVM 安装位置

LLVM_CONFIG_PATH=/home/linuxbrew/.linuxbrew/opt/llvm/bin/llvm-config cargo install c2rust

注意：如果 Linuxbrew 安装到您的家目录，请相应地调整 LLVM_CONFIG_PATH。

在 Gentoo 上，需要按照以下方式将构建系统指向 libclang.so 和 llvm-config 的位置

LLVM_CONFIG_PATH=/path/to/llvm-config LIBCLANG_PATH=/path/to/libclang.so cargo install c2rust

如果您在构建和安装时遇到问题，或者想要从最新的 master 版本构建，开发者文档提供有关构建系统的更多详细信息。

从 Git 安装

如果您想检查我们最近开发的功能或迫切需要 c2rust 的 bugfixed 版本，您可以直接从 Git 安装它

cargo install --git https://github.com/immunant/c2rust.git c2rust

请注意，master 分支处于持续开发中，您可能会遇到问题或崩溃。

如果需要，您还应该像上面描述的那样设置 LLVM_CONFIG_PATH。

C 到 Rust 的转换

要转换 compile_commands.json（见下文）中指定的 C 文件，请使用 c2rust 工具的 transpile 子命令运行

c2rust transpile compile_commands.json

（c2rust refactor 工具也可用于重构 Rust 代码，请参阅重构，但现在正在被一种更健壮的重构方式所取代。）

转换器需要用于构建 C 代码的确切编译器命令。这些信息通过名为 compile_commands.json 的 编译数据库 文件提供。（有关编译数据库的更多信息，请参阅此处）。许多构建系统可以自动生成此文件；我们下面展示了几个示例。

一旦您有了描述 C 构建的 compile_commands.json 文件，可以使用以下命令将 C 代码转换为 Rust：

c2rust transpile path/to/compile_commands.json

要为 Rust 库生成 Cargo.toml 模板，请添加 -e 选项

c2rust transpile --emit-build-files path/to/compile_commands.json

要为 Rust 二进制文件生成 Cargo.toml 模板，请这样做

c2rust transpile --binary myprog path/to/compile_commands.json

其中 --binary myprog 告诉转换器使用 main 函数从 myprog.rs 作为二进制的入口点。

转换后的 Rust 文件不会像正常的 Rust 模块那样直接相互依赖。它们将通过 C API 导出和导入函数。这些模块可以编译成一个单独的静态 Rust 库或二进制文件。

该翻译器存在一些已知限制。翻译器会发出警告并尝试跳过无法翻译的函数定义。

生成 compile_commands.json 文件

compile_commands.json 文件可以使用 cmake、intercept-build 或 bear 自动创建。

建议从编译数据库中移除优化（-OX），因为我们不支持翻译这些优化内置函数。

... 使用 cmake

使用 cmake 创建初始构建目录时，指定 -DCMAKE_EXPORT_COMPILE_COMMANDS=1。这仅适用于配置为使用 cmake 构建的工程。这适用于 Linux 和 MacOS。

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 ...

... 使用 intercept-build

intercept-build（scan-build 工具的一部分）适用于非 cmake 项目。 intercept-build 与 clang 一起打包在 tools/scan-build-py 下，但可以通过 pip 轻松安装独立版本：

pip install scan-build

用法

intercept-build <build command>

您还可以使用 intercept-build 为编译单个 C 文件生成编译数据库。例如

intercept-build sh -c "cc program.c"

... 使用 bear（仅限 Linux）

如果您已安装 bear，则可以使用它类似于 intercept-build

bear <build command>

... 使用 compiledb

如果其他工具不起作用，则可以使用 compiledb 软件包为 makefile 项目。通过 pip 安装：

pip install compiledb

用法

# After running
./autogen.sh && ./configure # etc.
# Run
compiledb make

联系

要报告翻译或重构问题，请使用我们的 问题跟踪器。

要联系开发团队，请加入我们的 Discord 频道 或通过 [email protected] 发送电子邮件。

常见问题解答（FAQ）

我在平台 X 上翻译了代码，但在平台 Y 上运行不正确。

我们在翻译到 Rust 之前运行 C 预处理器以专门化代码到宿主平台。因此，我们目前不支持交叉编译翻译的代码。

C2Rust 可以在哪些平台上运行？

翻译和重构工具支持 macOS 和 Linux。其他功能，如检查 C 和 Rust 代码之间的功能，目前仅限于 Linux 主机。

致谢和许可

本材料可在 LICENSE 文件中找到的 BSD-3 风格许可下使用。

C2Rust 翻译器受 Jamey Sharp 的 Corrode 翻译器的启发。我们依靠 Emscripten 的 Relooper 算法来翻译任意 C 控制流。

本材料是基于美国空军和 DARPA 的资助下进行的，资助合同号为 No. FA8750-15-C-0124。本材料中表达的意见、发现和结论或建议是作者（们）的意见，不一定反映美国空军和 DARPA 的观点。分发声明 A，“公开发布，无限分发”。