Caution

This software is not verified, will have breaking changes and might have bugs.

Ror

Ror is a PFE task runner.

See Examples

CLI Usage

ror [flags] [task] [task args]

Flags

• --export-taskfile: Export ror.kdl to Taskfile.yml (for compatibility with Task).
• -s, --silent: Silent mode (no output).
• -v: Verbose output.
• -vvv: Very verbose output.

Commands

Built-in commands are invoked with a leading +, so plain names stay free for tasks.

• +init: Create a new ror.kdl template.
• +validate <file>: Check that a file is valid ror.kdl.
• +version: Print version.
• +help: Print help message.

Format Description

Ror uses KDL v2 for its configuration file ror.kdl. The file defines a set of tasks that can be executed.

Structure

Tasks

Tasks are defined using the task node followed by the task name.

task my-task {
    ...
}

You generally don't need quotes for task names unless they contain special characters (like spaces, brackets ()[]{} or symbols like =, ,, ;, \, /, <, >) or look like a number, boolean, or null.

Common safe characters include letters, numbers, -, and _.

Properties

Inside a task, you can define the following properties:

• description: A string describing what the task does.
• cmd: The command to run.
• depends: A block listing dependencies using on.
• env: Environment variables passed to the task command.
• vars: Task-level variables that override global vars by name.

Dependencies

Dependencies define other tasks that must run successfully before the current task. They are specified within a depends block using on.

task install {
  depends {
    on "build"
  }
  
  cmd "cp ./app /usr/local/bin/app"
}

Command Execution

The cmd node specifies the shell command to execute. It supports variable substitution.

Task environment

A plain env value is fixed, even if the same variable exists outside ror:

task serve {
  env PORT="8080"
  cmd "./server"
}

Use expose to prefer a non-empty external value. If the variable is unset or empty, the configured value is used:

task serve {
  env PORT="8080" {
    expose
  }
  cmd "./server"
}

Use execute to run the value as a shell command and use its stdout as the environment value (surrounding whitespace is trimmed). With both directives, a non-empty external value skips the command. Without expose, the command always runs. An empty command is invalid even if an external value exists. A failed command fails the task.

task build {
  env REVISION="git rev-parse --short HEAD" {
    expose
    execute
  }
  cmd "echo $REVISION"
}

KDL v2 requires child directives on separate lines (or separated with semicolons).

Env values may reference global and task vars with %%name%%. Expansion happens before expose/execute handling, so it works for plain, exposed and executed values alike:

vars { version "1.2.3" }

task build {
  env APP_VERSION="%%version%%"
  env REVISION="git rev-parse --short HEAD" {
    expose
    execute
  }
  cmd "./build.sh"
}

Vars

A vars block defines named string values. It can be placed at the top level (global) or inside a task (task-level). Values are substituted using the same %%variable_name%% syntax as where variables.

vars {
  hostname "hello"
  domain "example.com"
}

task foo {
  # Task-level vars override globals by name.
  vars {
    hostname "world"
  }

  cmd "ssh %%hostname%%.%%domain%%"
}

Each entry is a name followed by a single string value. Duplicate names in the same block are an error.

Precedence, from lowest to highest:

1. global vars
2. task vars
3. where inside cmd

A task can freely use any global it does not override. A global that is overridden is shadowed: there is no way to read the original value from within that task. Vars are static strings; use where for dynamic ({ execute }) values.

Vars are expanded in cmd, description and env values using the same %%variable_name%% syntax. No extra directive is needed. An unknown name is left as-is so a command can still see it literally.

Variables

Variables are defined using where nodes attached to the cmd node or nested within other where nodes. They are substituted using %%variable_name%%.

Variable name can only contain symbols A-Z, a-z, 0-9, _ and -.

Static Variables

where my-var="value"

Dynamic Variables

Variables can be the result of a shell command execution by adding an { execute } block.

where current-date="date +%Y-%m-%d" { execute }

We can go even deeper:

where current-date="date %%format%%" { 
  where format="+%Y-%m-%d"

  execute
}

Examples

Basic Usage

A simple task to run a command.

task run {
  description "Run the project"

  cmd "go run ./main.go"
}

Complex Build (Variables)

A build task that injects git commit hash and compilation time into the binary.

task build {
  description "Build the application"

  cmd "go build -o out/app -ldflags='-X main.commit=%%commit%% -X main.date=%%date%%' ./cmd/app" {
    where commit="git describe --tags --always --dirty" { execute }
    where date="date +%Y-%m-%dT%H:%M:%SZ" { execute }
  }
}

Dependencies

A deploy task that ensures the application is tested and built first.

task deploy {
  description "Deploy the application"
  depends {
    on "test"
    on "build"
  }
  
  cmd "./scripts/deploy.sh"
}