[![Docs]][docs.rs]

[Docs]: https://docs.rs/c2rust-transpile/badge.svg
[docs.rs]: https://docs.rs/c2rust-transpile

# 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 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](../cross-checks/). 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.