include-first 0.1.0

Proc macro to evaluate include_str! macros early.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

# include-first

[![crates.io page](https://img.shields.io/crates/v/include-first.svg)](https://crates.io/crates/include-first)
[![docs.rs page](https://docs.rs/include-first/badge.svg)](https://docs.rs/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](https://bughunters.google.com/open-source-security).

## 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:

```rust
#[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:

```rust
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](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license
  ([LICENSE-MIT](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](CONTRIBUTING.md).