Step Properties Dialog General Tab
The General tab of the Step Properties dialog is used to configure common step properties.
Name: Used to identify the step when building (required).
Description: A description of the step (optional). It will also be displayed in a tool tip in the main window when the mouse is over the Step Name column.
Conditional Build Rule
This section of the step properties dialog General tab is used to define a build rule to determine if a step and its children will be built or skipped during a build. This is a powerful capability that allows selective execution of project steps based on the value of macros, script, or environment variables, implementing of loop constructs (performing a step or set of steps a certain number of times, until some condition is reached, once for each line in a file, etc.), and more. If Always build this step and child steps when checked is selected, no build rule will be evaluated and the step will be built if checked (this is the default).
Select Build only when macro or expression to define a build rule for the step. Enter the expression to evaluate, the comparison to use, and the value to compare with. When building, Visual Build evaluates the rule, and builds the step and its children if the rule evaluates to a true condition and skips the step if it doesn't. The following rule comparisons are supported:
|is undefined||Builds the step if the macro (i.e., %MYMACRO%) does not exist|
|is defined||Builds the step if the macro is exists|
|contains||Build if the expression contains the string in the following field (macros and/or script can be used in either field)|
|is equal to||Build if the expression is equal to the string in the following field|
|is not equal to||Build if the expression is not equal to the string in the following field|
|does not contain||Build if the expression does not contain the string in the following field|
|is true||Build if the expression is true (a non-zero number or the string True) -- useful when evaluating script expressions|
|is false||Build if the expression is false (zero or the string False)|
Settings in the Application options determine whether comparisons are case sensitive.
Note: When entering a macro in the macro or expression field, the macro name must be surrounded by percent signs (%MYMACRO%) so that the macro's value is used in the comparison. Otherwise, a literal comparison of the string that was entered and the comparison value will be performed.
For more complex rules, a script expression can be used determine whether the step should be built. Any valid script expression can be used, and the expression can call functions defined in the Script Editor. Script expressions are marked by bracket characters: [script code here].
A while loop can be implemented by checking Repeat step while condition is true. If the rule evaluates true, the step and all child steps will be built; the rule will then be re-evaluated and the steps repeated until the rule evaluates false (a macro can be modified in a child step to increment a counter or set the condition to false as appropriate, or a script function could be called which determines whether to continue the loop). A repeating set of steps can also exited with the Exit action or by the step failure exit build/subroutine option.
Note: A loop can also be implemented with the Loop action.
A conditional build rule normally applies to the current step and all child steps (steps below and indented from the step), so a build rule can easily be applied to a block of steps. Normally rules are nested (if a child step also defines a build rule, the parent and child step's rules must evaluate true). Note: this behavior can be overridden by disabling the option for nesting of rules in Application options.
Note: Build rules are not evaluated when performing a Rebuild Selected or when clicking the Test button on the step properties dialog; see the Methods of Building help topic for other ways to test iterating steps or steps with build rules.