Tasks | Shell

Shell — execute system commands

Xake provides three builders for running shell commands, each with different defaults.

Builders

sh — recommended

Fails on non-zero exit code by default. Returns unit for simple do! usage.

do! sh "dotnet build -c Release" {}

do! sh "dotnet" {
    args ["build"; "src/core"; "-c"; "Release"]
    workdir "src"
}

shell

Does not fail on error by default. Returns the exit code as int.

let! exitCode = shell {
    cmd "dotnet"
    args ["build"]
}
if exitCode <> 0 then
    do! trace Warning "Build returned %d" exitCode

shellCmd

Like shell but accepts a command line string that gets split into command and arguments:

let! exitCode = shellCmd "dotnet build" {
    arg "-c"
    arg "Release"
}

Operations

Operation	Description
cmd "command"	Set the command to execute
args ["a"; "b"]	Append a list of arguments
arg "value"	Append a single argument
workdir "path"	Set the working directory
failonerror	Fail the build on non-zero exit code
useclr	Run under mono on non-Windows platforms
env ("NAME", "value")	Set an environment variable
logprefix "prefix"	Set a prefix for log messages
stdout handler	Attach an additional stdout line handler
stderr handler	Attach an additional stderr line handler

Capturing output

result — exit code

Use result to explicitly get the exit code from sh or shellCmd:

let! exitCode = sh "dotnet --version" { result }

output — stdout lines

Capture stdout as a string list:

let! lines = sh "dotnet --list-sdks" { output }
for line in lines do
    do! trace Info "SDK: %s" line

result + output

Capture both exit code and stdout:

let! exitCode, lines = sh "git status --porcelain" { result; output }
// or equivalently:
let! exitCode, lines = sh "git status --porcelain" { resultAndOutput }

Defining reusable commands

let dotnet arglist = sh "dotnet" { args arglist; failonerror }

// Usage:
do! dotnet ["build"; "src/core"; "-c"; "Release"]
do! dotnet ["test"; "src/tests"]

Platform behavior

On Windows, commands that are not .exe files are automatically wrapped with cmd.exe /c. The useclr operation prefixes the command with mono on non-Windows platforms.

Error handling

sh fails on non-zero exit code by default. shell and shellCmd do not — use failonerror to opt in, or check the exit code manually:

// Explicit error check
do! shell {cmd "make"} |> FailWhen Not0 "make failed"
// or
do! shell {cmd "make"} |> CheckErrorLevel