.run and .runwait

Note: On Java engines in Build Forge 8.0, conditions [-c<condition>] for .run and .runwait are not supported. To make the launch dependent on a condition, use a conditional step instead.
.run [-c "<condition>"] "<ProjectName>" 
.runwait [-c "<condition>"] "<ProjectName>" 

You can use the .run and .runwait commands to launch a chained project from a step command. If the project has multiple snapshots, the system runs the default snapshot.

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

Conditional launches

You can use the optional -c parameter 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 such as 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 similar to 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.

Feedback