RUST C-Binding Template

Template for creating RUST projects with a binding to C-code

Table of Contents

• Raw Crate
• Safe Crate
• Example Application
• Unit Tests

Raw Crate

The template contains a C library (libfoo.a) with the following methods:

void foo_reset();
int  foo_get_value();
void foo_set_value(int value);

The raw_foo/build.rs compiles the library with make and provides a RUST binding via bindgen (see bindings.rs):

/* automatically generated by rust-bindgen 0.59.1 */

extern "C" {
    pub fn foo_reset();
}
extern "C" {
    pub fn foo_get_value() -> ::std::os::raw::c_int;
}
extern "C" {
    pub fn foo_set_value(value: ::std::os::raw::c_int);
}

These functions are purely exported by the raw_foo crate and can be used with the unsafe keyword (see example):

unsafe {
	println!("initial raw value: {}", raw_foo::foo_get_value());
	raw_foo::foo_set_value(13);
	println!("raw value after setting 13: {}", raw_foo::foo_get_value());
	raw_foo::foo_reset();
	println!("raw value after reset: {}", raw_foo::foo_get_value());
}

Safe Crate

This crate (safe_foo) has a wrapper function for each raw/unsafe method. This brings us a safe RUST API and is the place, to convert RUST types (e.g. vectors) from/to unsafe raw pointers of the raw C binding.

In this example the wrappers look like this:

pub fn foo_set_value(value : i32) {
	unsafe {
		raw_foo::foo_set_value(value);
	}
}

Example Application

In the example application, the two creates are used:

unsafe { raw_foo::foo_set_value(13); }
...
safe_foo::foo_set_value(13);

Unit Tests

Each create defines tests for its methods:

$ cargo test
   Compiling safe_foo v0.1.0 (/home/charly/Projects/RUST/rust-cbinding-template/safe_foo)
   Compiling example v0.1.0 (/home/charly/Projects/RUST/rust-cbinding-template/example)
    Finished test [unoptimized + debuginfo] target(s) in 0.41s
     Running unittests (target/debug/deps/example-bbc66704e8a894a2)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running unittests (target/debug/deps/raw_foo-60c4440c51b6f280)

running 3 tests
test tests::initial ... ok
test tests::reset ... ok
test tests::setter ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running unittests (target/debug/deps/safe_foo-ca0ccc922d825209)

running 3 tests
test tests::initial ... ok
test tests::setter ... ok
test tests::reset ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests raw_foo

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests safe_foo

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

$