include-first

This crate provides a proc macro to evaluates include_str! macros early. This can be used to apply them in the context of a macro_rules! declaration, rather than in the context where the macro is used.

This is not an officially supported Google product. This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.

Usage

Suppose you have a macro_rules! macro in a library crate, which uses include_str! to include a file, such as some assembly code:

#[macro_export]
macro_rules! generate_asm {
    ($foo:expr) => {
        core::arch::global_asm!(
            include_str!("entrypoint.S"),
            foo = const $foo,
        );
    }
}

If you use this from another crate, the include_str! will be evaluated from the context of the crate where it is used, and rustc will look for entrypoint.S relative to that crate's source directory. This is probably not what you want.

Adding the #[include_first] attribute macro fixes this:

use include_first::include_first;

#[macro_export]
#[include_first]
macro_rules! generate_asm {
    ($foo:expr) => {
        core::arch::global_asm!(
            include_str!("entrypoint.S"),
            foo = const $foo,
        );
    }
}

Now the include_first macro will go through and evaluate all include_str! macros in the context of the library crate where it is declared, before the macro_rules! macro is created.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

If you want to contribute to the project, see details of how we accept contributions.