rusty-cheddar
rusty-cheddar is a library for converting Rust source files into C header files.
A note on versioning: While rusty-cheddar is still in a significant flux (i.e.
pre-v1.0.0
) it will likely go through numerous breaking changes. However, until v1.0.0
, any
time a breaking change is made the minor version will be bumped and any time a new feature is
added the path version will be bumped.
rusty-cheddar targets C99 or later (for sane single line comments and use of stdint.h
and
stdbool.h
), if you really really really really really have to use an older standard then please
open an issue at the repo and I will begrudgingly figure out how to implement support for it
(after arguing with you lots and lots).
The most useful way to use rusty-cheddar is in a build script. To do this add the following
build-dependencies
section to your Cargo.toml
(to use it as a normal library simply replace
build-dependencies
with dependencies
):
# Cargo.toml
[]
= "0.3.0"
Then create the following build.rs
:
// build.rs
extern crate cheddar;
This should work as is providing you've set up your project correctly. Don't forget to add a
build = ...
to your [package]
section, see the cargo docs for more info.
rusty-cheddar will then create a my_header.h
file in include/
. Note that rusty-cheddar
emits very few warnings, it is up to the programmer to write a library which can be correctly
called from C.
API In a Module
You can also place your API in a module to help keep your source code neat. To do this you must supply the name of the module to Cheddar, then ensure that the items are available in the top-level scope:
// build.rs
extern crate cheddar;
// src/lib.rs
pub use c_api::*;
There is also the .compile()
and .compile_code()
methods for finer control.
Conversions
In the examples below, boilerplate has been omitted from the header.
Typedefs
rusty-cheddar converts pub type A = B
into typedef B A;
. Types containing generics are ignored.
Rust:
type UInt32 = u32;
pub type UInt64 = u64;
pub type MyOption<T> =
Header:
// Some boilerplate omitted.
typedef uint64_t UInt64;
// Some more boilerplate omitted.
Enums
rusty-cheddar will convert public enums which are marked #[repr(C)]
. If the enum is generic or
contains tuple or struct variants then cheddar
will fail. rusty-cheddar should correctly handle
explicit discriminants.
Rust:
// This would fail is it was #[repr(C)].
// This would fail if it was public.
Header:
// Some boilerplate omitted.
typedef enum Colours Colours;
// Some more boilerplate omitted.
Structs
Structs are handled very similarly to enums, they must be public, marked #[repr(C)]
, and they must not
contain generics (this currently only checked at the struct-level, generic fields are not checked).
Rust:
Header:
// Some boilerplate omitted.
typedef struct Person Person;
// Some more boilerplate omitted.
Opaque Structs
One common C idiom is to hide the implementation of a struct using an opaque struct, which can only be used behind a pointer. This is especially useful in Rust-C interfaces as it allows you to use any arbitrary Rust struct in C.
To define an opaque struct you must define a public newtype which is marked as #[repr(C)]
.
Rust:
;
Header:
// Some boilerplate omitted.
typedef struct MyCrate_Foo MyCrate_Foo;
// Some boilerplate omitted.
Note that the newtype must not be generic but the type that it wraps can be arbitrary.
Functions
For rusty-cheddar to pick up on a function declaration it must be public, marked #[no_mangle]
and
have one of the following ABIs:
- C
- Cdecl
- Stdcall
- Fastcall
- System
I'm not totally up to speed on calling conventions so if you believe one of these has been including in error, or if one has been omitted, then please open an issue at the repo.
rusty-cheddar will fail on functions which are marked as diverging (-> !
).
Rust:
use Add;
pub extern
pub extern
pub extern
Header:
// Some boilerplate omitted.
void ;
uint8_t ;
uint16_t ;
// Some more boilerplate omitted.
Paths
You must not put types defined in other modules in an exported type signature without hiding it behind an opaque struct. This is because the C compiler must know the layout of the type and rusty-cheddar can not yet search other modules.
The very important exception to this rule are the C ABI types defined in
the libc
crate and std::os::raw
. Types from these two modules must
be fully qualified (e.g. libc::c_void
or std::os::raw::c_longlong) so that they can be converted properly. Importing them with a
use`
statement will not work.
Contributing
Contributions to rusty-cheddar are more than welcome.
Bugs
If you find a bug or have a feature request please open an issue. I can't guarantee that I'll fix it but I'll give it a damn good go.
If you find the source code unclear in any way then I consider that a bug. I try to make my source code as clear as possible but I'm not very good at it, so any help in that regard is appreciated.
PRs
I love pull requests they tend to make my job much easier, so if you want to fix a bug or implement a feature yourself then that would be great. If you're confused by anything or need some pointers on how to proceed then feel free to open an issue so that I can help, otherwise these docs are a good place to start.
Tests
The tests require you to have a recent version (> v2.7.2
) of CppHeaderParser installed for the
version of Python which is installed as python
(usually Python 2). Furthermore due to the fact
that the tests are a massive pile of wanky hacks, you must be in the same directory as
rusty-cheddar's Cargo.toml
to successfully run them.