Tracing Execution in Oil (xtrace)

Oil extends shell's set -x / xtrace mechanism to give you more visibility into your program's execution. It shows high-level program structure ("functions", eval) as well as runtime events (starting and stopping external processes).

Table of Contents
Background
What's Wrong With set -x?
Oil Enhancements
Option Names
Variables for the Trace Line
Other Useful Variables
Parsing xtrace_rich Output

Background

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

$ sh -x -c 'echo 1; echo 2'
+ echo 1
1
+ echo 2
2

What's Wrong With set -x?

Oil Enhancements

Oil solves these problems. Here's an example of tracing a builtin, a pipeline, then another builtin:

$ osh -O oil:basic -x -c 'set +e; ls | grep OOPS | wc -l; echo end'
. builtin set '+e'
> pipeline
  | part 103
    . 103 exec ls
  | part 104
    . 104 exec grep OOPS
  | command 105: wc -l
  ; process 103: status 0
  ; process 104: status 1
  ; process 105: status 0
< pipeline
. builtin echo end

Option Names

This functionality is enabled by the xtrace_rich option, but you should generally use the oil:basic option group. This group turns on xtrace_rich and turns off xtrace_details, which is equivalent to:

$ shopt --set xtrace_rich
$ shopt --unset xtrace_details

Variables for the Trace Line

In Oil, the default trace line prefix is:

$ PS4='${SHX_indent}${SHX_punct}${SHX_pid_str} '

SHX_punct is one of the following:

TODO: Cross-shell tracing

Other Useful Variables

These variables can enhance the traces.

Parsing xtrace_rich Output

TODO


Generated on Tue Jan 19 11:43:13 PST 2021