Debugging
The commands that actually help, and how to read a diagnostic.
Debugging in PickleScript starts with a fast type-check, an AST dump, a stable error-code catalogue, and a history of which committed versions compiled.
Start with check
pickle check parses, resolves and type-checks without generating code. It is
the fastest loop in the toolchain:
pickle-cli check src/main.pkl
Read the diagnostic
Every diagnostic carries a stable code, a message that says what happened, the source line, and a caret under the offending span. Codes never change meaning between releases, so they are safe to search for.
| Range | Area |
|---|---|
E01xx |
Lexing and parsing |
E02xx |
Declarations, name resolution, inheritance |
E03xx |
Type checking and expressions |
E04xx |
Operations, attributes, calls, memory builtins |
E05xx |
Ownership and memory |
E07xx |
Stored or returned references |
A diagnostic with no code renders as (uncoded) rather than guessing one.
Look up any code
pickle explain prints the rule and a worked example, with no docs to
install:
pickle-cli explain # every code in the catalogue
pickle-cli explain E0343 # one code, with an example
The catalogue is also maintained as a page, see Diagnostics.
Look at the parse
When a construct is not doing what you expect, dump the tree the parser built:
pickle-cli ast src/main.pkl
The lexer has a matching dump: pickle lex prints the canonical token stream,
one token per line, so you can compare what the lexer produced against what the
parser expected.
History
Two commands answer "when did this break":
pickle historyshows how public types and dependencies evolved across git history, so a type that changed shape has a visible origin.pickle buildsshows, newest first, which committed versions compiled and which failed, with the error codes of the failures.
pickle-cli builds
Between the two, a regression in a dependency is a lookup rather than an investigation.
