Skip to content

Latest commit

 

History

History
65 lines (47 loc) · 2.79 KB

README.md

File metadata and controls

65 lines (47 loc) · 2.79 KB
Raw

Docs

C2Rust Transpiler

Basic Usage

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

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

The transpiler can also be given source files directly, which is ideal for projects that are trivially compiled, e.g.:

c2rust transpile [args] *.h *.c [-- extra-clang-args]

The following arguments control the basic transpiler behavior:

  • --emit-modules - Emit each translated Rust file as a module (the default is to make each file its own crate).
  • --fail-on-error - Fail instead of warning if a source file cannot be fully translated.
  • --reduce-type-annotations - Do not emit explicit type annotations when unnecessary.
  • -f <regex>, --filter <regex> - Only translate files based on the regular expression 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 translated Rust code as a library. Build files are emitted in the directory specified by --output-dir, or if not specified, the directory containing compile_commands.json. This will not overwrite existing files, so remove these build files before re-creating build files. (implies --emit-modules)
  • -b <main_module>, --binary <main_module> - Emit cargo build files to build the translated Rust code as a binary. The main function must be found in the specified module (C source file) <main_module>. <main_module> should be the bare module name, not including the .rs extension. Build files are emitted in the directory specified by --output-dir, or if not specified, the directory containing compile_commands.json. This will not overwrite existing files, so remove this build file directory before re-creating build files. (implies --emit-build-files)

Cross-check instrumentation

The transpiler can instrument the transpiled Rust code for cross-checking. The following options control this instrumentation:

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

For Developers

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