sild - The Small Interactive Lua Debugger

sild is a standalone, TUI debugger for Lua scripts. It build statically and can run on most

sild [options] <script.lua> [script args...]

Installation

Copy sild to a location on your $PATH and make it executable:

cp sild ~/.local/bin/sild
chmod +x ~/.local/bin/sild

Quick start

sild myscript.lua

sild will pause on the first line of your script. From there:

Key	Action
`n / <enter>`	step to next line
`c`	continue freely (honours breakpoints)
`c <line>`	continue until line (one-shot)
`finish`	run until current function returns
`vars`	list locals in scope with types
`eval <expr>`	evaluate a Lua expression
`dump <tbl> [depth]`	dump table recursively (default depth 3)
`bt`	stack traceback
`calls`	show function call counts
`set <name> <expr>`	set a local variable by name
`watch <expr>`	watch expression, printed each step
`unwatch <expr>`	remove a watch
`watches`	list active watches
`bp <line>`	set breakpoint at line
`bp <line> if <expr>`	conditional breakpoint
`bpdel <line>`	remove breakpoint at line
`bplist`	list all breakpoints
`q`	quit sild
`? / h / help`	show this help

Command-line options

Flag	Description
`-b, --break <line>`	Set a breakpoint at `<line>` before execution starts.
`-c, --config <file>`	Load config from `<file>` instead of the default path.
`-l, --lines <n>`	Number of source lines shown in the code view.
`-C, --columns <n>`	Inner width of the code box in characters.
`-W, --width <n>`	Width of the history column in characters.
`-h, --help`	Print help and exit.
`-v, --version`	Print version and exit.

Arguments after the script name are passed to the script via the usual arg table.

sild -b 42 -b 87 myscript.lua arg1 arg2

Inline annotations

To write breakpoints and watches in your script, write them in the following annotation form.

--- BREAK

Break on the following line.

--- BREAK if n > 5

Break on the following line, only if the expression returns truthy. The expression is evaluated in the scope of your code at that point.

--- WATCH n
--- WATCH a[1]

Register a watch. The watch is added once, the first time the annotation is reached, and stays watched until removed with unwatch.

--- UNWATCH n

Remove a registered watch.

Configuration

The default config file is loaded from first:

$XDG_CONFIG_HOME/sild/sild.cfg

else

~/.config/sild/sild.cfg

You can use a custom config with:

sild --config /path/to/file.cfg

If a config file does not exist, sild runs with it's built-in defaults.

Format

# Lines starting with # are comments.
# key = value
code_lines = 20
col_keyword = 1;32

Keys and values are separated by =. Strings may be optionally quoted. Numbers must be plain integers. Unknown keys produce a warning on stderr.

Available settings

Layout

Key	Default	Description
`auto_size`	`true`	Should the UI set it's own size for the terminal.
`code_lines`	`15`	Number of source lines shown in the code box.
`code_inner`	`56`	Inner width of the code box in characters.
`hist_width`	`40`	Width of the history column in characters.

Colours

All colours are specified as ANSI SGR codes as the digits between \e[ and m.

Code range	Meaning
`0`	Reset
`1`	Bold
`2`	Dim
`31`–`37`	Foreground colours
`90`–`97`	Bright foreground
`1;33`	Compound (bold yellow)
`""`	No colour

Key	Default	Applied to
`col_keyword`	`1;34`	Lua keywords
`col_string`	`32`	String literals
`col_number`	`35`	Numeric literals
`col_operator`	`33`	Operators
`col_comment`	`2`	Comments
`col_current`	`33`	Current line marker
`col_breakpt`	`31`	Breakpoint line number
`col_dim`	`2`	Dimmed elements
`col_header`	`36`	History column headers
`col_lineno`	`33`	Line number inside history headers
`col_watch`	`36`	Watch label prefix
`col_value`	`33`	Evaluated values
`col_info`	`36`	Informational messages
`col_error`	`31`	Error messages
`col_prompt`	`33`	Banner and breakpoint messages

Priority order

Settings are prioritised in this order, from lowest to highest priority:

Built-in defaults (always present)
Config file (~/.config/sild/sild.cfg or --config)
Command-line flags (--lines, --columns, --width)

Useful Notes

rlwrap can be used to enable command history:

alias sild='rlwrap sild'

TODO:

Do all `'-- TODO'` items

lua_src/main.lua

27:-- TODO: Look for annotations in require'd files
28:local breakpoints_list, actions_list = parse.annotations(cli.script_path)

43:  -- TODO: use XDG_CONFIG_HOME here
42: print(ansi.color_dim("n=step  c=continue  ?=help  q=quit") .. "  " ..
43:   -- TODO: use XDG_CONFIG_HOME here
  ansi.color_dim("config: " .. (cli.config_file or (os.getenv("HOME") or "~") .. "/.config/sild/sild.cfg")) .. "\n")

lua_src/sild/commands.lua

10: local function print_help()
11:  local function row(cmd, desc)
12:    print("  " .. ansi.color_value(ansi.fit(cmd, 28)) .. "  " .. desc)
13:  end
14:  -- TODO: Fit to screen width
15:  print()
16:  print(ansi.color_bold("-- Navigation ------------------"))

lua_src/sild/config.lua

31:-- TODO: Replace all this if-elseing with tables of handlers
32:function M.parse_file(path)

lua_src/sild/ui.lua

8:-- TODO: Make part of config
9:local SPLIT_POSITION = 0.35

Add `.editorconfig` instead of using global format styles

Add MacOS target

flake.nix

let
  # TODO: Add x86_64-darwin and aarch64-darwin
  buildTargets = {

callchart - print a bar chart out of call data

PgUp PgDn to scroll code window

Fix `auto_size` toggle

lua_src/sild/config.lua

local config = {
  -- layout
  auto_size        = true,

Luac detection (maybe decomp support?)

`parse.lua` is only about file parsing, maybe rename?

EmmyLua document all functions

Hex code colour support

Improve error messages for target scripts

Have the program name and description set in rust (even possibly cargo)

Allow debugging more than just scripts, be able to descend layers

'vars' is not comprehensive, modify how it chooses

Fix partially broken watch annotations

See if highlight works with multiline strings and longer floating point numbers like (123.456)

Also doesn't handle multiline comments and string escape sequences

These appear at start of debugging program, see if we can skip them

sh [sild.debugger:174] [main.lua:47]