C2Rust

<!-- ANCHOR: intro -->

Intro

C2Rust helps you migrate C99-compliant code to Rust. The translator (or transpiler), c2rust transpile, produces unsafe Rust code that closely mirrors the input C code. The primary goal of the translator is to preserve functionality; test suites should continue to pass after translation.

Generating safe and idiomatic Rust code from C ultimately requires manual effort. We are currently working on analysis to automate some of the effort required to lift unsafe Rust into safe Rust types. However, we are building a refactoring tool that reduces the tedium of doing so. This work is still in the early stages; please get in touch if you're interested!

You can also cross-check the translated code against the original (tutorial).

Here's the big picture:

To learn more, check out our RustConf'18 talk on YouTube and try the C2Rust translator online using the Compiler Explorer. This uses the current master branch, updated every night.

<!-- ANCHOR_END: intro -->

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.

<!-- ANCHOR: installation -->

Installation

Prerequisites

C2Rust requires LLVM 7 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 18.04, Debian 10, 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-14 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@21/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-2022-08-08. 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-2022-08-08 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.

<!-- ANCHOR_END: installation --> <!-- ANCHOR: translating-c-to-rust -->

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 compilation databases here). Many build systems can automatically generate this file; we show a few examples below.

Once you have a compile_commands.json file describing the C build, translate the C code to Rust with the following command:

c2rust transpile path/to/compile_commands.json

To generate a Cargo.toml template for a Rust library, add the --emit-build-files option:

c2rust transpile --emit-build-files path/to/compile_commands.json

To generate a Cargo.toml template for a Rust binary, do this:

c2rust transpile --binary myprog path/to/compile_commands.json

Where --binary myprog tells the transpiler to use the main function from myprog.rs as the entry point for a binary. This can be repeated multiple times for multiple binaries.

The translated Rust files will not depend directly on each other like normal Rust modules. They will export and import functions through the C API. These modules can be compiled together into a single static Rust library or binary.

You can run with --reorganize-definitions (which invokes c2rust-refactor), which should deduplicate definitions and directly import them with uses instead of through the C API.

The refactorer can also be run on its own to run other refactoring passes:

c2rust refactor --cargo $transform

There are several known limitations in this translator. The translator will emit a warning and attempt to skip function definitions that cannot be translated.

Generating compile_commands.json Files

The compile_commands.json file can be automatically created using either cmake, meson, bear, intercept-build, or compiledb.

It may be a good idea to remove optimizations (-OX) from the compilation database, as there are optimization builtins which we do not support translating.

... with cmake

When creating the initial build directory with cmake, specify -DCMAKE_EXPORT_COMPILE_COMMANDS=1. This only works on projects configured to be built by cmake. This works on Linux and MacOS.

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 ...

... with meson

When creating the initial build directory with meson, it will automatically generate a compile_commands.json file inside of <build_dir>.

meson setup <build_dir>

... with bear

bear is recommended for projects whose build systems don't generate compile_commands.json automatically (make, for example, unlike cmake or meson). It can also be useful for cmake and meson to generate a subset of the full compile_commands.json, as it records all compilations that a subcommand does.

It can be installed with

apt install bear

or

brew install bear

Usage:

bear -- <build command>

<build command> can be make, make/cmake for a single target, or a single cc compilation:

bear -- make
bear -- cmake --build . --target $target
bear -- cc -c program.c

Note that since it detects compilations, if compilations are cached (by make for example), you'll need a clean build first (e.g. `m