如何正确使用 include-what-you-use

简单地说，由 Google 开发的 include-what-you-use（IWYU）让源代码文件包含代码里用到的所有头文件。这种方法确保在改动了一些接口之后，代码依然最有可能编译成功。

之前我写了一篇关于 include-what-you-use 工具的文章，它会建议使用提前声明来加速编译时间，并且检测可能导致可移植性问题的对间接包含的意外依赖。

但是，你也可能注意到该工具引起的一些负面问题。

1、问题：确保间接包含

你首先会注意到的一个问题是，遵循“包含你所使用的”有时候会造成一些困扰。使用一种包含其它头文件的“便捷头文件”是一种常见操作，许多 Boost 类库使用了这一方法。例如，我们包含了 boost/mp11.hpp 来使用所有 Boost.Mp11 里提供的元编程相关的工具。

#include <boost/mp11.hpp>using my_types = boost::mp11::mp_list<int, char, float>;

但是 IWYU 并不知道这一点，相反它建议我们包含 boost/mp11/detail/mp_list.hpp 以使用 mp_list，而这显然是错的。

如果你在编写一个类库，你可以使用一种特殊的注释来修复该问题 // IWYUpragma: export：

// somewhere in a Boost.Mp11 header file
#include <boost/mp11/detail/mp_list.hpp> // IWYU pragma: export

这里告诉了 IWYU 这一行的头文件里的内容都确认被上面包含的头文件包含了并可以使用。

提示：当编写类库是使用“便捷头文件”并且要使用 IWYU，使用 // IWYU pragma: export （或者是更加常用的 begin_exports/end_exports）来标识已经确认包含了的头文件。

如果你不是在编写类库，使用 // IWYU pragma: keep 来告诉IWYU 确保该头文件要被保留检测到，但是并没有指令能确认包含该头文件就一定是正确的。

所以的指令可以在这里查看：https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUPragmas.md

2、非侵入指令：映射文件

解决以上问题有个非侵入式的方法：创建映射文件，在映射文件里你可以定义哪些符号应该对应哪些头文件。

在我们的例子里，我们想指定 boost::mp11::mp_list 是由 boost/mp11.hpp 提供的。所以我们创建一个 mp11.imp 文件，包含以下内容:

[
{ symbol: ["boost::mp11::mp_list", "private", "<boost/mp11.hpp>", "public"] }
]

该文件的语法类似 JSON，包含了一些数组类型的指令。在这里，我们使用 symbol 指令，来指定具有某种可见性（因为某些原因这里必须是 private）的某个特定符号（boot::mp11::mp_list），是由某个具有某种可见性（通常是 public）的指定头文件（boost/mp11.hpp）提供的。

然后我们使用 -Xiwyu -mapping_file=mp11.imp 将这该映射文件传递给 IWYU，IWYU 就不会在提示过多的信息了。

提示：使用一个符号映射文件来告诉 IWYU 你要包含哪些头文件，所有符号都可以用该方法，但是有点太过繁琐。

不过好在还有个更好的方法：我们可以使用 include 指令来将一个头文件重映射到另一个头文件，或者将一整个文件夹重映射到一个头文件：[ { include: [“@<boost/mp11/.*>”, “public”, “<boost/mp11.hpp>”, “public”] } ]

这里的 @ 是一个通配符，我们在这里把在指定文件夹里的所有头文件（我们认为是公共的）映射到另一个头文件（我们认为也是公共的）。

IWYU 不会再提示任何 boost/map11/*里的头文件，而是提示 boost/mp11.hpp。而既然我们已经在代码里包含了，所以也就一切正常。

提示：使用包含映射让一个头文件或者多个头文件映射为另一个头文件。

最后的指令是 ref，让多个 .imp文件合并为一个。

请查看这些关于映射文件的文档：https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md

3、结论

就个人来讲，我并不为映射文件困扰，而不必困扰是因为我从不自动运行 IWYU，一般是手动运行并查看它输出的建议变更。这样做是非常值得的，通过清理一些不必要的包含指令，我可以明显提升编译的速度。

期望以后模块化可以让这些操作变得不再必要。

4、让 IWYU 更上一层楼

在游戏、自动化、金融和其它前沿领域的公司，都面临着在高峰时段增加计算能力的需求和更快地响应市场的压力，仅仅使用 IWYU 是无法完全应对这些挑战的。

通过将任务分布在网络中的本地机器或者是虚拟机上，并且无缝地运行，Incredibuild 的创新解决方案可以为耗时的任务进行加速，例如编译、测试和其它任务。这让各种大小不同的组织都可以用一套完整的解决方案来保证速度、准确性和透明可见。

点击了解 Incredibuild 加速 C/C++ 构建编译的解决方案，并获取试用 License！