创建 Profile XML 文件

Profile XML 文件用于定义 Automatic Interception Interface 应如何处理各种不同的分布式作业进程。

一个示例

在此简易示例中，我们的目标是分发一个由 MainProcess.exe 运行的主进程。该主进程运行了若干个子进程 (DummySubProcess.exe),并且以一个链接步骤结束 (link.exe)。

在这种情况下，我们可能仅需要分发子进程的执行 (DummySubProcess.exe)。将简单的 link.exe 任务执行分发至远端机器，网络中会同时发送相当大量的数据（.obj 文件等），因此最好始终在启动机器上运行任务。

语法

以下 profile.xml 可用于运行 Automatic Interception Interface：

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<Profile FormatVersion="1">
    <Tools>
        <Tool Filename="MainProcess" AllowIntercept="true" />
        <Tool Filename="DummySubProcess" AllowRemote="true" />
        <Tool Filename="link" AllowRemote="false" />
    </Tools>
</Profile>

以下命令规定 DummySubProcess.exe 须执行 10 次：

IBConsole  /command="MainProcess.exe DummySubProcess.exe 10"  /profile="profile.xml"

说明

• MainProcess.exe 即正在运行的主进程。由于此进程将会生成我们想要让 Incredibuild 分发的子进程（DummySubProcess.exe 和 link.exe），因此该进程标记的 AllowIntercept 属性将设为 True。

• 由于我们想要将 DummySubProcess.exe 的执行分发至远端机器，因此 DummySubProcess 的 AllowRemote将设为 True。

• 由于我们想要让 link.exe 在本地运行，因此“link.exe”的AllowRemote 将设为 False。由于 AllowIntercept 和 AllowRemote 的默认设置均为False，因此在 profile.xml 文件中忽略此行应有同样效果。

使用情况

您的 profile.xml 文件就绪后，即可配合以下工具通过 Automatic Interception Interface 分发构建进程：

• 自定义工具，用于加快一组预定义标准 Make 的构建时间，以及其他构建工具和支持的编译器，此外，用于在 Visual Studio 中拦截渲染工具（使用自定义步骤）（请参阅 Accelerating Custom Build Steps, Custom Build Events and Custom Build Tools in Visual Studio）。

• IBConsole.exe

示例和资源

以下是 Profile XML 文件格式的详细规范。除下方信息外，还请注意以下有用资源：

• 在 Incredibuild 安装文件夹中，您会找到一个标准 .xsd 架构文件（“Schema for Profile file.xsd”），您可以使用该文件验证现有的 Profile XML 文件。MS Visual Studio 及许多其他 XML 相关编辑器均可读取 .xsd 文件。

• 若干使用 Automatic Interception Interface 的预构建项目工作示例（包括 Profile XML 文件）通过 Incredibuild 进行安装。

Profile XML 文件规范

Profile XML 文件架构如下所示：

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<Profile FormatVersion="1">
    <Tools>
        <Tool ATTRIBUTES />
        ...
    </Tools>
</Profile>

• Tool 元素定义了 Incredibuild 应在分布式进程中处理的一个或多个工具。

• Multiple Tool 元素可能包含于 Tool 元素中。

如有以下情况，应添加 Tool 元素：

Tool 元素属性

1. Filename：工具的名称（文件名扩展可选）。允许通配符（例如“TOOL*.exe”）支持覆盖多个工具名称的单个 Tool 定义。

2. AllowRemote：此属性为“True”的 Tool 在执行时将分发至远端机器。

   <Tool Filename="cl" AllowRemoteIf="-c,/c" />

3. AllowRemoteIf：条件值用于根据命令行内容来确定，一项任务是应该分发完成还是应该在本地 Agent 上执行。如果在任务命令行中找到了此属性的指定值，那么任务将标记为“允许分发”。以下是使用方法示例：上述内容用于 Profile 文件时，仅命令行中包含“-c”或“/c”字符串的 cl.exe 文件（不带引号）会被分发至远端机器。

4. AllowIntercept：此属性为“True”的 Tool 将被 Automatic Interception Interface 监控。任何负责直接或间接执行远端执行 Tool 的工具（即 AllowRemote 属性设为“True”的远端执行 Tool）应将 AllowIntercept 属性设为“True”。

5. DeriveCaptionFrom：此属性控制了在构建监视器 Progress View 任务构建栏中出现的标题栏。该属性接受两种预定义值：

   • firstparam– 回显任务命令行的第一个参数。

   • lastparam – 回显任务命令行的最后一个参数。

6. SingleInstancePerAgent：即使运行在配备多处理器或多核硬件的 Agent 上，该属性配置为“True”的工具都不会在单个 Agent 上并行运行。此属性并不会阻止工具同时在不同 Agent 上运行。

7. AllowRestartOnLocal：对于此属性设为“True”的 Tool，启动 Agent 可以应用性能优化功能，该功能由 Agent 设置选项中的 "Restart remote processes on local machine when possible" 进行激活。Important： 对于增量写入了输出文件的工具，此属性不应设为“True”，因为如果工具的本地实例终止，可能会导致留下“半成品”输出文件。

8. SuccessExitCodes：此属性指定了可成功退出指定工具的退出代码。该属性的值为以逗号分隔的数值列表。允许存在值的范围（例如：“2..19”）。如忽略，工具的默认成功退出代码将为 0。

9. WarningExitCodes：此属性指定了对特定工具起警告作用的退出代码。返回此退出代码的任务将以黄色条形显示于 Build Monitor Progress 页面，并在 Summary 页面计为警告。该属性的值为以逗号分隔的数值列表。允许存在值的范围（例如：“2..19”）。

