Crate include_data

include_data - Include typed data directly in your executable

The primary API is provided by two macros:

• include_data - include static data as any plain-old-data type
• include_slice - include static data as &'static [T] slice for any plain-old-data T

Soundness of types for this purpose is guaranteed via the AnyBitPattern trait from the bytemuck crate. This trait can be implemented on any type and so long as that implementation is sound, then these macros are also sound. As the name suggests, this is true exactly when the type can contain any bit pattern of the correct size.

So for core library types, the following works out of the box:

static MY_INTEGER: i32 = include_data!("../tests/test_data/file_exactly_4_bytes_long");
static SOME_TEXT: &[u32] = include_slice!(u32, "../tests/test_data/some_utf-32_file");
const FOUR_BYTES: [u8; 4] = include_data!("../tests/test_data/file_exactly_4_bytes_long");

Note that include_data works with const, while include_slice only supports static.

For custom types:

#[repr(C)]
#[derive(Copy, Clone)]
struct Foo {
    integer: u16,
    pair: [u8; 2],
}

// Safety: the type `Foo` has been checked to satisfy all requirements of
// `AnyBitPattern`.
unsafe impl bytemuck::Zeroable for Foo {}
unsafe impl bytemuck::AnyBitPattern for Foo {}

static FOO_DATA: Foo = include_data!("../tests/test_data/file_exactly_4_bytes_long");

If necessary, this crate also provides the include_unsafe macro, which is sound if and only if the included file is a valid bit pattern for the target type, but this is not checked. This should be avoided unless absolutely necessary, since it is very unsafe and its soundness is fragile (in some cases, soundness may be broken by a compiler update). See the macro docs for more details.

// This struct contains a `bool`, which is only valid for bit patterns of
// 0x00 and 0x01, so does not satisfy `bytemuck::AnyBitPattern` and thus
// requires `include_unsafe`.
#[repr(C)]
struct StructWithBool {
    boolean: bool,
    two_bytes: u16,
}

static BAR_DATA: StructWithBool = unsafe { include_unsafe!("../tests/test_data/file_exactly_4_bytes_long") };

Platform-specific behaviour

The interpretation of multi-byte sequences depends on a machine’s endianness. In the case of these macros, multi-byte sequences will be interpreted into types according to the endianness of the compilation target, not the compilation host machine.

The interpreation of paths passed to these macros is host-platform specific and identical to that of core::include_bytes.

Macros

include_data

Include data from a file as static data in the executable, of a type that implements bytemuck::AnyBitPattern.

include_f32s

Alias of include_slice(f32, path). Returns a &'static [f32].

include_f64s

Alias of include_slice(f64, path). Returns a &'static [f64].

include_i8s

Alias of include_slice(i8, path). Returns a &'static [i8].

include_i16s

Alias of include_slice(i16, path). Returns a &'static [i16].

include_i32s

Alias of include_slice(i32, path). Returns a &'static [i32].

include_i64s

Alias of include_slice(i64, path). Returns a &'static [i64].

include_i128s

Alias of include_slice(i128, path). Returns a &'static [i128].

include_isizes

Alias of include_slice(isize, path). Returns a &'static [isize].

include_slice

Include data from a file as static data, consisting of a slice of bytemuck::AnyBitPattern types.

include_u8s

Alias of include_slice(u8, path). Returns a &'static [u8].

include_u16s

Alias of include_slice(u16, path). Returns a &'static [u16].

include_u32s

Alias of include_slice(u32, path). Returns a &'static [u32].

include_u64s

Alias of include_slice(u64, path). Returns a &'static [u64].

include_u128s

Alias of include_slice(u128, path). Returns a &'static [u128].

include_unsafe

Include data from a file as static data in the executable, without checking validity.

include_usizes

Alias of include_slice(usize, path). Returns a &'static [usize].