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编译器进行构建。如果您正在开发其他功能，您可能需要安装正确的nightly编译器版本。

从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

如果您在构建和安装过程中遇到问题，或想从最新的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的编译数据库文件提供。有关编译数据库的更多信息，请参阅这里。（以下是一些生成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、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上工作不正确。

我们在翻译到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：“批准公开发布，无限分发”。