include_proc_macro

用法

include_proc_macro crate提供了一个宏，设计用于与外部工具轻松集成，尤其是在使用进程宏时。它非常简单，只是用一些糖包装了include!宏调用，主要用于减少样板代码和美化进程宏代码。

注意：include_proc_macro旨在作为dependency添加，尽管它仅是一个开发时依赖项。该宏本身在调试断言之外不返回任何内容，编译器足够智能，可以忽略它，因此实际上它达到了相同的效果，尽管它必须可用。

该宏检查是否启用了调试断言（#[cfg(debug_assertions)]）。如果启用了调试断言，它将在模块树中包含来自Cargo项目根目录（通过CARGO_MANIFEST_DIR环境变量获取）的针对目标的.rs文件。就这么简单。

示例

在Rust中

// lib.rs
include_proc_macro::include_proc_macro!("sample");

上面的命令在调试断言（开发时间）期间从Cargo项目的根目录包含sample.rs。它简单地展开为

#[cfg(debug_assertions)]
include!(
    concat!(
    env!("CARGO_MANIFEST_DIR"),
    "/",
    "sample", // <-- arg
    ".rs"
    )
);

宏的主要参数是

• $file_name：一个表示要包含在开发时间内模块树中的进程宏源文件（.rs）名称的字符串字面量（这有时有助于启用某些高级IDE功能）。

实际使用

您希望将宏放置在开发工具识别为模块树一部分的位置。在许多情况下，这意味着在进程宏crate的lib.rs文件中使用它。

注意：请记住，你应该 不要 在其crate的界限之外使用或依赖过程宏代码。此配置旨在反向操作：它在开发过程中将诸如自动完成等特性引入到过程宏crate中。这就是为什么我们只在调试断言期间包含它们的原因。

问题

对于某些IDE或其他编程环境，理解模块树至关重要，因为它通过提供自动完成和稳定同步等特性来提高开发者体验。这取决于具体情况，处理方式各不相同，但有时过程宏可能会成为问题。

简单来说，在Rust中，模块树是代码组织的分层表示。每个Rust文件都可以作为模块，其中嵌套了子模块，形成一个随着项目发展而演变的树状结构。

过程宏crate确实存在于这个模块树中。然而，它们的源文件通常位于crate的根目录，而不是在lib.rs文件中。此外，它们不一定被明确地声明为模块。这些与典型Rust代码的偏差可能会给依赖于“传统”项目结构的开发工具带来困难。

这不是一个普遍问题，因为它很大程度上取决于每个工具尝试解释过程宏的方式。

一个实际的解决方案是在过程宏crate中包含在lib.rs文件内的过程宏代码，尤其是在开发期间，这样就不会在发布（或其他非调试）构建中引起问题。这个决定可能会使宏对某些开发工具更容易访问，从而提高发现、自动完成、语法高亮和文档支持。

这正是此crate所做的事情。

或者，你可以使用#[path]属性与模块定义一起使用，以指向cargo根目录中的源文件，这在实践中基本上达到同样的效果。一些IDE和环境也与过程宏配合得很好，所以可能根本不需要解决方案。

虽然此crate提供的解决方案简单有效，但并非万能。最佳方法取决于多个因素，如你的工具设置、个人偏好以及项目的具体需求。尽管如此，此crate的存在为问题提供了一个简单的解决方案；将你的过程宏crate与你的其他代码连接起来，使其更容易被外部工具发现。

附加功能

此外，include_proc_macro提供了两个方便的别名，here!和named!

include_proc_macro::here!("sample"); 

请注意，使用这些别名会产生与直接使用include_proc_macro相同的结果。它们包括为了方便和使代码更美观（即当你想要/必须使用完全限定的路径时）。

注意：鉴于（未使用）宏不会引入编译时或运行时开销，命名空间污染既微不足道又不太可能发生冲突或其他问题，因此使用这些别名在我看来是可以接受的。然而，如果证明这是不可取的，我们将通过功能标志将这些隐藏起来。

支持

无论你是否使用此项目、从中学习到东西，或者只是喜欢它，请考虑通过购买我一杯咖啡来支持它，这样我可以花更多的时间在像这样的开源项目上：）

许可证

你可以在这里查看完整的许可证这里

此项目是在MIT许可证的条款下授权的。