If you generate code from
include! directive isn't quite ideal for including the resulting code, for several reasons:
include!doesn't support top-level doc comments.
include!doesn't support inner directives like
- Any module directives in the included file get resolved relative to the included file, not relative to the file including them. So, if you generate
mod error;, and include it from
lib.rs, rustc looks for
There's a long history of bug reports related to each of these issues.
I'd like to propose a new directive,
include_raw!, which includes the specified file as if its text appeared directly in the module invoking
include_raw!. Any doc comments, inner directives, or module directives will get resolved as if they appeared directly in the file invoking
include_raw!. Also, unlike
include_raw! will only work in top-level item context, not in expression mode. Note that
include_raw! can still require that the text properly parse as Rust (e.g. no unmatched delimiters), and can still parse the file and include it as tokens; it should just treat those tokens as if they appeared in the including file.
@dtolnay pointed out that we could fix
include!to partially address the first two issues (though the documentation and directives wouldn't get propagated to the top level).
- I've updated this proposal to make it clear that the new directive can still parse the generated code and include it as tokens, rather than raw text.