Struct cheddar::Cheddar

pub struct Cheddar { /* fields omitted */ }

Stores configuration for the Cheddar compiler.

Examples

Since construction can only fail if there is an error while reading the cargo manifest it is usually safe to call .unwrap() on the result (though .expect() is considered better practice).

cheddar::Cheddar::new().expect("unable to read cargo manifest");

If your project is a valid cargo project or follows the same structure, you can simply place the following in your build script.

cheddar::Cheddar::new().expect("unable to read cargo manifest")
    .run_build("path/to/output/file");

If you use a different structure you should use .source_file("...") to set the path to the root crate file.

cheddar::Cheddar::new().expect("unable to read cargo manifest")
    .source_file("src/root.rs")
    .run_build("include/my_header.h");

You can also supply the Rust source as a string.

let rust = "pub type Float32 = f32;";
cheddar::Cheddar::new().expect("unable to read cargo manifest")
    .source_string(rust)
    .run_build("target/include/header.h");

If you wish to hide your C API behind a module you must specify the module with .module() (don't forget to pub use the items in the module!).

cheddar::Cheddar::new().expect("unable to read cargo manifest")
    .module("c_api").expect("malformed header path")
    .run_build("header.h");

Methods

impl Cheddar

fn new() -> Result<Cheddar, Error>

Create a new Cheddar compiler.

This can only fail if there are issues reading the cargo manifest. If there is no cargo manifest available then the source file defaults to src/lib.rs.

fn source_file<T>(&mut self, path: T) -> &mut Cheddar where
    PathBuf: From<T>, 

Set the path to the root source file of the crate.

This should only be used when not using a cargo build system.

fn source_string(&mut self, source: &str) -> &mut Cheddar

Set a string to be used as source code.

Currently this should only be used with small strings as it requires at least one .clone().

fn module(&mut self, module: &str) -> Result<&mut Cheddar, Vec<Error>>

Set the module which contains the header file.

The module should be described using Rust's path syntax, i.e. in the same way that you would use the module ("path::to::api").

Fails

If the path is malformed (e.g. path::to:module).

fn insert_code(&mut self, code: &str) -> &mut Cheddar

Insert custom code before the declarations which are parsed from the Rust source.

If you compile a full header file, this is inserted after the #includes.

This can be called multiple times, each time appending more code.

fn compile_code(&self) -> Result<String, Vec<Error>>

Compile just the code into header declarations.

This does not add any include-guards, includes, or extern declarations. It is mainly intended for internal use, but may be of interest to people who wish to embed moz-cheddar's generated code in another file.

fn compile(&self, id: &str) -> Result<String, Vec<Error>>

Compile a header.

id is used to help generate the include guard and may be empty.

fn write<P: AsRef<Path>>(&self, file: P) -> Result<(), Vec<Error>>

Write the header to a file.

fn run_build<P: AsRef<Path>>(&self, file: P)

Write the header to a file, panicking on error.

This is a convenience method for use in build scripts. If errors occur during compilation they will be printed then the function will panic.

Panics

Panics on any compilation error so that the build script exits and prints output.

fn print_error(&self, error: &Error)

Print an error using the ParseSess stored in Cheddar.