BuildForge Help

.run and .runwait

.run [-c "<condition>"] "<ProjectName>"
.runwait [-c "<condition>"] "<ProjectName>"

The .run and .runwait commands allow you to launch a chained project from a step command, providing a more flexible means of launching chains, including the evaluation of environment variables to determine whether a chain is launched.

The commands differ in how they behave after they launch a project:

Conditional Launches

The optional -c parameter can be used to make the launch depend on a condition. You can use environment variables in the condition. The condition can be of several forms:
String comparison
You can use equal (=) or not equal (!=) operators to evaluate strings. The chain is launched if the comparison evaluates true.
Numeric comparison
You can use <, >, <>, ><, or = operators to compare two numeric values.
Command success
You can use a command enclosed in backticks as the value of the -c parameter. The system runs the command; if it succeeds, the chain is launched.

Examples

.run "BuildWindowsDriver"

The system launches the BuildWindowsDriver project. The launching project continues with the next step immediately.

.runwait "BuildWindowsDriver"

The system launches the BuildWindowsDriver project. The system pauses the launching project at the .runwait step. When the BuildWindowsDriver project completes and passes, the .runwait step's status is set to pass.

.run -c "$HOMEDRIVE=C:" "Simple Echo"

The system runs the project Simple Echo if and only if the HOMEDRIVE variable has the value C:.

This command produces log output like the following (in the EXEC section of the step log):
  • When HOMEDRIVE is C:
    .run Condition: 'C:' = 'C:' satisfied.
    
    Queueing Project "Simple Echo" on server [WinBox].
    Queued Build 'BUILD_202' of project 'Simple Echo'.
  • When HOMEDRIVE is not C:
    .run -c "$HOMEDRIVE=C:" "Simple Echo"     
    
    .run Condition: 'D:' = 'C:' unsatisfied, no project queued.
The system can numerically compare strings if they contain numbers. For example, it handles the following cases as shown:
.runwait -c "a12b<c42d" "Simple Echo"
.run Condition: '12' < '42' satisfied. 
Queueing Project "Simple Echo" on server [WinBox]. 
Waiting for .run build (4411) to complete. 
.run build is now running. 
.run build has finished. 
Build 'BUILD_203' of project 'Simple Echo' completed. 
.runwait -c "f43g<>h43i" "Simple Echo"
.run Condition: '43' <> '43' unsatisfied, no project queued. 
The following examples show how to use commands as conditions. Note that the command must be enclosed in both quotes and backticks:
.run -c "`exit 1`" "Simple Echo"
Env .run encountered an error during variable expansion, parameter [`exit1`] expanded to []. 
Expansion returned non-zero exit, project will not be queued. 
.run -c "`exit 0`" "Simple Echo"
Expansion returned zero exit, project will be queued. 
Queueing Project "Simple Echo" on server [WinBox]. 
Queued Build 'BUILD_204' of project 'Simple Echo'.
When you use .runwait and a build fails, the log looks like the following:
.runwait "Fail Build"
Queueing Project "Fail Build" on server [WinBox]. 
Waiting for .run build (4413) to complete. 
.run build is now running. 
.run build has finished. 
Build 'BUILD_3' of project 'Fail Build' Failed, setting step status to fail.
Related concepts
Launching Projects from Steps