diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 276 |
1 files changed, 276 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..62dcb22 --- /dev/null +++ b/README.md @@ -0,0 +1,276 @@ +# 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: + +```sh +cp sild ~/.local/bin/sild +chmod +x ~/.local/bin/sild +``` + +--- + +## Quick start + +```sh +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. + +```sh +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. + +```lua +--- BREAK +``` +Break on the following line. + +```lua +--- 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. + +```lua +--- 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`. + +```lua +--- 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 + +```ini +# 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: + +1. Built-in defaults (always present) +2. Config file (`~/.config/sild/sild.cfg` or `--config`) +3. Command-line flags (`--lines`, `--columns`, `--width`) + +--- + +## Useful Notes + +`rlwrap` can be used to enable command history: +```sh +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] + ``` |