c2rust

C2Rust Intro C2Rust helps you migrate C99-compliant code to Rust. The transpiler, c2rust transpile, produces unsafe Rust code that closely mirrors the input C code. The primary goal of the transpiler is to preserve functionality; test suites should continue to pass after translation. The output of c2rust transpile is unsafe and unidiomatic; it is merely the first step in a longer migration process. Generating safe and idiomatic Rust code from C ultimately requires additional work. This work can be done by a human, a large language model, a deterministic tool, or some combination thereof. flowchart LR A[C sources] --> B subgraph "C2Rust toolchain" B["`c2rust transpile`"] --> C["`c2rust refactor`"] C --> D["`c2rust postprocess`"] end D --> E[Human and/or agentic workflow] E --> F[Safe, idiomatic Rust] click B "https://github.com/immunant/c2rust/tree/master/c2rust-transpile" "c2rust transpile" click C "https://github.com/immunant/c2rust/tree/master/c2rust-refactor" "c2rust refactor" click D "https://github.com/immunant/c2rust/tree/master/c2rust-postprocess" "c2rust postprocess" Loading For instance, we provide a deterministic refactoring tool to automate cleanup across the files produced by c2rust transpile. We also provide an LLM-powered postprocessing tool for additional types of cleanup that are hard to do deterministically. Even though the postprocessor validates the output of LLMs, it can introduce errors; we recommend using it in combination with a robust test suite. You can also cross-check the translated code against the original (tutorial). You can try c2rust transpile directly in the Compiler Explorer. This uses the current master branch, updated every night. Documentation To learn more about using and developing C2Rust, check out the manual. The manual is still a work-in-progress, so if you can't find something please let us know. c2rust.com/manual/ also has not been updated since ~2019, so refer to the in-tree ./manual/ for more up-to-date instructions. Installation Prerequisites C2Rust requires LLVM 15 or later with its corresponding clang compiler and libraries. Python (through uv), CMake 3.5 or later and openssl (1.0) are also required. These prerequisites may be installed with the following commands, depending on your platform: Python: curl -LsSf https://astral.sh/uv/install.sh | sh uv venv uv pip install -r scripts/requirements.txt Ubuntu 22.04, Debian 12, and later: apt install build-essential llvm clang libclang-dev cmake libssl-dev pkg-config git Depending on the LLVM distribution, the llvm-dev package may also be required. For example, the official LLVM packages from apt.llvm.org require llvm-dev to be installed. Arch Linux: pacman -S base-devel llvm clang cmake openssl NixOS / nix: nix-shell macOS: Xcode command-line tools and recent LLVM (we recommend the Homebrew version) are required. xcode-select --install brew install llvm cmake openssl The C2Rust transpiler now builds using a stable Rust compiler. If you are developing other features, you may need to install the correct nightly compiler version. Installing from crates.io cargo install --locked c2rust You can also set the LLVM version explicitly if you have multiple installed, like this, for example: LLVM_CONFIG_PATH=llvm-config-15 cargo install --locked c2rust If you're using LLVM from Homebrew (either on Apple Silicon, Intel Macs, or Linuxbrew), you can run: LLVM_CONFIG_PATH="$(brew --prefix)/opt/llvm/bin/llvm-config" cargo install --locked c2rust or for a specific LLVM version, LLVM_CONFIG_PATH="$(brew --prefix)/opt/llvm@22/bin/llvm-config" cargo install --locked c2rust On Gentoo, you need to point the build system to the location of libclang.so and llvm-config as follows: LLVM_CONFIG_PATH=/path/to/llvm-config LIBCLANG_PATH=/path/to/libclang.so cargo install --locked c2rust If you have trouble with building and installing, or want to build from the latest master, the developer docs provide more details on the build system. Installing from Git If you'd like to check our recently developed features or you urgently require a bugfixed version of c2rust, you can install it directly from Git: cargo install --locked --git https://github.com/immunant/c2rust.git c2rust Please note that the master branch is under constant development and you may experience issues or crashes. You should also set LLVM_CONFIG_PATH accordingly if required as described above. Nightly Tools c2rust and c2rust-transpile are installed by default and can be built on stable rustc. The other tools, such as c2rust-refactor, use rustc internal APIs, however, and are thus pinned to a specific rustc nightly version: nightly-2023-04-15. These are also not published to crates.io. To install these, these can be installed with cargo with the pinned nightly. For example, cargo +nightly-2023-04-15 install --locked --git https://github.com/immunant/c2rust.git c2rust-refactor However, we recommend installing them from a full checkout, as this will resolve the pinned nightly automatically: git clone https://github.com/immunant/c2rust.git cd c2rust cargo build --release These tools, like c2rust-refactor, can then also be invoked through c2rust as c2rust refactor, assuming they are installed in the same directory. Translating C to Rust To translate C files specified in compile_commands.json (see below), run the c2rust tool with the transpile subcommand: c2rust transpile compile_commands.json c2rust also supports a trivial transpile of source files, e.g.: c2rust transpile project/*.c project/*.h For non-trivial projects, the translator requires the exact compiler commands used to build the C code. This information is provided via a compilation database file named compile_commands.json (note that it must be named exactly compile_commands.json; otherwise libclangTooling can have (silent) trouble resolving it correctly). (Read more about compil