This section of the step properties dialog 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 Pro 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:
| Comparison | Behavior |
| is undefined | Builds the step if the macro (i.e., %MYMACRO%) is not defined |
| is defined | Builds the step if the macro is defined |
| 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 and whether rules are nested.
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 brackets: [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). See the ContinuousIntegration.bld, Advanced.bld (Continuous Build section), and Files.bld (Repeat for File Contents section) samples for some examples.
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.