Script Events

Script events allow custom script code to hook into build events at various points in the build process. This can be useful for performing logic to enable/disable file logging for portions of a build, as an alternative way to implement build rules, to check the step's output and fail the step if the contents indicate an error condition, etc.

Event functions can be created using the Events toolbar button or the Edit menu in the Script Editor. The available events are described below.

Project Events

Project events are called once for each build. The code for project events should entered as Project script in the Script Editor (it can also be entered as Global script, but each event function can be defined in only one location).

Event Function

Description

vbld_BuildStarting()

Called before the build starts (before any logging).

vbld_BuildDone(status)

Called after a build completes (after all logging completed); the completion status of the build is passed.

vbld_ProjectLoaded(filename)

Called when a project is loaded; the filename of the project is passed. The _BUILD_PROFILE_ temporary macro can be created or updated in this method to define the build profile.

Note: Only script code for the default script language will be executed for project events.

Step Events

Step-Specific

Step-specific events are invoked once for each step that is built. The code for these step events must be entered on the Step tab of the Script Editor, which must be opened from the step properties dialog to edit these events. The global Step item is available for accessing the properties of the current step.

Event Function

Description

vbld_StepStarting()

Called after build rules have been evaluated but before the step starts; if False is returned, the step is skipped.

vbld_StepStarted()

Called immediately before the custom action for the step is built.

vbld_StepDone()

Called after the custom action for the step has finished building; the step status is available in the Step.BuildStatus property and can also be updated to change the success/failure status of the step. If the step is marked to continue on failure, throwing or raising an error from this event will not ignore the failure (providing a way to abort the build even when the step is marked to continue on failure). The step's output is available in the LASTSTEP_OUTPUT system macro (accessed from script code via Application.ExpandMacrosAndScript("%LASTSTEP_OUTPUT%")).

Project-Level

Project-level step events are also invoked once for each step that is built, but the code is entered on the Project tab of the Script Editor. The global Step item is available for accessing the properties of the current step.

Event Function

Description

vbld_StepStartingProject()

Called after build rules have been evaluated but before the step starts and before the step-specific vbld_StepStarting event.

vbld_StepStartedProject()

Called immediately before the custom action for the step is executed and before the step-specific vbld_StepStarted event.

vbld_StepDoneProject()

Called after the custom action for the step has finished building and after the step-specific vbld_StepDone event; the step status is available in the Step.BuildStatus property and can also be updated to change the success/failure status of the step. If the step is marked to continue on failure, throwing or raising an error from this event will not ignore the failure (providing a way to abort the build even when the step is marked to continue on failure).

Notes:

•	Script code for step script events must use the default script language.

•	Script event code cannot reference macros directly -- use the script code Application.ExpandMacrosAndScript("%MYMACRO%") instead of "%MYMACRO%".

•	The StepStarted and StepDone events do not fire if the step is skipped.