Diagnostics and reports
Text errors
The CLI prints one line to standard error:
error: file.nbl:12:5: message
Exit status is 1.
JSON errors
python3 -m niblick source.nbl --diagnostics-json
The CLI prints a JSON array with one object:
[
{
"file": "source.nbl",
"line": 12,
"column": 5,
"severity": "error",
"message": "unknown function 'foo'"
}
]
Field |
Type |
Meaning |
|---|---|---|
|
string |
Source path, or empty when unavailable |
|
integer |
1-based line |
|
integer |
1-based column |
|
string |
|
|
string |
Diagnostic text |
|
integer |
Optional end line |
|
integer |
End column |
|
string |
Optional diagnostic code |
end_line, end_column, and code appear only when set.
Symbol maps
python3 -m niblick source.nbl --map-json build/source.map.json
python3 -m niblick source.nbl --debug-map build/source.debug.json
--map-json contains globals, functions, runtime routines, flash data, and
code-size buckets. --debug-map contains PC-to-source mappings for the
debugger.
Size report
python3 -m niblick source.nbl --symbols
The report lists per-function word counts, runtime routines, flash data, startup overhead, and the total.
Stack report
python3 -m niblick source.nbl --stack
The report lists maximum non-tail user depth, the deepest path, per-function entry depth, runtime call sites with stack cost, and linked runtime costs. A call that would exceed the five hardware stack entries produces a warning.
Execution trace
python3 -m niblick source.nbl --run --trace --trace-limit 20
Each line contains the PC, raw word, decoded instruction, selected registers,
stack pointer, and flags. --trace-limit caps printed instructions.
I/O trace
python3 -m niblick source.nbl --run --trace-io --io-trace-limit 200
The trace lists step, PC, event kind, address, bit, and before/after values.
--io-trace-limit 0 stores unlimited events.
Dumps
Option |
Output |
|---|---|
|
16 rows of 16 nibbles |
|
UART TX and RX bytes, error state |
|
Page-15 SFR values |