Why Sponsor Oils? | source | all docs for version 0.23.0 | all versions | oilshell.org
xtrace
)Oils 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).
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
set -x
?argv
array for commands. It doesn't tell you if the
command is a builtin, shell function, or external binary, which is important
for program comprehension (and performance).echo x | read
mutate a variable?)eval
or source
.Oils solves these problems. Here's an example of tracing a builtin, a pipeline, then another builtin:
$ osh -O ysh:upgrade -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
builtin
prefix.command
prefix.exec()
calls are shown with the exec
prefix.>
and <
characters. This includes the entire pipeline, as well as proc
calls (not shown).|
and ;
characters. These are
asynchronous in general.argv
arrays may be quoted with QSN. This
shows special characters unambiguously, and ensures that each trace entry is
exactly one physical line.This functionality is enabled by the
xtrace_rich option, but you should
generally use the ysh:upgrade
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
In YSH, the default trace line prefix is:
$ PS4='${SHX_indent}${SHX_punct}${SHX_pid_str} '
SHX_indent
is affected by synchronous constructs like proc
and eval
, as
well as new processes.SHX_pid_str
is only set for child shell processes (to avoid redundancy).
It has a space at the beginning like ' 123'
.SHX_punct
is one of the following:
+
for legacy shell tracing (xtrace_details).
for builtin
and exec
>
and <
for internal, stack-based, synchronous constructs
proc
, eval
, and source
, an entire pipeline, and the wait
builtin|
and ;
for process start and wait
TODO: Cross-shell tracing
SHX_descriptor
is alias for BASH_XTRACEFD
?$SHX_indent
and $SHX_pid_str
These variables can enhance the traces.
@BASH_SOURCE
, @BASH_LINENO
, @FUNCNAME
, $LINENO
@SOURCE_NAMES
as alias? LINE_NUMS
?$SECONDS
for timingxtrace_rich
OutputTODO