C2Rust Transpiler

Basic Usage

The transpiler module is invoked using the transpile sub-command of c2rust:

1. c2rust transpile [args] compile_commands.json [-- extra-clang-args]

The following arguments control the basic transpiler behavior:

  • —emit-modules - Emit each translated Rust file as a module (the default isto make each file its own crate).
  • —fail-on-error - Fail instead of warning if a source file cannot be fullytranslated.
  • —reduce-type-annotations - Do not emit explicit type annotations whenunnecessary.
  • —translate-asm - Translate C inline assembly into corresponding Rust inlineassembly. The translated assembly is unlikely to work as-is due to differencesbetween GCC and LLVM (used in Rust) inline assembly styles, but it can providea starting point for manual translation.
  • -f <regex>, —filter <regex> - Only translate files based on the regularexpression used.

Creating cargo build files

The transpiler can create skeleton cargo build files for the translated Rust sources, controlled by the following options:

  • -e, —emit-build-files - Emit cargo build files to build the translatedRust code as a library. Build files are emitted in the directory specified by—output-dir, or if not specified, the directory containingcompile_commands.json. This will not overwrite existing files, so removethese build files before re-creating build files. (implies —emit-modules)
  • -m <main_module>, —main <main_module> - Emit cargo build files to buildthe translated Rust code as a binary. The main function must be found in thespecified module (C source file) <main_module>. <main_module> should bethe bare module name, not including the .rs extension. Build files areemitted in the directory specified by —output-dir, or if not specified, thedirectory containing compile_commands.json. This will not overwrite existingfiles, so remove this build file directory before re-creating buildfiles. (implies —emit-build-files)

Cross-check instrumentation

The transpiler can instrument the transpiled Rust code forcross-checking. The following options control thisinstrumentation:

  • -x, —cross-checks - Add macros and build files for cross-checking.
  • —use-fakechecks - Link against the fakechecks library for cross-checkinginstead of using the default online checks.
  • -X <config>, —cross-check-config <config> - Use the given config file asthe cross-checking config.

For Developers

The c2rust-transpile library uses the c2rust-ast-exporter library to translate Ccode to Rust. The ast-exporter library links against the native clang compilerfront end to parse C code and exports the AST for use in the transpiler, whichis then implemented purely in Rust.