C2Rust

C2Rust帮助您将符合C99规范的代码迁移到Rust。翻译器（或转译器）c2rust transpile产生与输入C代码非常相似的不可安全Rust代码。翻译器的主要目标是保留功能；在翻译后，测试套件应继续通过。

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

这就是整体情况

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

文档

要了解有关使用和开发C2Rust的更多信息，请查看手册。手册仍在进行中，如果您找不到某些内容，请告知我们。

安装

先决条件

C2Rust需要7.0或更高版本的LLVM及其相应的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版本，例如

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还支持对源文件的简单转换，例如

c2rust transpile project/*.c project/*.h

（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 文件

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

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

... 使用 cmake

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

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 ...

... 使用 meson

使用 meson 创建初始构建目录时，它将自动在 <build_dir> 内生成一个 compile_commands.json 文件。

meson setup <build_dir>

... 使用 intercept-build

intercept-build（scan-build 工具的一部分）推荐用于非 cmake 项目。它捆绑在 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 上无法正常工作。

在翻译成Rust之前，我们运行C预处理器来将代码特定化到宿主平台。因此，目前我们不支持交叉编译翻译后的代码。

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

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

致谢和许可

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

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

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