Rustifact  

A seamless bridge between a build script and the main crate.

Motivation

When it comes to generating computationally intensive artifacts at compile time, we have many tools at our disposal: build scripts (build.rs), declarative macros (macro_rules!), procedural macros, and increasingly, const functions. Each of these methods, however, brings its own set of challenges.

Rustifact has been designed as an abstraction layer that simplifies the creation of build scripts that produce data for inclusion into the final binary.

Types supported

Rustifact allows static and const declarations of data types composed of numeric types (floats, ints, usize), booleans, strings, arrays, structs, and enums. Also supported are (unordered and ordered) sets and maps with perfect-hash lookup.

(*) Sets and maps are provided with help from the excellent phf_codegen library, though these features are gated via the set and map features.

(*) Jagged array support is available via the rustifact_extra crate.

Usage steps

1. Generate the required data in your build script.

2. #[derive(ToTokenStream)] for any custom types(*) (not in the Rust standard library) exported from your build script.

3. Export your data with any combination of the write_X macros.

4. In the main part of your crate (within src/) import your data with use_symbols.

(*) These types should be implemented in a separate crate, so they're usable from the build script and the main crate.

NOTE: We refer to exclusively to data in the above, but Rustifact is also capable of generating types in some situations where doing so by hand would be burdensome.

A simple example

build.rs

use rustifact::ToTokenStream;

fn main() {
    // Write a constant of type Option<(i32, i32)>
    let a = Some((1, 2));
    rustifact::write_const!(CONST_A, Option<(i32, i32)>, &a);
    // Write a static variable of type &'static str. Strings map to static string slices.
    let b = format!("Hello {}", "from Rustifact");
    rustifact::write_static!(STATIC_B, &'static str, &b);
    // Write a getter function returning Vec<Vec<i32>>
    let c = vec![vec![1], vec![2, 3], vec![4, 5, 6]];
    rustifact::write_fn!(get_c, Vec<Vec<i32>>, &c);
    // Write a static array of i32 with dimension two.
    let arr1: [[i32; 3]; 3] = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
    rustifact::write_static_array!(ARRAY_1, i32 : 2, &arr1);
    // Write a const array of f32 with dimension one.
    let arr2: [f32; 3] = [1.1, 1.2, 1.3];
    rustifact::write_const_array!(ARRAY_2, f32 : 1, &arr2);
    // or equivalently: rustifact::write_const_array!(ARRAY_2, f32, &arr2);
}

src/main.rs

rustifact::use_symbols!(CONST_A, STATIC_B, get_c, ARRAY_1, ARRAY_2);

fn main() {
    assert!(CONST_A == Some((1, 2)));
    assert!(STATIC_B == "Hello from Rustifact");
    assert!(get_c() == vec![vec![1], vec![2, 3], vec![4, 5, 6]]);
    assert!(ARRAY_1 == [[1, 2, 3], [4, 5, 6], [7, 8, 9]]);
    assert!(ARRAY_2 == [1.1, 1.2, 1.3]);
}

Cargo.toml

[package]
# ...

[build-dependencies]
rustifact = "0.10"

[dependencies]
rustifact = "0.10"

More examples

• array4d Generates and exports a 4 dimensional array using write_static_array!

• city_data Generates and exports a one dimensional array using write_static_array!

• coords Demonstrates the use of custom types with #[derive(ToTokenStream)].

• html_tags Exports a large collection of individual constants using write_statics!.

• out_type Demonstrates struct export with ToTokenStream's OutType attribute.

• map Demonstrates construction of a map with lookup via a perfect hash function.

For more examples, inspect the write_X macros in the crate documentation.

Development status

Please note that Rustifact is in an early development stage. Overall, it is unlikely to cause unpleasant surprises, though there may be edge cases that haven't yet been discovered. Some breaking changes may occur in the future, though we aim to preserve backward compatibility where possible.

License

Rustifact is free software, and is released under the terms of the Mozilla Public License version 2.0. See LICENSE.