more build tools
This commit is contained in:
@@ -30,6 +30,10 @@ Each stage has a corresponding CLI tool that lets you see its output.
|
||||
| streamline | `streamline.ce --ir` | Human-readable canonical IR |
|
||||
| disasm | `disasm.ce` | Source-interleaved disassembly |
|
||||
| disasm | `disasm.ce --optimized` | Optimized source-interleaved disassembly |
|
||||
| diff | `diff_ir.ce` | Mcode vs streamline instruction diff |
|
||||
| xref | `xref.ce` | Cross-reference / call creation graph |
|
||||
| cfg | `cfg.ce` | Control flow graph (basic blocks) |
|
||||
| slots | `slots.ce` | Slot data flow / use-def chains |
|
||||
| all | `ir_report.ce` | Structured optimizer flight recorder |
|
||||
|
||||
All tools take a source file as input and run the pipeline up to the relevant stage.
|
||||
@@ -141,6 +145,160 @@ Function creation instructions include a cross-reference annotation showing the
|
||||
3 function 5, 12 :235 ; -> [12] helper_fn
|
||||
```
|
||||
|
||||
## diff_ir.ce
|
||||
|
||||
Compares mcode IR (before optimization) with streamline IR (after optimization), showing what the optimizer changed. Useful for understanding which instructions were eliminated, specialized, or rewritten.
|
||||
|
||||
```bash
|
||||
cell diff_ir <file> # diff all functions
|
||||
cell diff_ir --fn <N|name> <file> # diff only one function
|
||||
cell diff_ir --summary <file> # counts only
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| (none) | Show all diffs with source interleaving |
|
||||
| `--fn <N\|name>` | Filter to specific function by index or name |
|
||||
| `--summary` | Show only eliminated/rewritten counts per function |
|
||||
|
||||
### Output Format
|
||||
|
||||
Changed instructions are shown in diff style with `-` (before) and `+` (after) lines:
|
||||
|
||||
```
|
||||
=== [0] <anonymous> (args=1, slots=40) ===
|
||||
17 eliminated, 51 rewritten
|
||||
|
||||
--- line 4: if (n <= 1) { ---
|
||||
- 1 is_int 4, 1 :4
|
||||
+ 1 is_int 3, 1 :4 (specialized)
|
||||
- 3 is_int 5, 2 :4
|
||||
+ 3 _nop_tc_1 (eliminated)
|
||||
```
|
||||
|
||||
Summary mode gives a quick overview:
|
||||
|
||||
```
|
||||
[0] <anonymous>: 17 eliminated, 51 rewritten
|
||||
[1] <anonymous>: 65 eliminated, 181 rewritten
|
||||
total: 86 eliminated, 250 rewritten across 4 functions
|
||||
```
|
||||
|
||||
## xref.ce
|
||||
|
||||
Cross-reference / call graph tool. Shows which functions create other functions (via `function` instructions), building a creation tree.
|
||||
|
||||
```bash
|
||||
cell xref <file> # full creation tree
|
||||
cell xref --callers <N> <file> # who creates function [N]?
|
||||
cell xref --callees <N> <file> # what does [N] create/call?
|
||||
cell xref --dot <file> # DOT graph for graphviz
|
||||
cell xref --optimized <file> # use optimized IR
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| (none) | Indented creation tree from main |
|
||||
| `--callers <N>` | Show which functions create function [N] |
|
||||
| `--callees <N>` | Show what function [N] creates (use -1 for main) |
|
||||
| `--dot` | Output DOT format for graphviz |
|
||||
| `--optimized` | Use optimized IR instead of raw mcode |
|
||||
|
||||
### Output Format
|
||||
|
||||
Default tree view:
|
||||
|
||||
```
|
||||
demo_disasm.cm
|
||||
[0] <anonymous>
|
||||
[1] <anonymous>
|
||||
[2] <anonymous>
|
||||
```
|
||||
|
||||
Caller/callee query:
|
||||
|
||||
```
|
||||
Callers of [0] <anonymous>:
|
||||
demo_disasm.cm at line 3
|
||||
```
|
||||
|
||||
DOT output can be piped to graphviz: `cell xref --dot file.cm | dot -Tpng -o xref.png`
|
||||
|
||||
## cfg.ce
|
||||
|
||||
Control flow graph tool. Identifies basic blocks from labels and jumps, computes edges, and detects loop back-edges.
|
||||
|
||||
```bash
|
||||
cell cfg --fn <N|name> <file> # text CFG for function
|
||||
cell cfg --dot --fn <N|name> <file> # DOT output for graphviz
|
||||
cell cfg <file> # text CFG for all functions
|
||||
cell cfg --optimized <file> # use optimized IR
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--fn <N\|name>` | Filter to specific function by index or name |
|
||||
| `--dot` | Output DOT format for graphviz |
|
||||
| `--optimized` | Use optimized IR instead of raw mcode |
|
||||
|
||||
### Output Format
|
||||
|
||||
```
|
||||
=== [0] <anonymous> ===
|
||||
B0 [pc 0-2, line 4]:
|
||||
0 access 2, 1
|
||||
1 is_int 4, 1
|
||||
2 jump_false 4, "rel_ni_2"
|
||||
-> B3 "rel_ni_2" (jump)
|
||||
-> B1 (fallthrough)
|
||||
|
||||
B1 [pc 3-4, line 4]:
|
||||
3 is_int 5, 2
|
||||
4 jump_false 5, "rel_ni_2"
|
||||
-> B3 "rel_ni_2" (jump)
|
||||
-> B2 (fallthrough)
|
||||
```
|
||||
|
||||
Each block shows its ID, PC range, source lines, instructions, and outgoing edges. Loop back-edges (target PC <= source PC) are annotated.
|
||||
|
||||
## slots.ce
|
||||
|
||||
Slot data flow analysis. Builds use-def chains for every slot in a function, showing where each slot is defined and used. Optionally captures type information from streamline.
|
||||
|
||||
```bash
|
||||
cell slots --fn <N|name> <file> # slot summary for function
|
||||
cell slots --slot <N> --fn <N|name> <file> # trace slot N
|
||||
cell slots <file> # slot summary for all functions
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--fn <N\|name>` | Filter to specific function by index or name |
|
||||
| `--slot <N>` | Show chronological DEF/USE trace for a specific slot |
|
||||
|
||||
### Output Format
|
||||
|
||||
Summary shows each slot with its def count, use count, inferred type, and first definition. Dead slots (defined but never used) are flagged:
|
||||
|
||||
```
|
||||
=== [0] <anonymous> (args=1, slots=40) ===
|
||||
slot defs uses type first-def
|
||||
s0 0 0 - (this)
|
||||
s1 0 10 - (arg 0)
|
||||
s2 1 6 - pc 0: access
|
||||
s10 1 0 - pc 29: invoke <- dead
|
||||
```
|
||||
|
||||
Slot trace (`--slot N`) shows every DEF and USE in program order:
|
||||
|
||||
```
|
||||
=== slot 3 in [0] <anonymous> ===
|
||||
DEF pc 5: le_int 3, 1, 2 :4
|
||||
DEF pc 11: le_float 3, 1, 2 :4
|
||||
DEF pc 17: le_text 3, 1, 2 :4
|
||||
USE pc 31: jump_false 3, "if_else_0" :4
|
||||
```
|
||||
|
||||
## seed.ce
|
||||
|
||||
Regenerates the boot seed files in `boot/`. These are pre-compiled mcode IR (JSON) files that bootstrap the compilation pipeline on cold start.
|
||||
|
||||
Reference in New Issue
Block a user