C2Rust

C2Rust 帮助你将 C99 兼容的代码迁移到 Rust。翻译器（或转换器）c2rust transpile 生成与输入 C 代码紧密对应的 unsafe Rust 代码。翻译器的首要目标是保留功能；测试套件在翻译后应继续通过。

从 C 生成安全且符合 Rust 习惯的代码最终需要手动努力。我们目前正在努力实现分析，以自动化将 unsafe Rust 转换为安全 Rust 类型所需的一些工作。这项工作还处于早期阶段；如果您对此感兴趣，请与我们联系！我们之前维护了一个可脚本化的重构工具 c2rust refactor，该工具可以减少重构的繁琐，但现在这个工具已经弃用，以便我们能够使用最新的 Rust 工具链向前发展。

这里是整体情况

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

文档

要了解更多关于使用和开发 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 编译器进行构建。如果您正在开发其他功能，可能需要安装正确的夜间编译器版本。

从 crates.io 安装

cargo install c2rust

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

LLVM_CONFIG_PATH=llvm-config-14 cargo install c2rust

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

• Intel Mac

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

• Apple Silicon Mac

  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 的修复版本，您可以直接从 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]。

常见问题解答

我在平台 X 上翻译了代码，但在平台 Y 上无法正确工作。

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

C2Rust 可在哪些平台上运行？

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

致谢和许可

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

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

本材料基于美国空军和DARPA的支持下进行的工作，合同编号为FA8750-15-C-0124。本材料中表达的意见、发现、结论或建议是作者的观点，并不一定反映美国空军和DARPA的观点。分发声明A：“批准公开发布，分发不受限制”。