Master's Thesis Submission

C to Rust Transformation via rustfix

• use c2rust to transform C code to unsafe code
• algorithmically transform unsafe to safe, and more idiomatic, Rust

Project structure

The project structure can roughly be categorised as follows:

. 
|
├── examples               // Case-study examples of Rust code to be transformed
|
├── callgraph              // Callgraph generation 
|
├── constraint-solver      // Collects and solves constraints over Rust AST
|
├── oracle                 // High-level interface to the Rust compiler + errors
|
├── rewrite                // High-level rewrite loop
|
└── rustfix                // Main RustFix driver
|
└── tests                  // Tests for the rustfix tool

Building rustfix

We have implemented rustfix on the nightly-2021-12-04 channel. To build rustfix, one has to first switch to the nightly-2021-12-04 channel. The first step is to use rustup, Rust's toolchain installer, to install nightly-2021-12-04. If rustup is not installed yet, please visit: https://doc.rust-lang.org/book/ch01-01-installation.html

Once rustup is installed, to install the nightly-2021-12-04 channel, run

rustup toolchain install nightly-2021-12-04

Next, switch the Rust compiler over to the nightly-2021-12-04 channel:

rustup default nightly-2021-12-04 

Finally, for access to the internal workings of the Rust compiler, as well as other useful tools, run:

rustup component add rust-src rustc-dev llvm-tools-preview

Then, proceed to the rewrite directory and run

cargo build

There may be several warnings (quite a few...) but if there are no errors then the build succeeded. Yay!

Alternatively, we have provided the rustfix binary in the main directory. One may be required to tell the OS where some dynamic libraries are located, however, since we use libc.

Running rustfix

The examples in the thesis can be found in the examples/array/C directory. These are the examples written in the original C code. The c2rust translated examples are then found in the examples/array/C2rust directory, and we will be using these instead. If one would like to translate C code using c2rust, an online demonstration as well as downloadable tool can be found here.

For the purposes of running rustfix, however, navigate to tests/before. Here, we have four examples, arrays, insertion_sort, matrix, qsort. Let's use qsort as an example. In tests/qsort/src, we have main.rs and main_as_rs.rs. Both files are identical; main_as_rs.rs simply serves as a baseline to compare the program code with after the rustfix translation.

To run rustfix, navigate back to the rewrite/ directory. Then, run cargo run [directory of main.rs or lib.rs] to run the tool on a file or large project respectively. For our purposes, let's run the rustfix tool on qsort with the following command:

cargo run ../tests/before/qsort/src/main.rs

One can then open up the ../tests/before/qsort/src/main.rs file to see that the Quicksort program has been refactored!

Remember that to run rustfix, one has to be in the rewrite/ directory.

Running the randomized tests

To verify the results of the refactoring, navigate to tests/after. Here, for each example, we have provided the program code before refactoring and after refactoring. Consider the Quicksort program again. In the program code after refactoring, which is available at tests/after/qsort/src/main.rs, we have attached a test suite to the end of the program. This test suite is the same test suite that was also mentioned in the thesis (see: Evaluation and Case Studies chapter). Essentially, across 100 iterations, it randomly generates a vector of size 10000 with elements randomly selected from the range 1 to 10000. Then, it runs our refactored Quicksort on it and checks that the vector is indeed sorted.

One can run the test for each example by navigating to the respective directory, in this case tests/after/qsort, and running

cargo test