Automatic Interception Interface - Profile XML File

The profile XML file is used to define the how the Automatic Interception Interface should handle the various processes involved in a distributed job.

Contents of this page:

An Example

In this scenario we would probably only want to distribute execution of compilation steps (cl.exe). Distributing execution of the single link.exe task to a remote machine would involve sending a relatively large amount of data (.obj files, etc.) across the network, so it would probably be best to let this task always run on the initiating machine.

The following profile.xml file can be used to run the Automatic Interception Interface on the above scenario:

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

Explanation

• "make.exe" is the process managing the build process. Because this process spawns processes whose execution we want IncrediBuild to intercept (cl.exe and link.exe), this process is marked with the AllowIntercept attribute set to "True".
• Since we want to distribute execution of "cl.exe" to remote machines, "cl" is specified with AllowRemote set to "True".
• Since we want "link.exe" to run locally, it is specified with AllowRemote set to "False". Omitting this line from the profile.xml file would have the same effect since the default for both AllowIntercept and AllowRemote is "False".

Once our profile.xml file is ready, all that's left is to run xgConsole.exe to distribute the build process using the Automatic Interception Interface.

Samples and Resources

1. In the "XGE" subfolder under the IncrediBuild installation folder you will find a standard .xsd schema file ("Schema for Profile file.xsd") you can use to validate an existing Profile XML file. .xsd files can be read by MS Visual Studio and many XML-related editors.
2. Several pre-built working samples of projects (including Profile XML files) using the Automatic Interception Interface are installed with IncrediBuild. See this section for more details.

Profile XML File Specification

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

- The Tool element defines the tool or tools that IncrediBuild should handle during the distributed process.
- Multiple Tool elements may be included under the Tools element.
- A Tool element should be added for the following cases:

Tool Element Attributes

1. Filename: The name of the tool (filename extension is optional). Note that wildcards (e.g. "TOOL*.exe") are allowed to support a single Tool definition that covers multiple tool names.
2. AllowRemote: Execution of Tools with this attribute set to "True" will be distributed to remote machines.
3. AllowIntercept: Tools with this attribute set to "True" are monitored by the Automatic Interception Interface. Any tool responsible for direct or indirect execution of remotely executed Tools (Tools with AllowRemote set to "True") should have AllowIntercept set to "True".
4. DeriveCaptionFrom: This attribute controls the caption that will appear in the task's build bar in the build monitor Progress View. The attribute accepts 2 pre-defined values:
   • firstparam - will echo the first parameter from the task's command line.
   • lastparam - will echo the last parameter from the task's command line.
5. SingleInstancePerAgent: Tools with this attribute set to "True" will never run concurrently on a single Agent - even if the Agent has multi-processor or multi-core hardware. Note that this attribute does not prevent tools from running on different Agents at the same time.
6. AllowRestartOnLocal: For tools with this attribute set to "True", the initiating Agent will be allowed to apply the performance optimization activated by the "Restart remote processes on local machine when possible" Agent Settings option.
   Important: This attribute should not be set to True for tools that write incrementally to output files, since this might leave a "half-baked" output file if the local instance of the tool is terminated.
7. SuccessExitCodes: This attribute specifies the exit code(s) that will be considered as success exit codes for the specified tool. Value is a comma-separated list of numerical values. Ranges are also allowed (e.g.: '2..19'). If omitted, the default success exit code for the tool will be 0.
8. WarningExitCodes: This attribute specifies the exit code(s) that will be considered as warning exit codes for the specified tool. Tasks returning this exit code will be displayed as a yellow bar in the Build Monitor Progress page and will be counted as warnings in the Summary page. Value is a comma-separated list of numerical values. Ranges are also allowed (e.g.: '2..19').
9. IdentifyTaskOutput: This attribute should be used whenever double-clicking on a progress bar in the Build Monitor Progress display doesn't work for a certain tool whose execution is distributed using either the Submission Interface or the Automatic Interception Interface. When specified using the "True" attribute, IncrediBuild will attempt to add textual identifiers to the tool's output to help locate it in the build's output text. The identifiers will be removed from the final build output text. Here is a usage example:
10. AutoRecover: comma-separated list of strings which, when found in tool output, will cause IncrediBuild to re-assign the task to another Agent and discard the previous output.
11. TimeLimit: Time limit, in seconds, after which a remote task will automatically be canceled and re-assigned to a different Agent.

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

12. VCCompiler: When set to True (the default is False), this tool and its sub-processes will be handled in the same way as the Visual Studio C/C++ compiler in terms of PDB and PCH handling. Use this property only when attempting to distribute execution of the Visual Studio C/C++ compiler through the XGE Interfaces.
    The VCCompiler option is only available with the Visual Studio C/C++ Build System extension package.
13. AutoReserveMemory: This attribute specifies that the tool utilizes memory mapping of files, typically used by compilers for implementing support for precompiled headers. The attribute should specify the file extension(s) of the files to be used with memory mapping (typically the precompiled header file extension). For example, to specify that a tool called "gcc" uses memory mapping for creating precompiled headers with the ".gch" extension, gcc's definition in the profile XML might look like:

            <Tool Filename="gcc" AllowRemote="true" DeriveCaptionFrom="lastparam" AutoReserveMemory="*.gch"/>
    
    To specify more than one file extension, enter comma-separated values, e.g.: "*.gch,*.pch".

Important Notes

• The main build tool executable should be defined in the profile XML with the AllowIntercept attribute set to "True" (see XML profile files in the sample projects). Note that if you are running xgConsole.exe with the "/COMMAND=" syntax, the tool specified in the /COMMAND argument (or cmd.exe if the tool is a .bat file) will be implicitly given the AllowIntercept behavior.
• If the process to be executed remotely is spawned by a child process of the main build tool, the entire hierarchy of processes starting from the main build tool should be specified the AllowIntercept attribute set to "True". For example, if the main build tool is "make.exe", which executes "runner.exe", and "runner.exe" executes "MyTool.exe" which is the process whose execution we wish to distribute, then both "make.exe" and "runner.exe" must be specified with the AllowIntercept attribute set to "True".
• when running make tools in the Mingw or Cygwin environments, some common shell commands are automatically defined with "AllowIntercept" set to "True", to avoid their execution getting queued. See this page for more details.
• Executables spawned by a tool specified with AllowRemote set to "True" should not be specified as well with AllowRemote set to "True". Remote child processes will be handled automatically by the Xoreax Grid Engine.