XML Interface - XML Syntax Notes

This section contains notes on XML Validity as well as additional information on important elements in the XML syntax.

XML Validity

Additional Notes on XML Elements

1. Project: the entire set of tasks that will be run.
2. Task: a single task definition. Please note that one defined task in the XML can be translated to multiple tasks if a file search or response file (explained below) is applied.
3. TaskGroup: a group of tasks.
4. SourceFile: this attribute, associated with the Task element, defines the input source for the task.
   1. Use Wildcards to define a file search (e.g.: use one task to process all files in a given directory). Please note that recursive file searches are not yet supported.
   2. Use response files to load a predefined list of files (scroll down to the 'Response File Loading' section for more details).
5. InputFiles: this attribute, associated with the Task element, defines additional input files for the task. Use this attribute to define files which the task is dependent on and are not defined in the XML (e.g. - header files in code builds).
   1. Defining this attribute is not required but is recommended for incremental builds.
   2. You may define multiple files using a comma or semicolon as a delimiter.
   3. Response file loading is also supported.
   4. E.g.:
      <Task SourceFile="main.c" InputFiles="@ResponseFile1.txt; main.h; @ResponseFile2.txt " />
6. OutputFiles: this attribute, associated with the Task element, defines the output files for the task.
   1. Defining this attribute is not required but is recommended for incremental builds.
   2. You may define multiple files using a comma or semicolon as a delimiter.
   3. Response file loading is also supported.
7. DependsOn: this attribute, associated with Task and TaskGroup defines the dependency relations. Please note that multiple dependencies can be defined. You may define multiple dependencies using a comma or semicolon as a delimiter (e.g.: DependsOn="task1;task2"). For more information on dependencies, see the section on dependency definitions.
8. Tool: the Tool element defines the tool or tools that will be used to execute the tasks. The tool executables or related DLLs do not have to reside on the remote machines. You can define the same application as a tool more then once if needed (see demo XML).
   There are two limitations on the type of applications that can be used. These limitations may change in the future. The current limitations are:
   1. The application can't change registry settings during its operation. Registry Read-Only access is permitted.
   2. The application can't prompt for any required UI interactions during its operation.
9. Params: this attribute, associated with the Tool and Task elements, defines the command line inputs for the tasks. Please note that the parameters passed to the task can be a mix of new parameters and parameters inherited from the tool (see the inherited:params macro).
10. WorkingDir: the WorkingDir attribute, appearing in the Project, TaskGroup and Task elements, defines the working directory used for tasks. The deepest occurrence in the XML definition locally overrides any parent definition. E.g.: in the demo XML, the file name passed to the application does not contain the full path, but since the Project element defined a WorkingDir, the application can pick up the file.
11. OutputPrefix / GroupPrefix: these attributes, associated with Tool element, define the text that will appear in the build monitor and logs.
12. SkipIfProjectFailed: this attribute, associated with the Tool and Task elements defines the behavior in case a failure occurs (e.g.: skip the link task if a compile task failed).
13. SuccessExitCodes: this attribute, associated with the Tool element allows changing the default 0 success exit code returned from the tool. Ranges are allowed (e.g.: '2..19').
14. 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').
15. OutputFileMasks: this attribute, associated with the Tool element allows defining a set of file types that should be returned to the builder. E.g.: an application uses intermediate files that are not required by the builder. To prevent unnecessary file syncs over the network, a file mask for the desired files only can be defined. Multiple masks are allowed. E.g.: '*.o, *.d'.
16. 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.
17. 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 name="compiler" path="c:\cygwin\bin\gcc.exe" AllowRemote="true" AutoReserveMemory="*.gch"/>
    
    To specify more than one file extension, enter comma-separated values, e.g.: "*.gch,*.pch".

18. 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.
19. 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.