包含工具

包含工具的参考指南,用于将现有C++项目转换为一个IWYU类型。

Windows
MacOS
Linux
本页面的内容

警告: 包含工具用于转换大量内部Epic项目,其中包括虚幻引擎4(UE4)。此工具免费试用,但我们提供的支持等级也有所限制。

包含工具 可用于将现有的C++项目转换为一个包含您所使用(IWYU)类型。其工作原理是尝试从每个头文件形成自含式转译单元。虽然基于启发法的它能节约大量时间,但却不太可能形成完美的结果。相反,它会构成一个起点,您可以此为基础进行手动编辑来完成转换。它运行较为暴力(耗时较长,完成大型项目的转换可能需要数天时间)、难以进行迭代、可能需要按每个项目进行修改,而且难以进行调试。

操作工具

包含工具的操作包含数个阶段,解释如下:

  • 虚幻编译工具由一个目标触发,生成一个编译步骤列表。建议使用项目的编辑器目标,因为它包含的代码路径通常多于任何其他目标类型。我们还建议Linux编译使用来自Windows的交叉编译工具链,以便使用Clang工具链。使用Clang十分重要,因为Visual C++不进行两阶段名称查找,而无法在这些模板被实例化之前从依赖类上的模板类中找到依赖性,从而形成高度不可读的输出。 

  • 源文件由内部预处理器进行部分预处理。这并不会转换标记化的源文件本身,而是确定当前目标的哪些代码块活跃、哪些不活跃,并将每个文件分割成一系列片段。每个片段定义了源文件中 #include 指令之间的一系列代码行,这意味着任何源文件的单文件版本都可以在任何点进行组装,方式是递归式遵循 #include 指令,并串联遇到的片段列表。

  • 此步骤十分重要,因为它是包含工具将会优化的片段列表。在此阶段中,包含工具将验证一些限制并发出警告。一些警告看似过于迂腐和形式化,但对确保输出有效而言,它们十分必要。以下警告尤其需要注意:

    • 头文件之间不应有包含循环。

    • 所包含的源文件必须由每个转译单元以相同的方式进行预处理(举例而言,所有宏在包含的每个情境中被定义的方式都必须一致)。

  • 每个片段都会被写入工作文件夹。每个源文件按其原始布局输出,以保留行数量,并注释掉属于其他片段的行。

  • 将针对看似可以前置声明的符号的模式来对源文件进行标记化和搜索。(举例而言:“class Foo { ...”)

  • 每个源文件皆为强力编译,以确定成功编译所依赖的片段。这是转换中最费力的部分,但此分析的结果存储在工作目录中,如果源文件未改变则应该可以重复使用。该工具还支持使用多台PC计算依赖性数据的“切分”模式(如下所述)。

  • 搜索的结构如下:

    • 输入转译单元被扩展为由片段序列(1...n)表示。

    • 一组所需片段(r)被初始化为仅存在于输入文件中的片段(而并非被输入文件包括的片段)。

    • 将执行二进制搜索来找到源文件成功编译所需的片段最长序列(1...m,带r)。

    • 将序列(m)中的最后一个片段添加到所需组(r)中。如果“m”已经被优化,则其依赖性也将被添加到r。

    • 对片段序列(1...m - 1)重复二进制搜索。

  • 每个输出文件都是用最小的一组包含项编写的,以便进行单独编译。启发法尝试直接包括包含名称显式引用的符号的所有依赖性的标头,并且仅在非递归式包括其他依赖性的情况下才将其他依赖性包含在内。

使用范例

执行片段分析并输出诊断信息:

-Mode=Scan -Target=FooEditor -Platform=Linux -Configuration=Development -WorkingDir=D:\Working

优化基本代码:

-Mode=Optimize -Target=FooEditor -Platform=Linux -Configuration=Development -WorkingDir=D:\Working -OutputDir=D:\Output -SourceFiles=-/Engine/... -OptimizeFiles=-/Engine/... -OutputFiles=-/Engine/...

可以传递几个过滤参数来限制源文件迭代(-SourceFiles-OptimizeFiles-OutputFiles)。每个都可以使用P4式通配符的分号列表,来包括(/Engine/...)或排除(-/Engine/Foo.cpp)文件,或可以指定拥有规则的响应文件,每行写入(D:\ Filter.txt)。整体而言,您可能不希望重新优化引擎代码,因此将所有这些内容从分析中排除是有道理的。

由于程序可能需要很长时间才能运行,所以它能够以“切分”模式运行。如果您有多台PC都同步到同一个源树,则可以使用 -Shard=N-NumShards=M 来配置一台机器,使其只考虑输入组的一部分。每台机器上的工作目录应相同,且得到的工作目录可复制到一起,用于在一台机器上进行最终运行,生成输出文件。

注意: 参见 Program.cs 中的注释了解其他模式(查找 ToolMode 列举)和命令行选项(CommandLineOptions 类)。

欢迎来到全新虚幻引擎4文档站!

我们正在努力开发新功能,包括反馈系统,以便您能对我们的工作作出评价。但它目前还未正式上线。如果您对此页面有任何意见与在使用中遭遇任何问题,请前往文档反馈论坛告知我们。

新系统上线运行后,我们会及时通知您的。

发表反馈意见