C2Rust Manual

To add a new test case, simply create a new .c file. For example:

void example(unsigned buffer_size, int buffer[]) {
    /* your code here */
}

Then create a new .rs file with the following skeleton (does not need to be a buffer, can check return values as well):

# #![allow(unused_variables)]
#fn main() {
extern crate libc;

use c_file::rust_example;

use self::libc::c_int;

#[link(name = "test")]
extern "C" {
    #[no_mangle]
    fn example(_: c_uint, _: *mut c_int);
}

// The length can be any value
const BUFFER_SIZE: usize = 1024;

pub fn test_example() {
    let mut buffer = [0; BUFFER_SIZE];
    let mut rust_buffer = [0; BUFFER_SIZE];
    let expected_buffer = [/* this can be used as another measure of correctness */];

    unsafe {
        example(BUFFER_SIZE as u32, buffer.as_mut_ptr());
        rust_example(BUFFER_SIZE as u32, rust_buffer.as_mut_ptr());
    }

    assert_eq!(buffer, rust_buffer);
    assert_eq!(buffer, expected_buffer);
}
#}

The C code can do one of two things: modify some sort of buffer or return a value.

To completely skip the translation of a C file, you must add the comment //! skip_translation at the top of the file. That will prevent the case from showing up as red in the console output.

You can also mark a Rust file as unexpected to compile, by adding //! xfail to the top of the file, or just expect an individual test function to fail to run by adding // xfail prior to the function definition.

Adding //! extern_crate_X to the top of a test file will ensure extern crate X; gets added to the main binary driver. Be sure to also add the X crate to the test directory's Cargo.toml.

Similarly, //! feature_X adds #![feature(X)] to the top of the main driver file.

From the project root, run ./scripts/test_translator.py tests to run all of the tests in the tests folder. Here are a couple other handy options:

# run a subset of the tests
$ ./scripts/test_translator.py --only-directories="loops" tests
# show output of failed tests
$ ./scripts/test_translator.py --log ERROR                tests
# keep all of the files generated during testing
$ ./scripts/test_translator.py --keep=all                 tests
# get help with the command line options
$ ./scripts/test_translator.py --help

This tests directory contains regression, feature, and unit tests. A test directory goes through the following set of steps:

1. A compile_commands.json file is created for the Clang plugin in c2rust-ast-exporter to recognize its C source input

2. This JSON and the C source file are fed to the c2rust-ast-exporter to produce CBOR data of the Clang type-annotated abstract syntax tree.

3. This CBOR data is fed to the c2rust-transpile to produce a Rust source file supposedly preserving the semantics of the initial C source file.

4. Rust test files (test_xyz.rs) are compiled into a single main wrapper and main test binary and are automatically linked against other Rust and C files thanks to cargo.

5. The executable from the previous step is run one or more times parameterized to a specific test function.