C2Rust

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

从C生成安全和惯用的Rust代码最终需要手动努力。我们目前正在努力分析自动化将unsafe Rust提升到safe 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 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分支构建，开发文档提供了有关构建系统的更多详细信息。[开发文档](https://github.com/immunant/c2rust/blob/308da97f8ea6f76fc63d39e0fa84f0b28ee17622/c2rust-asm-casts/docs/README-developers.md#building-with-system-llvm-libraries)

从Git安装

如果您想检查我们最近开发的功能，或迫切需要修复了bug的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

（曾经还有一个用于重构Rust代码的c2rust refactor工具，但现在已经用更健壮的重构方式取代了。）

转换器需要构建C代码时使用的确切编译器命令。这些信息通过名为compile_commands.json的编译数据库文件提供。 （关于编译数据库的更多信息，请参阅[这里](https://sarcasm.github.io/notes/dev/compilation-database.html)）。许多构建系统可以自动生成此文件；我们下面展示了几个示例。

一旦有了描述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]。

常见问题解答

我在平台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，“批准公开发布，无限分发”。