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. 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'.