10. IdentifyTaskOutput：此属性可用于以下情况，即无论何时，某工具在执行时使用 Submission Interface 或 Automatic Interception Interface 进行分发，但在 Build Monitor Progress display 中双击进度条不起作用的情况。指定使用“True”属性时，Incredibuild 会试图将文本标识符添加至工具输出，以便在构建的输出文本中对其进行定位。标识符会从最终构建输出文本中移除。下面是一个使用例子。

    <Tool Filename="cl" AllowRemote="true" DeriveCaptionFrom="lastparam" IdentifyTaskOutput="true"/>

11. AutoRecover：如果在工具输出中发现以逗号分隔的字符串列表，则 Incredibuild 会将任务重新分配至另一 Agent 并放弃先前的输出。

12. TimeLimit：在执行以秒为单位的时间限制之后，远端任务将自动取消并重新分配至其他 Agent。

13. VCCompiler：设为“True”时（默认“False”），对此工具及其子进程的处理方式将与 Visual Studio C/C++ 编译器处理 PDB 和 PCH 的方式相同。仅在试图通过 IB Interface 分发对 Visual Studio C/C++ 编译器的执行时，才会使用此属性。VCCompiler 仅适用于 Visual Studio C/C++ Build System 扩展包。

14. AutoReserveMemory：该属性制定该工具使用文件的内存映射，通常由编译器用于实现对预编译头文件的支持。对于即将用于内存映射的文件，该属性应指定其文件扩展名（通常为预编译标头文件扩展名）。例如，要指定名为“gcc”的工具使用内存映射创建带有“.gch”扩展名的预编译头文件，XML 配置文件中的 gcc 定义可能为：

    <Tool Filename="gcc" AllowRemote="true" DeriveCaptionFrom="lastparam" AutoReserveMemory="*.gch"/>

    要指定多个文件扩展名，请输入以逗号分隔的值，例如："*.gch,*.pch"。<

15. AdditionalOutputMask：此属性规定工具需根据所提供的掩码将附加文件返回至启动机器。例如，要规定某个名为“gcc”的工具须将所有生成的 .log 文件返回至启动机器，则“gcc”在 Profile XML 文件中的定义应如下：

    <Tool Filename="gcc" AllowRemote="true" DeriveCaptionFrom="lastparam" AdditionalOutputMask="*.log"/>

重要提示

• 您可以创建默认返回启动机器的文件列表。在 HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Xoreax\Incredibuild\Builder 下创建名为 AdditionalOutputMasks 的注册表字符串值。为指定多个文件扩展名，请输入以逗号分隔的值，例如：“*.log,*.dat”。

• 主构建工具可执行文件应在 Profile XML 文件中进行定义，且 AllowIntercept 属性应设为“True”（请参阅 sample projects 中的 XML Profile 文件）。请注意，如果您正在以“/COMMAND=”语法运行 IBConsole.exe，则在 /COMMAND 参数中指定的工具 (或 cmd.exe，如果工具是 .bat 文件）将被隐式赋予 AllowIntercept 行为。

• 如果远端执行的进程是由主构建工具的子进程生成的，那么应将始于主构建工具的整个进程层次结构的 AllowIntercept 属性设为“True”。例如，如果主构建工具为“make.exe”，它执行了“runner.exe”，而“runner.exe”又 执行了“MyTool.exe”，且后者正是我们想要分发其执行的进程，那么“make.exe”和“runner.exe”的 AllowIntercept 属性均将设为“True”。

• 由 AllowRemote 属性设为“True”的工具所生成的可执行文件，其 AllowRemote 属性不应设为“True”。远端子进程将由 Incredibuild 自动处理。

• Incredibuild 仅可在 Visual Studio 2010 及更新版本中使用 Profile xml 文件进行自定义步骤、任务执行以及特殊构建工具的分发。更多信息，请参阅 BuildConsole 部分 的最后部分。

Automatic Interception Interface XML 架构

此部分介绍了用于构建 Automatic Interception Interface 配置文件的 XML 架构。可在 Using XML Interface 部分中找到有关 XML 架构的详细说明。

XML 文件使用 Interception Interface 定义了集成行为，也定义了那些可分发、可本地运行的进程。XML 文件介绍了一组规则，这些规则将应用于 Incredibuild 正在执行的任务。该规则适用于所有共享相同名称的任务。例如，XML 将任务“Render”设为“AllowRemote”，那么一个作业可能会包括若干种 Render 实例，每个实例均会根据规则在远端处理。IBConsole 将此 XML 文件作为配置文件使用，定义了处理进程的方式。

<Tool Filename="SubProcess" AllowRemote="true" DeriveCaptionFrom="lastparam" IdentifyTaskOutput="true"/>

示例 1

要指定文件名为 LogMe 的文件，需将所有生成的 .log 和 .dat 文件返回至启动机器，则在 Profile XML 文件中将 LogMe 按如下方式定义：

<Tool Filename="LogMe" AllowRemote="true" DeriveCaptionFrom="lastparam" AdditionalOutputMask="*.log"/>,*.dat

示例 2

假定 LogMe 将返回所有类型的文件，但您仅关注其返回的 .log 文件。那么在这种情况下，Profile XML 文件中将对 LogMe 按如下方式定义：

<Tool Filename="LogMe" AllowRemote="true" DeriveCaptionFrom="lastparam" OutputFileMasks="*.log"/>

Tool 指应用了规则的进程名称。