These options from the application options dialog configure global file log settings for builds:

 

Enable file logging: When checked, build output is written to the specified log file in addition to the Output pane.  Use the Browse button to choose a file, View to view the current log file in viewer (configured in the user options), Launch to open in its associated application, or Delete to delete the log file if it exists.

 

Log Filename: The name of the log file to write build output to if file logging is enabled (this value is available in the system macro LOGFILE if logging is enabled).  This is a global setting that affects all builds, unless the LOGFILE macro is overridden by a project.  Project-specific log files can also be used for every project automatically by entering %PROJDIR%\%PROJROOT%.<ext> in this field.  These system macros will be expanded when a project is built and the path and root name of the project file will be used for the log file.

 

The log filename can also be overridden for a given project in the Project Properties dialog or by passing in a temporary LOGFILE on the command-line.  This can be useful for creating project-specific log files or to dynamically modify the target filename (for instance, to temporarily disable file logging).  See the Logging.bld sample for more details.

 

Format: Determines the format that will be used to generate the log file.  The available options are Text and XML. Text log files are similar to the output displayed in the Output pane (including a timestamp for each step), and additional logging options are available for this format.

 

XML log files are written in a hierarchical XML format, with elements for each build and step.  The log file is appended to as steps are built, so until the build completes, the closing step, build, and log tags (elements) will not yet exist.  The Transform XML Log action can be used to add the closing tags (making the log a valid XML document that can be sent within a build), to filter the output, and to convert XML logs into HTML documents.  The Logging.bld sample demonstrates several techniques that are useful when using the XML log format (including deleting an XML log file before a build and disabling/enabling file logging during a build via code in script events).  For easier browsing of the file in Internet Explorer, XML log filenames can be given a .xml extension.

 

Note: To change the log file format to XML before file logging starts, use this VBScript code in the vbld_BuildStarting script event:

 

Application.Options.LogFormat = "XML"

 

Log all failure step output: If checked, even if a message is logged from a failure step with a higher level than the above Log level setting, the message will still be written to the log.  If unchecked, such messages logged from failure steps will not be written to the log.

 

Delete log file at the start of each build: If checked, the log file will be deleted at the beginning of each build.  Otherwise, the log file is appended to with each build.  When using XML logging and master/child projects that use the same log file, this option should not be checked, because it would cause the log file to be deleted at the beginning of the master and each child project.

 

Log default property of each step: If checked, each step's default property will be logged when it is built.  This can be useful for debugging purposes.

 

Log build rule when a step is skipped or repeated: If checked, when a step's repeating build rule is processed or when a step with a build rule is skipped, the details of the build rule will be logged.

 

 

Notes: