Crate ffizz_header
source ·Expand description
This crate supports generating a C header for a library crate, directly in the library itself.
Typically the crate would be annotated with ffizz_header
macros to define the header content.
Then, the header is generated by calling generate
.
Generating Headers
What follows is a simple, effective way to generate the header file, using the excellent cargo-xtask.
With this in place, simply run cargo xtask codegen
to generate the header file.
The file can either be checked in (in which case CI should verify that it is up-to-date), or generated as part of the release / packaging process.
Setup
In your library’s top level, add a call to
#[cfg(debug_assertions)] // only include this in debug builds
/// Generate the header
pub fn generate_header() -> String {
ffizz_header::generate()
}
Set up an xtask project as described in the project’s documentation.
Add your library as a dependency of the xtask crate.
In xtask/src/main.rs
, for a mysupercool-lib
crate:
use std::env;
use std::fs::File;
use std::io::Write;
use std::path::PathBuf;
fn main() {
let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
let workspace_dir = manifest_dir.parent().unwrap();
// assume the mysupercool-lib crate is in `lib/`..
let lib_crate_dir = workspace_dir.join("tests").join("lib");
let mut file = File::create(lib_crate_dir.join("mysupercoollib.h")).unwrap();
write!(&mut file, "{}", ::mysupercool_lib::generate_header()).unwrap();
}
You may wish to improve on this implementation, with proper command-line parsing and error handling.
Caveats
This method does not support producing multiple header files for a single workspace. Rust refuses to link them, due to duplicate symbols. If your workspace contains multiple libraries, another option is to build a binary for each one, that generates the header file for only that library.
Defining Headers
Typically, a library exporting a header will define its topmatter and corresponding footer in src/lib.rs
, using snippet
.
ffizz_header::snippet! {
#[ffizz(name="topmatter", order=1)]
/// ```c
/// #ifndef INFPREC_H
/// #define INFPREC_H
///
/// #include <stdint.h> // ..and any other required headesr
/// ```
}
ffizz_header::snippet! {
#[ffizz(name="bottomatter", order=10000)]
/// ```c
/// #endif /* INFPREC_H */
/// ```
}
The topmatter might also include forward declarations of types or macros.
The remaining declarations will be for types and exported functions, using item
.
It can be helpful to define a range of order
values for each source file, to keep related declarations together in the generated header.
#[ffizz_header::item]
#[ffizz(order = 900)]
/// ***** infprec_t *****
///
/// An infinite-precision integer.
/// ```c
/// typedef struct infprec_t infprec_t
/// ```
pub struct InfPrec { /* .. */ }
#[ffizz_header::item]
#[ffizz(order = 901)]
/// Add two infinite-precision numbers.
#[no_mangle]
pub unsafe extern "C" fn infprec_add(a: infprec_t, b: infprec_t) -> infprec_t { todo!() }
extern "C"
For headers intended for use in C and C++, it may be helpful to define an EXTERN_C macro:
/// #ifdef __cplusplus
/// #define EXTERN_C extern "C"
/// #else
/// #define EXTERN_C
/// #endif // __cplusplus
this can later be used in declarations like
EXTERN_C infprec_t infprec_add(infprec_t a, infprec_t b);
Macros
- Generate C header content from the included docstring.
Functions
- Generate the C header for the library.
Attribute Macros
- Generate C header content from the docstring on this item.