textual-debugger 0.2.14__tar.gz → 0.2.16__tar.gz

{textual_debugger-0.2.14 → textual_debugger-0.2.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.14
+Version: 0.2.16
 Summary: A TUI debugger for Python, Perl, and other languages.  Based on textual.
 Author-email: Al Danial <al.danial@gmail.com>
 License: textual-debugger is licensed to you under the MIT/X Consortium license:
@@ -53,10 +53,12 @@ Requires-Dist: debugpy>=1.8.12
 Requires-Dist: pygments>=2.17.0
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.30.0
-Requires-Dist: mcp<3.0.0,>=2.0.0
 Provides-Extra: edit
 Requires-Dist: textual[syntax]>=8.0.0; extra == "edit"
+Provides-Extra: mcp
+Requires-Dist: mcp<3.0.0,>=2.0.0; extra == "mcp"
 Provides-Extra: dev
+Requires-Dist: textual-debugger[mcp]; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
@@ -74,7 +76,7 @@ Dynamic: license-file
 a full-featured terminal-based debugger for Python and other languages
 with a Debug Adapter Protocol (DAP) implementation.  In addition to Python,
 `tdb` comes with built-in support for
-- C and C++ (via `gdb` or `lldb-dap`)
+- C, C++, Fortran (via `gdb` or `lldb-dap`)
 - Rust (via `gdb` or `lldb-dap`, selected explicitly)
 - Perl (via `perl -d`)
 - Bash (via bash's own `DEBUG` trap; bash ≥ 4.4)
@@ -100,12 +102,12 @@ MIT License.  Copyright 2026 by Al Danial.
 `tdb`:
 
 - debugs multiple languages through the Debug Adapter Protocol: Python (via `debugpy`,
-the richest feature set), C/C++ (via `gdb -i dap` or `lldb-dap`), Rust (via `gdb` or
-`lldb-dap`), Perl (via `perl -d`),
-Bash (via bash's own `DEBUG` trap), Tcsh (via source instrumentation of a
-stock `tcsh`), Ruby (via the debug gem's `rdbg`), OCaml (native via
-`lldb-dap`/`gdb`, bytecode via ocamlearlybird), Go (via Delve's `dlv
-dap`), and PowerShell 7 (via PowerShell Editor Services). Most languages are
+the richest feature set); C/C++ and Fortran (via `gdb -i dap` or `lldb-dap`); Rust (via `gdb` or
+`lldb-dap`); Perl (via `perl -d`);
+Bash (via bash's own `DEBUG` trap); Tcsh (via source instrumentation of a
+stock `tcsh`); Ruby (via the debug gem's `rdbg`); OCaml (native via
+`lldb-dap`/`gdb`, bytecode via ocamlearlybird); Go (via Delve's `dlv
+dap`); and PowerShell 7 (via PowerShell Editor Services). Most languages are
 auto-detected from the target; Rust intentionally requires `--lang rust`
 (ref. [Multi-Language Debugging](#multi-language-debugging)).
 
@@ -128,7 +130,7 @@ built with `textual`, `prompt-toolkit`, `urwid`, `curses`, `rich`, and so on
 to have `tdb` pop open automatically at the first uncaught exception, and a live
 breakpoint hook (`tdb.breakpoint()` in Python, `Devel::TdbRemote::breakpoint()`
 in Perl, `Tdb.breakpoint` in Ruby, `tdb.Breakpoint()` in Go, `tdb_breakpoint()`
-in C/C++, `tdb::breakpoint()` in Rust, `Tdb.breakpoint ()` in OCaml) that opens
+in C/C++ and Fortran, `tdb::breakpoint()` in Rust, `Tdb.breakpoint ()` in OCaml) that opens
 `tdb` paused at a line of your choosing
 
 - can be entirely keyboard-driven
@@ -167,6 +169,14 @@ or run it without installing:
 uvx --from textual-debugger tdb  my_program.py
 ```
 
+The MCP server (`tdb-mcp`, `tdb --mcp`) is an optional extra because its
+`mcp` dependency requires the `cryptography` package, which cannot be
+installed on every platform. Add it with:
+
+```bash
+pip install "textual-debugger[mcp]"
+```
+
 
 ## Quick Start
 
@@ -177,9 +187,21 @@ tdb --doc
 # show the Help > About text, where tdb and its config, breakpoints and
 # log files live, and the path + version of each interpreter and native
 # debugger it would use (python, gdb, lldb-dap, perl, ruby, dlv,
-# ocamlearlybird, bash, tcsh, pwsh)
+# ocamlearlybird, bash, tcsh, pwsh), whether gdb has its DAP interpreter
+# (`gdb -i dap`), whether perl has ExtUtils::MakeMaker (needed to
+# build the bundled PadWalker), and the `examples dir` holding the
+# per-language examples (C, C++, Fortran, Go, OCaml, Perl, PowerShell,
+# Python, Ruby, Rust, bash, tcsh) installed with the package
 tdb --info
 
+# reset config.json to defaults (the old file is kept as
+# config.json-YYYY-mm-DD-HH:MM:SS; HH.MM.SS on Windows)
+tdb --config write-default
+
+# build and cache the bundled PadWalker Perl module now rather than
+# on the first Perl launch
+tdb --config install-padwalker
+
 # debug a Python program (stops at first line by default)
 tdb my_program.py
 
@@ -258,7 +280,7 @@ languages are supported out of the box:
 | Language | Adapter(s) | Dependencies           | Feature level |
 |----------|------------|------------------------|---------------|
 | Python | `debugpy` (default) | Python ≥ 3.11 | everything in this README |
-| C / C++ (any native binary) | `gdb` (default), `lldb-dap` (alternate) | `gdb -i dap` requires GDB ≥ 14 built with Python (RHEL 8/9: `dnf install gcc-toolset-14-gdb`, see [C/C++ tips](#cc-tips)); `lldb-dap` ships with LLVM ≥ 17 (e.g. `apt install lldb`) | core debugging: breakpoints, stepping, stack, variables, evaluate console + remote attach (gdbserver/lldb-server, local symbol-bearing executable required) |
+| C / C++ / Fortran (any native binary) | `gdb` (default), `lldb-dap` (alternate) | `gdb -i dap` requires GDB ≥ 14 built with Python (RHEL 8/9: `dnf install gcc-toolset-14-gdb`, see [C/C++/Fortran tips](#cc-tips)); `lldb-dap` ships with LLVM ≥ 17 (e.g. `apt install lldb`) | core debugging: breakpoints, stepping, stack, variables, evaluate console + remote attach (gdbserver/lldb-server, local symbol-bearing executable required) |
 | Rust (explicit `--lang rust`) | `gdb` (Linux default), `lldb-dap` (macOS default) | any rustc building with debug info; GDB ≥ 14 or LLVM `lldb-dap` ≥ 17 (concurrency ownership evidence additionally requires stable Rust 1.98) | core debugging + best-effort Rust concurrency inspection + remote attach |
 | Perl | perl-tdb (bundled) | perl ≥ 5.18 on PATH  | core debugging + remote attach |
 | Bash | bash-tdb (bundled) | bash ≥ 4.4 on PATH  | core debugging (no remote attach) |
@@ -279,7 +301,7 @@ The language is auto-detected from the debug target:
    `.sh` / `.bash` → Bash; `.csh` / `.tcsh` → Tcsh; `.rb` → Ruby; `.ps1` /
    `.psm1` → PowerShell. (`.ml` / `.mli` do *not* auto-select OCaml, see
    point 6.)
-3. Native executables (ELF, Mach-O, PE magic bytes) → C/C++, unless
+3. Native executables (ELF, Mach-O, PE magic bytes) → C/C++/Fortran, unless
    byte-checking finds an OCaml marker (a native binary's
    `caml_program`/`caml_startup` runtime symbols, a bytecode file's
    trailing `Caml1999` marker, or a `#!...ocamlrun` shebang) → OCaml
@@ -287,13 +309,13 @@ The language is auto-detected from the debug target:
    `go version` itself locates, scanned in the first 16MB of the file) →
    Go. A stripped native OCaml binary, or a Go binary whose buildinfo
    blob sits beyond the 16MB scan window, that byte-checking can't
-   identify falls back to C/C++; force it with `--lang ocaml` or `--lang
+   identify falls back to C/C++/Fortran; force it with `--lang ocaml` or `--lang
    go` respectively. Rust is never inferred from an executable; select it
    explicitly with `--lang rust`.
 4. A `#!...python`, `#!...perl`, `#!...bash`, `#!...csh`/`#!...tcsh`,
    `#!...ruby`, or `#!...pwsh` shebang → Python / Perl / Bash / Tcsh / Ruby /
    PowerShell respectively.
-5. C/C++/Rust *source* files (`.c`, `.cpp`, `.rs`, …) produce an error with a
+5. C/C++/Fortran/Rust *source* files (`.c`, `.cpp`, `.rs`, …) produce an error with a
    hint: compile with debug info (`g++ -g -O0`) and debug the binary.
 6. `.ml` / `.mli` (OCaml source) produce an error too: build the project
    first (dune's dev profile keeps debug info) and pass the **built
@@ -320,7 +342,7 @@ message naming its path and version; when that `gdb` came from `PATH`
 (not from `--adapter` or `config.json`), `tdb` first looks for a newer one
 installed by Red Hat's Software Collections
 (`/opt/rh/gcc-toolset-*/root/usr/bin/gdb`, `/opt/rh/devtoolset-*/...`) and
-uses the newest that qualifies. See [C/C++ tips](#cc-tips) for RHEL 8.
+uses the newest that qualifies. See [C/C++/Fortran tips](#cc-tips) for RHEL 8.
 
 > **Migration note:** extensionless Python scripts without a `python` shebang
 > were previously assumed to be Python; they now require `--lang python`.
@@ -358,16 +380,16 @@ programs by nature). Remote attach (`-r`) also works for Perl (see
 [Perl](#perl), `Devel::TdbRemote` in place of `debugpy.listen()`), Ruby
 (see [Ruby](#ruby), `rdbg --open` in place of `debugpy.listen()`), Go (see
 [Go](#go), `dlv dap --listen` in place of `debugpy.listen()`), and for
-Rust and C/C++ native binaries (against a gdbserver/lldb-server stub, with
+Rust and C/C++/Fortran native binaries (against a gdbserver/lldb-server stub, with
 a local symbol-bearing executable; see [Rust](#rust) — the same flags work
-for a C/C++ target without `--lang`), but not for Bash, Tcsh, OCaml, or
+for a C/C++/Fortran target without `--lang`), but not for Bash, Tcsh, OCaml, or
 PowerShell. `--terminal` works for every launch-mode
-language — Python, Perl, Bash, Tcsh, Ruby, and C/C++, OCaml native, or Rust
+language — Python, Perl, Bash, Tcsh, Ruby, and C/C++/Fortran, OCaml native, or Rust
 sessions via `--adapter lldb-dap` — see
 [External Terminal Support](#external-terminal-support). Go and PowerShell do
 not support `--terminal` yet (`dlv dap` and PSES have no terminal-routing
 mode). Typing into the Console view to feed the program's stdin works for
-Python, Perl, Bash, Tcsh, Ruby, and PowerShell, but not for C/C++, Rust,
+Python, Perl, Bash, Tcsh, Ruby, and PowerShell, but not for C/C++/Fortran, Rust,
 OCaml, or Go, whose adapters spawn the debuggee themselves — see
 [Console Output and Input](#console-output-and-input).
 
@@ -458,14 +480,14 @@ picture:
   multiprocessing child attach.
 - Detection of a Go binary via buildinfo check scans only the first
   16MB of the file; a huge binary whose buildinfo blob sits beyond that
-  falls back to C/C++ — force it with `--lang go`.
+  falls back to C/C++/Fortran — force it with `--lang go`.
 - `-a`/`--attach`'s language auto-detection (reading the target pid's
   buildinfo from `/proc/PID/exe`) is Linux-only; on macOS/Windows pass
   `--lang go` alongside `-a`.
 
 See [Go](#go) below for launch details.
 
-### C/C++ tips
+### C/C++/Fortran tips
 
 - Compile with `-g` (ideally `-g -O0` or `-g3 -O0`).
   If no breakpoint in a file can be
@@ -485,6 +507,29 @@ See [Go](#go) below for launch details.
 - GDB (the default adapter) has the most complete libstdc++
   pretty-printing. `lldb-dap` (via `--adapter lldb-dap`) also debugs
   GCC-built binaries fine.  DWARF is compiler-neutral.
+- **STL containers in the Variables view.** A distro `gdb` shows
+  `std::vector<Result>` as `std::vector of length 2, capacity 2` with
+  `[0]`, `[1]` children because gcc installs libstdc++'s pretty-printers
+  next to it and `gdb` auto-loads them. A `gdb` built from source into
+  its own prefix never finds that auto-load script and shows the same
+  variable as `_M_impl` / `_M_start` pointer soup. `tdb` sources a small
+  helper into every `gdb` session that, on the first `std::` value it
+  sees, looks for gcc's printers (the distro auto-load script for the
+  loaded `libstdc++.so`, `share/gcc*/python` near that library or near
+  gdb's data directory, then the usual distro, Red Hat toolset, Homebrew
+  and MacPorts locations) and uses them; when none are installed it
+  falls back to its own bundled printers for `std::string`, `vector`,
+  `deque`, `list`, `map`/`set` (and multi-), `unordered_map`/`set`,
+  `unique_ptr`, `shared_ptr`/`weak_ptr` and `optional`. Printers gdb
+  auto-loads itself or that your `.gdbinit` registers still take
+  precedence. The helper also shields gdb's DAP layer from gcc 15's map
+  and set printers, whose child count is broken there (expanding a
+  `std::map` fails with "name 'self' is not defined" on an unpatched
+  distro gdb). `TDB_GDB_STL_PRINTERS` tunes it: `off` registers nothing,
+  `bundled` forces the bundled printers (and drops gdb's auto-loaded
+  ones), a directory holding `libstdcxx/` names gcc's printers
+  explicitly. Type `tdb-stl-printers` in the evaluate console to see
+  which printers are in use.
 - **GDB evaluate-console quirk:** GDB's DAP treats REPL input as CLI
   commands, so evaluate expressions with an explicit `print`, e.g.
   `print x` rather than bare `x` (bare `x` collides with GDB's
@@ -501,7 +546,8 @@ See [Go](#go) below for launch details.
   from the evaluate console without you having typed `list`.
 - **RHEL 8 (and 9) gdb is too old for DAP:** the stock `/usr/bin/gdb` is
   8.2 on RHEL 8 (10.2 on RHEL 9) and answers `gdb -i dap` with
-  ``Interpreter `dap' unrecognized``. Install a newer one from the
+  ``Interpreter `dap' unrecognized``. Install a newer one
+  (minimum GCC Toolset version is 14) from the
   GCC Toolset, which leaves `/usr/bin/gdb` alone:
 
   ```bash
@@ -517,19 +563,22 @@ See [Go](#go) below for launch details.
   wrote the file). Either delete the entry or point it at the toolset
   gdb. A GDB ≥ 14 that was built without Python support gives the same
   ``Interpreter `dap' unrecognized`` error (`gdb --configuration` shows
-  `--without-python`); use `--adapter lldb-dap` or a gdb built with
+  `--without-python`); `tdb --info` probes for this and reports
+  `GDB LACKS DAP CAPABILITY AND CANNOT BE USED` in its `DAP interpreter`
+  row when the gdb it found rejects `-i dap`. Use `--adapter lldb-dap`
+  or a gdb built with
   Python.
 
 **Attach to a running process:** `tdb -a PID` attaches gdb (or `--adapter
 lldb-dap`) to a live native process and stops it. On Linux tdb reads
 `/proc/PID/exe` to identify the language (Go, OCaml, Rust, otherwise
-C/C++) and to load symbols; pass the executable path as well to use a
+C/C++/Fortran) and to load symbols; pass the executable path as well to use a
 different symbol file, and pass `--lang` off Linux. `--no-pause-on-attach`
 leaves the process running, for a program about to stop itself. An
-interpreter process (python3, perl, ruby, bash) is attached as C/C++; for
+interpreter process (python3, perl, ruby, bash) is attached as C/C++/Fortran; for
 Python, Perl, and Ruby programs use `--remote-attach` instead.
 
-**Live breakpoint hook:** the C/C++ counterpart of Python's
+**Live breakpoint hook:** the C/C++/Fortran counterpart of Python's
 [`tdb.breakpoint()`](#live-breakpoint-hook). Include `tdb.h` (its directory
 is the `tdb.h dir` row of `tdb --info`) and call `tdb_breakpoint()`:
 
@@ -567,6 +616,29 @@ header-only. Linux only: the hook grants ptrace access to tdb's debugger
 with `PR_SET_PTRACER`; elsewhere it warns once and returns. See
 `examples/C/breakpoint_hook_demo.c` and `examples/C++/breakpoint_hook_demo.cpp`.
 
+Fortran (or any language that can call C) uses the same header: compile
+`tdb.h` as C into an object that defines `tdb_breakpoint()`, declare it with
+`bind(C)`, and link the object in:
+
+```fortran
+interface
+    subroutine tdb_breakpoint() bind(C, name="tdb_breakpoint")
+    end subroutine tdb_breakpoint
+end interface
+...
+call tdb_breakpoint()   ! tdb opens here, paused on the next line
+```
+
+```bash
+gcc -g -O0 -c -x c "$(tdb --info | awk -F': ' '/tdb.h dir/ {print $2}')/tdb.h" -o tdb.o
+gfortran -g -O0 -o prog prog.f90 tdb.o
+./prog    # run it directly, not under tdb
+```
+
+Use gdb (the default) for Fortran: lldb-dap stops on the right line but,
+lacking Fortran support, shows no Fortran locals. See
+`examples/Fortran/breakpoint_hook_demo.f90`.
+
 ### Rust
 
 Rust debugging is intentionally explicit: build a normal debug executable,
@@ -587,7 +659,7 @@ cargo rustc -- -C debuginfo=2 -C opt-level=0
 # Equivalent direct rustc settings: rustc -C debuginfo=2 -C opt-level=0 src/main.rs
 ```
 
-As for C/C++, the Console view cannot feed the program's stdin (the gdb and
+As for C/C++/Fortran, the Console view cannot feed the program's stdin (the gdb and
 lldb adapters spawn it themselves); use `--terminal` with `--adapter
 lldb-dap` for interactive programs. A panic that terminates the debuggee opens the error modal with the parsed
 panic message and backtrace; `tdb` injects `RUST_BACKTRACE=1` into launched
@@ -624,7 +696,7 @@ for example `ssh -L 2345:127.0.0.1:2345 host`, then attach to `127.0.0.1:2345`.
 `--adapter lldb-dap`) to a live Rust process and stops it; tdb loads
 symbols from `/proc/PID/exe`, or from an executable path you pass as well.
 Without `--lang`, tdb recognizes a non-stripped Rust binary by its runtime
-symbols; a stripped one is debugged as C/C++.
+symbols; a stripped one is debugged as C/C++/Fortran.
 
 **Live breakpoint hook:** the Rust counterpart of Python's
 [`tdb.breakpoint()`](#live-breakpoint-hook). Depend on the `tdb` crate from
@@ -696,12 +768,20 @@ per interpreter under its config directory (`~/.config/tdb/padwalker/` on
 Linux/macOS, `%APPDATA%\\tdb\\padwalker\\` on Windows), and prepends that
 directory to the debuggee's `PERL5LIB`.  The build takes about a second and
 needs perl's headers (`libperl-dev` on Debian/Ubuntu, `perl-devel` on
-Fedora/RHEL) plus a C compiler; Strawberry Perl on Windows ships both.  When
-the build is not possible, `tdb` prints a one-line notice on the console and
-falls back to a read-only pad walk, so outer-frame lexicals degrade but
-debugging otherwise proceeds.  `tdb --info` reports the source directory, the
-cache directory, and whether a build exists for the `perl` on your `PATH`.
+Fedora/RHEL), a C compiler, and the core `ExtUtils::MakeMaker` module (some
+minimal distro perls omit it; `perl-ExtUtils-MakeMaker` on Fedora/RHEL);
+Strawberry Perl on Windows ships all three.  When the build is not possible,
+`tdb` prints a one-line notice on the console and falls back to a read-only
+pad walk, so outer-frame lexicals degrade but debugging otherwise proceeds.
+`tdb --info` reports the source directory, the cache directory, and the
+`ExtUtils::MakeMaker` version of the `perl` it would use, with a warning when
+that module is missing and PadWalker therefore cannot be built.
 `TDB_PADWALKER_CACHE` overrides the cache location.
+To build it ahead of time (for example when provisioning a machine, or to
+see the compiler's error output without starting a debug session), run
+`tdb --config install-padwalker`; it exits 0 when PadWalker loads
+(natively, from the cache, or freshly built) and 1 with the reason when it
+cannot be built.
 
 **Launching a script:**
 
@@ -1001,7 +1081,7 @@ tihs line correctly.
 usual behavior.
 
 A stripped native binary that byte-checking can't identify as OCaml falls
-back to C/C++; force it with `--lang ocaml`. Override the adapter or point
+back to C/C++/Fortran; force it with `--lang ocaml`. Override the adapter or point
 at a non-`PATH` install in `config.json` (see
 [Configuration](#configuration)):
 
@@ -1131,7 +1211,7 @@ tdb -r host:port --lang go # attach to a `dlv dap --listen` already running remo
 
 `tdb --test ./pkg` debugs the package's tests under Delve's `test` mode;
 pass test-binary flags after `--`, e.g. `tdb --test ./pkg -- -run TestFoo`.
-`-a`/`--attach` works for Go and, through gdb/lldb-dap, for C/C++, Rust,
+`-a`/`--attach` works for Go and, through gdb/lldb-dap, for C/C++/Fortran, Rust,
 and OCaml; on Linux `tdb` identifies the language from `/proc/PID/exe`
 without `--lang` (elsewhere pass `--lang go` alongside `-a`). Attaching
 stops the process immediately so you get control right away;
@@ -1330,6 +1410,13 @@ A cursor line (blue) tracks your position; the current execution line is highlig
 | `Ctrl+S` | Stack View |
 | `Ctrl+B` | Breakpoint View |
 
+Pressing the shortcut of the view that already has focus returns focus to
+the previous view, so e.g. `Ctrl+E` jumps from the Code View to the
+Evaluate Console and a second `Ctrl+E` jumps back.
+The shortcuts also work while typing in the Evaluate Console and the
+Console View's stdin line, where `Ctrl+E` and `Ctrl+V` take precedence over
+end-of-line and paste (`End` and the terminal's own paste still work).
+
 **Menu-bar shortcuts (global):**
 
 `Alt+<first-letter>` opens the corresponding tab in the menu bar.
@@ -1507,7 +1594,7 @@ returns. Two ways to pin, two ways to unpin:
 | | Evaluate Console | Variables View |
 |---|---|---|
 | pin | `display b` | right-click the variable's row |
-| unpin | `undisplay b` | left-click its row under **Display** |
+| unpin | `undisplay b` | right-click its row under **Display** |
 
 ```
 >>> display b
@@ -1523,6 +1610,8 @@ returns. Two ways to pin, two ways to unpin:
 
 Right-clicking a child of an expanded object pins the full path
 (`obj.count`, `items[2]`), and a bare `display` lists everything pinned.
+Left-click works the same under **Display** as in every other scope:
+it expands or collapses an object, and a double-click opens it in a modal.
 A click in the Variables View is recorded exactly as the typed command,
 so `--record`/`--replay` sessions reproduce it. Some terminals keep
 right-click for their own paste or context menu (Windows Terminal and
@@ -1588,8 +1677,8 @@ variable lives:
 | tcsh | `set name …`, `setenv NAME …` | the whole run |
 | Ruby | `name = …`, `$name = …`, `@name = …` | globals and instance variables persist; plain locals live only in the eval's binding and read back as unavailable after the next step |
 | PowerShell | `$name = …`, `$global:name = …` | the function scope, or the whole run for `$global:` |
-| C/C++/Rust/OCaml under gdb | `set $name = …` (a gdb convenience variable) | the whole run |
-| C/C++/Rust/OCaml under lldb-dap | `int $name = …` (an lldb persistent variable) | the whole run |
+| C/C++/Fortran/Rust/OCaml under gdb | `set $name = …` (a gdb convenience variable) | the whole run |
+| C/C++/Fortran/Rust/OCaml under lldb-dap | `int $name = …` (an lldb persistent variable) | the whole run |
 | Go (dlv), OCaml under ocamlearlybird | not possible: their evaluate cannot create variables | — |
 
 A tracked name that no longer resolves (a Python local after its frame
@@ -1619,7 +1708,7 @@ when the session has no stdin to feed.
 
 Stdin forwarding works for the languages whose program `tdb` launches on a
 pipe it owns: Python, Perl, Bash, Tcsh, Ruby, and PowerShell. It is not
-available for the compiled languages — C/C++, Rust, OCaml, and Go — because
+available for the compiled languages — C/C++/Fortran, Rust, OCaml, and Go — because
 their adapters (`gdb -i dap`, `lldb-dap`, `dlv dap`) spawn the debuggee
 themselves and give `tdb` no handle on its stdin; the input line stays
 hidden there. It is also unavailable for remote attach (`-r`), where the
@@ -1744,12 +1833,57 @@ This behavior matches hitting `c` while in a conventional (that is, the Python
 standard library's) `breakpoint()` session.
 If you want to kill the program instead, use `Ctrl+c` in the terminal running the debuggee.
 
-Perl, Ruby, Go, C/C++, Rust, and OCaml programs get the same hook as
+Perl, Ruby, Go, C/C++/Fortran, Rust, and OCaml programs get the same hook as
 `Devel::TdbRemote::breakpoint()`, `Tdb.breakpoint`, `tdb.Breakpoint()`,
 `tdb_breakpoint()`, `tdb::breakpoint()`, and `Tdb.breakpoint ()`; see
-[Perl](#perl), [Ruby](#ruby), [Go](#go), [C/C++ tips](#cc-tips),
+[Perl](#perl), [Ruby](#ruby), [Go](#go), [C/C++/Fortran tips](#cc-tips),
 [Rust](#rust), and [OCaml](#ocaml).
 
+### pytest Integration (`--pdbcls`)
+
+`tdb` can stand in for `pdb` when `pytest` stops on a failing test, the
+same way IPython (`--pdbcls=IPython.terminal.debugger:Pdb`) and pudb
+(`--pdbcls=pudb.debugger:Debugger`) do:
+
+```bash
+pytest --pdb --pdbcls=tdb.pytest_debugger:Debugger
+```
+
+`-s` / `--capture=no` is not required; pytest suspends output capturing
+before handing control to the debugger. To make it the default, add the
+options to your pytest configuration:
+
+```toml
+[tool.pytest.ini_options]
+addopts = "--pdbcls=tdb.pytest_debugger:Debugger"
+```
+
+(`tdb.pytest_debugger:Pdb` is an alias for the same class.)
+
+What you get depends on how pytest enters the debugger:
+
+| pytest trigger | `tdb` behavior |
+|---|---|
+| `--pdb`, test fails or errors | Post-mortem TUI on the failing test, as with [`tdb.exception_hook`](#post-mortem-exception-hook). Navigate the stack and inspect every frame's variables at the point of failure. pytest's own runner frames are trimmed from the Stack View. Quit `tdb` (`q`, then `q` again to confirm) and pytest moves on to the next test. |
+| `breakpoint()` or `pytest.set_trace()` in a test | Live `tdb` attached to the pytest process, paused on the line after the call, as with [`tdb.breakpoint()`](#live-breakpoint-hook). Step, evaluate, set breakpoints, continue. |
+| `--trace` | Live `tdb` paused on the first line of each test. |
+
+Notes:
+
+- Post-mortem mode is a frozen snapshot: no Evaluate View, no stepping.
+  For a live view of a failure, put a `breakpoint()` in the test (or use
+  `--trace`) and `continue`. `tdb` stops on the failing line with the
+  interpreter still alive.
+- One live `tdb` serves the whole pytest run. After `continue` it stays
+  attached, showing **Running**, and the next `breakpoint()` or `--trace`
+  stop appears in it. If a test fails under `--pdb` while it is still
+  attached, the post-mortem view opens once you quit the live `tdb`.
+- Every failure opens its own post-mortem session. Combine with `-x` or
+  `--maxfail=N` to limit how many you step through.
+- Live stops need `debugpy` installed in the environment running pytest.
+- When stdin/stdout aren't a terminal (CI, `pytest-xdist` workers), the
+  class falls back to plain `pdb` behavior.
+
 ### Async Task Inspector
 
 For programs using `asyncio`, the menu bar shows an **Async Tasks (N)** label with the count of
@@ -1924,8 +2058,8 @@ tdb --terminal xterm my_tui_app.py
 ```
 
 `--terminal` works for every language `tdb` can *launch* (as opposed to
-attach to): Python, Perl, Bash, Tcsh, Ruby, and C/C++ or native OCaml
-sessions via `--adapter lldb-dap`. Neither `gdb -i dap` (the default C/C++
+attach to): Python, Perl, Bash, Tcsh, Ruby, and C/C++/Fortran or native OCaml
+sessions via `--adapter lldb-dap`. Neither `gdb -i dap` (the default C/C++/Fortran
 adapter, and an alternate for native OCaml) nor `ocamlearlybird` (the
 bytecode OCaml adapter) has any terminal integration -- `tdb` rejects
 `--terminal` up front for both, with an error pointing at `--adapter
@@ -2033,7 +2167,7 @@ nonzero `sys.exit()`, which `debugpy` treats as an uncaught `SystemExit` -- `tdb
 the TUI at the point of failure instead of exiting silently, so you can inspect the
 crash. Exit-code passthrough applies only to a clean exit during the headless phase.
 
-Supported languages: Python, Perl, Bash, Tcsh, Ruby, PowerShell 7, C/C++
+Supported languages: Python, Perl, Bash, Tcsh, Ruby, PowerShell 7, C/C++/Fortran
 (both `gdb` and `lldb-dap`), and native OCaml (both `gdb` and `lldb-dap`;
 bytecode/`ocamlearlybird` sessions don't support pause, so `--run` is
 unavailable for those). `--run` is rejected up front for any other
@@ -2043,7 +2177,18 @@ language.
 blocking external call or syscall, the pause can't land until that call returns --
 `tdb` prints a notice and opens the TUI once the stop actually arrives.
 
-**Incompatible flags:** `-r`, `-k`/`-t`, `--record`, `--replay`, `--replay-tui`, `--server`,
+**Breakpoints:** run mode never uses breakpoints saved in `breakpoints.json`, and
+never writes to it either, so the breakpoints you saved for normal sessions are left
+untouched. Breakpoints given on the command line with `-k`/`-t` are accepted, but they
+stay inactive while the program runs headlessly. They are installed the first time the
+TUI opens (normally when you press Ctrl-C), and stay live after you detach, so the
+program then stops at them:
+
+```bash
+tdb --run -k 120 -k utils.py:45 my_program.py   # breakpoints arm on the first Ctrl-C
+```
+
+**Incompatible flags:** `-r`, `--record`, `--replay`, `--replay-tui`, `--server`,
 `--headless`, `--mcp`, `--terminal`.
 
 ### Eval Mode (`-e`/`--eval`)
@@ -2085,7 +2230,7 @@ evaluated in each child process that reaches it.
   uncaught-exception stop) is continued untouched, so the program runs to
   completion unattended.
 - For non-Python debuggees the expression must be in the debug adapter's
-  own syntax, for example gdb's `print x` / `set var x=3` for C/C++, and not
+  own syntax, for example gdb's `print x` / `set var x=3` for C/C++/Fortran, and not
   necessarily the debuggee's language. The adapter may bind the breakpoint
   to the next executable line (gdb moves one off a declaration or brace);
   the eval point matches that bound line, so the expression still runs.
@@ -2272,6 +2417,16 @@ its companion `examples/sales_report_buggy.py`.
 
 ### Running the MCP server
 
+The MCP server needs the optional `mcp` extra:
+
+```bash
+pip install "textual-debugger[mcp]"
+```
+
+Without it, `tdb-mcp` and `tdb --mcp` exit with that install hint, and
+`tdb --info` reports `MCP server : not installed`. Everything else in
+tdb works without the extra.
+
 Configure your MCP client (Claude Desktop, an IDE extension, etc.) to
 launch `tdb-mcp` over stdio. Example `claude_desktop_config.json`:
 
@@ -2357,13 +2512,14 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
            [--terminal {xterm,konsole,gnome-terminal,ghostty,kitty,iterm2,warp,wezterm,terminator}]
            [--local-root PATH] [--remote-root PATH]
            [--server] [--headless] [-k FILE:LINE|LINE] [--server-port SERVER_PORT] [-d] [--doc-text] [--info]
+           [--config {write-default,install-padwalker}]
            [program] [args ...]
 ```
 
 | Flag | Description |
 |------|-------------|
 | `-r HOST:PORT` | Attach to a remote debugpy server |
-| `-a`, `--attach PID` | Attach to a running local process by pid: Go (Delve) or a native C/C++, Rust, or OCaml program (gdb or lldb-dap). Linux identifies the language from `/proc/PID/exe`; elsewhere pass `--lang` and, for native programs, the executable path. |
+| `-a`, `--attach PID` | Attach to a running local process by pid: Go (Delve) or a native C/C++, Fortran, Rust, or OCaml program (gdb or lldb-dap). Linux identifies the language from `/proc/PID/exe`; elsewhere pass `--lang` and, for native programs, the executable path. |
 | `--local-root PATH` | Local directory containing a copy of remote code (repeat to mirror multiple trees). Pair with `--remote-root`; counts must match. Required when `-k` sets a breakpoint against a remote debuggee whose code lives at a different path. |
 | `--remote-root PATH` | Remote directory matched to `--local-root` (same CLI position via `zip()`). |
 | `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated). Passing `-k` implies `--no-stop-on-entry` so the program runs straight to the first breakpoint. |
@@ -2392,6 +2548,11 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | `--replay-interval S` | With `--replay`/`--replay-tui`: fixed S-second delay before each action instead of the recorded gaps |
 | `--replay-timeout S` | With `--replay`/`--replay-tui`: per-action stop-wait timeout (default 30) |
 | `--examine-log DEST` | With --run: write each Ctrl-\ / SIGUSR2 stack snapshot to DEST (- = stdout; repeatable) |
+| `--doc` | Display this README in a terminal Markdown viewer and exit |
+| `--doc-text` | Print this README to stdout as wrapped plain text and exit |
+| `--info` | Print the About text, file locations, and the path and version of each interpreter and debugger `tdb` would use, then exit |
+| `--config write-default` | Rename the existing `config.json` to `config.json-YYYY-mm-DD-HH:MM:SS` (`HH.MM.SS` on Windows, which forbids colons in filenames) and write a new one holding every default value, then exit |
+| `--config install-padwalker` | Build and cache the bundled PadWalker Perl module now, for the perl `tdb` would debug with (`adapters.perl` in `config.json`, else `perl` on `PATH`), instead of waiting for the first Perl launch; exits 1 if it cannot be built |
 
 ## Configuration
 
@@ -2406,7 +2567,9 @@ On Windows, it uses `%APPDATA%\tdb\`.
 
 ### Sample `config.json`
 
-Every key `tdb` reads, with its default or a representative value. Copy
+Every key `tdb` reads, with its default or a representative value.
+`tdb --config write-default` writes a fresh file with these defaults
+(moving the old one aside as `config.json-YYYY-mm-DD-HH:MM:SS`), or copy
 this to restore a deleted or corrupted file, then delete the entries you
 don't need: a missing key takes its default, an unknown key is ignored,
 and an invalid value (say a misspelled `step_mode`) falls back to the
@@ -2495,7 +2658,7 @@ fires as expected.
 
 - [textual](https://github.com/Textualize/textual) : TUI framework
 - [debugpy](https://github.com/microsoft/debugpy) : Debug Adapter Protocol implementation for Python
-- [gdb](https://sourceware.org/gdb/) / [lldb-dap](https://lldb.llvm.org/resources/lldbdap.html) : optional, user-installed DAP adapters for C/C++
+- [gdb](https://sourceware.org/gdb/) / [lldb-dap](https://lldb.llvm.org/resources/lldbdap.html) : optional, user-installed DAP adapters for C/C++/Fortran
 - [debug gem](https://github.com/ruby/debug) (`rdbg`) : optional, user-installed DAP adapter for Ruby
 - [ocamlearlybird](https://github.com/hackwaly/ocamlearlybird) : optional, user-installed DAP adapter for OCaml bytecode (native OCaml reuses `gdb`/`lldb-dap`)
 - [pygments](https://pygments.org/) : Syntax highlighting