C2Rust

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

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

这就是大局

要了解更多信息，请观看我们的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 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

如果您在构建和安装过程中遇到问题，或想从最新主分支构建，请参阅开发者文档，以获取有关构建系统的更多详细信息。

从 Git 安装

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

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

请注意，主分支正在持续开发中，您可能会遇到问题或崩溃。

如果需要，您也应该根据上述说明设置 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 告诉转换器使用 myprog.rs 中的 main 函数作为二进制的入口点。

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

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

生成 compile_commands.json 文件

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

建议从编译数据库中删除优化（-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 上运行不正确。

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

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

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

致谢和许可

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

C2Rust 翻译器灵感来源于 Jamey Sharp 的 Corrode 翻译器。我们依赖于 Emscripten 的 Relooper 算法来翻译任意的 C 控制流。

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