tyc debug

tyc debug [PATH] [--entry FILE] [--debugger MODULE] [--python PATH] [--break TY:LINE]... [--no-build] [--raw-pdb] [-- ARGS...]

Builds the project, then execs python -m pdb build/<entry>.py (or another debugger module). Repeatable --break <ty-file>:<line> flags translate Typhon source locations through the v2 .py.map and inject -c "break …" commands into the debugger session, so you set breakpoints in .ty coordinates and they fire on the corresponding emitted Python lines.

Examples

tyc debug                          # step through build/main.py under pdb
tyc debug --entry api.py           # different entry point
tyc debug --debugger pudb          # use pudb instead
tyc debug --debugger ipdb          # ipdb if you have it
tyc debug -- --verbose --port 8080  # forward args to the script
tyc debug --no-build               # reuse existing build/
tyc debug --raw-pdb                # plain pdb, without the .ty-coordinate wrapper

# Set a breakpoint on a Typhon line:
tyc debug --break src/main.ty:42

# Multiple breakpoints stack:
tyc debug --break src/main.ty:42 --break src/lib/io.ty:7

Flags

Flag	Default	Effect
`--entry FILE`	`main.py`	Entry-point file relative to the build dir.
`--python PATH`	`python3`	Python interpreter.
`--debugger MODULE`	`pdb`	Module to launch via `python -m`. Common choices: `pdb`, `ipdb`, `pudb`, `debugpy`.
`--break TY:LINE`	—	Break at `<ty-file>:<line>` (e.g. `src/main.ty:42`). Repeatable. The line number is parsed from the segment after the last `:`, so Windows-style drive letters (`C:\foo.ty:10`) and POSIX paths both round-trip. Lines that don’t appear in the `.py.map` table surface a warning and are skipped.
`--no-build`	off	Skip rebuilding; assume `build/` is current.
`--raw-pdb`	off	Launch `python -m pdb` directly, without the Typhon-aware `pdb.Pdb` subclass that shows `.ty` locations on every pause. Only meaningful with `--debugger pdb` (the default); choosing another debugger disables the wrapper automatically.

How `--break` works

Each <ty-file>:<line> is resolved by reading the .py.map v2 sidecar that was emitted next to the corresponding build/*.py, looking up the first Python line that originated from the requested Typhon line, and then composing a -c "break build/<file>.py:<py-line>" argument that ships into the debugger’s startup. The first time you hit c (continue) in the debugger session, every --break location is already set.

The mapping is one-to-many in the other direction — a single Typhon line can lower to several Python lines — so --break picks the first Python line that originated from your .ty line. That tends to be the most useful entry point: e.g. gather: blocks break before the first task is created, not somewhere inside the synthesised TaskGroup.

Frame remapping after a crash

By default tyc debug runs pdb through a small generated subclass (TyphonPdb) that loads every .py.map at startup and overrides do_list / do_where / the prompt, so listings, stack displays, and the prompt itself read .ty coordinates. With --raw-pdb (or any --debugger other than pdb) that layer is dropped and frames surface as build/*.py paths. To map a captured traceback back to .ty source, run tyc trace on the saved traceback file:

tyc run --compile -- --bad-arg 2>err.log
tyc trace err.log          # remaps frames to .ty

What’s not implemented yet

A fully Typhon-native debugger — one that steps a .ty statement at a time (one Python statement → one Typhon statement, even when gather: lowers to several Python lines) — is still on the roadmap. The pdb wrapper covers listing, stack display, and the prompt in .ty coordinates, and --break covers breakpoint placement, without the full source-mapped TUI.

Where next

tyc trace — map a Python traceback back to .ty.
tyc run — non-debugger build + exec, or VM-mode run.