source | all docs for version 0.8.6 | all versions | oilshell.org

Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.

Tracing Execution in Oil (xtrace)

Oil extends shell's set -x to give you more visibility into your program's execution.

Background

In shell, the $PS4 variable controls the prefix of each trace line. The default value is '+ ', which results in traces like:

+ echo 1
+ echo 2

Oil Enhancements

In Oil, the default is

PS4='${X_indent}${X_punct}${X_pid} '

• X_indent is affected by proc invocations, source, and eval
• X_punct is:
  • + for a command (TODO: make this richer?)
  • > and < for indentation changes -- synchronous
  • | and . for process start and stop -- asynchronous, e.g. with pipelines and &.

To see hierarchical traces, turn on xtrace_rich:

shopt -s xtrace_rich   # part of the oil:basic option group

Useful Variables For Use in $PS4

• @BASH_SOURCE, @FUNCNAME, $LINENO
  • TODO: Add @SOURCE_NAME as alias?
• TODO: $SECONDS for timing

Parsing xtrace_rich Output

• It's concurrent, but lines are atomically written
• TODO: Specify a regular language?
• Coalesce by PID?