punkshell/goals/G-108-buildsuite-debug-tier.md

G-108 Debug buildsuite tier: tcl::test-enabled runtimes (-dbg) with recorded constrained-test runs

Status: proposed Scope: src/buildsuites/suite_tcl90/ (build905.zig debug knobs + tcl::test wiring, suite.tcl debug variant steps, tools/test_gate.tcl record runs); kit-family debug members coordinate with G-103 Goal: the suite can build debug-tier variants of its runtimes, named with a trailing -dbg tier suffix, in which the C test extension (tcl::test) is compiled in and the relevant debug defines are enabled (tiered: at minimum assertions live / NDEBUG off with tcl::test; a deeper tier adds TCL_MEM_DEBUG so script-level commands such as memory exist), verifiable via ::tcl::build-info fields (debug, memdebug); under a debug shell the core testsuite's normally skipped C-test-command-constrained tests (testobj, testchannel, testdstring, testevalex, etc. — ~11k skips in the release census) actually run, recorded (never gated) via the existing test_gate record mode with separate artifacts; where feasible, full kit family members are also produced at debug tiers so applications can be exercised in a debug-friendly runtime. Acceptance: a suite invocation produces a debug-tier tclsh whose ::tcl::build-info reports debug=1 (and memdebug=1 at the memory tier, with memory present as a command) and where package require tcl::test succeeds; a record-mode core-suite run under that shell completes with its skip count reduced by thousands relative to the release census (C-test-command constraints resolving true), with summary/log artifacts under out/testreports/ recorded in this file; the release gate composite and its baseline are unchanged by the debug tier's existence (debug runs are record-only, opt-in steps); debug runtime and kit names carry a trailing -dbg distinguishing them from release artifacts; kit-family debug feasibility (all bundled extensions rebuilt with matching debug defines, per the TCL_MEM_DEBUG all-or-nothing linking constraint) is resolved and recorded here — either the family members exist at least at one tier, or the blocking findings are documented.

Context

Drafted 2026-07-21 from the release-census skip analysis: the suite's ~11,435 core-suite skips are dominated by per-command tcltest constraints (testobj, testchannel ~213 guarded lines, testdstring ~46, testevalex, testchmod, testbytestring, testsetplatform, testfilehandler, testnrelevels, testfs, ...) that probe for C test commands from the tcl::test loadable extension (generic/tclTest.c, tclTestObj.c and friends), which the release build deliberately never compiles. In a debug build where tcl::test loads, most of those skips become runs.

::tcl::build-info is the verification surface (punk91 census 2026-07-21): debug = NDEBUG absent, memdebug = TCL_MEM_DEBUG, compiledebug = TCL_COMPILE_DEBUG, no-optimize = TCL_CFG_OPTIMIZED absent, plus profile/ purify. Current suite builds report none set (ReleaseFast, no tcl::test).

Existing hooks: build905.zig already forwards -Doptimize (default ReleaseFast) into the staged build, and carries commented-out TCL_MEM_DEBUG/-DNDEBUG lines with the recorded warning that TCL_MEM_DEBUG must be defined for ALL modules linked together or none — TCL_MEM_DEBUG redefines the allocator macros, so a memdebug shell requires every static/loaded extension (thread, tclvfs, tk, tcllibc accelerators) rebuilt with the same define. TCL_COMPILE_DEBUG/ TCL_COMPILE_STATS similarly must be absent (not =0) for release performance.

Approach

• Tiered -dbg suffix on artifact names (exact tier map to be settled during implementation; working sketch: dbg1 = tcl::test + assertions (NDEBUG off, Debug optimize), dbg2 = dbg1 + TCL_MEM_DEBUG (memory command), deeper tiers (TCL_COMPILE_DEBUG) only if useful). Suffix trails the runtime name so release names stay canonical.
• tcl::test wiring: compile the C test sources and register so package require tcl::test works in the static shell (static-package registration or shipped loadable — settled at implementation; win/tclWinTest.c included on windows).
• Constrained-test runs reuse the G-107-generalized tools/test_gate.tcl in -mode record with distinct artifact names (e.g. tclcore-dbg1.summary/.log); never part of the default gate composite; a run that produces no totals still fails its step (G-107 semantics).
• Kit family debug members follow G-103's family definition (achieved 2026-07-22 - see goals/archive/G-103-runtime-kit-family.md); this goal only requires the feasibility outcome plus naming convention (-dbg) — full family production landed under G-103 (kit-family/kit-family-artifacts suite steps) - debug members extend that settled shape.
• Debug tiers are opt-in build invocations (-D flags / named steps), not new copy-and-tweak suite trees, unless implementation shows a variant tree is cleaner (sources.config precedent).

Notes

• G-100 (archived) recorded a census-hygiene finding this goal's recorded test runs depend on: TCL<major>_<minor>_TM_PATH env vars seed tm.tcl's module roots and were NOT part of the suite scrub list, so a suite shell can silently prefer machine/repo tm modules over what the suite installed. Fixed for suite_tcl86; suite_tcl90 still has the exposure via TCL9_0_TM_PATH - see goals/archive/G-100-suite-tcl86-tk-tcllib.md.
• G-104 (archived) recorded this goal as a surface consumer: 'make.tcl buildsuite build' forwards driver args (-steps/-zigargs) untouched and list/info read the sources.config self-description records, so the -dbg debug variants ride the surface and contract automatically with no make.tcl edits - see goals/archive/G-104-maketcl-buildsuite-surface.md.
• Release census reference: gate runs from G-098 (achieved 2026-07-20) / G-102 (achieved 2026-07-21, archived), 66,350 total / ~11,435 skipped; per-constraint guarded-line counts recorded in the drafting conversation (testchannel ~213, testdstring ~46, testsetplatform ~29, testobj ~28, testchmod ~36, testevalex ~18, testfilehandler ~22, ...).
• Built-in tcltest constraints (knownBug, nonPortable, extensive, userInteraction) and platform (unix*) skips remain skipped — this goal targets the C-test-command family, not those.
• Debug/memdebug shells are markedly slower; wall-clock of the recorded run is expected to exceed the release gate's.
• 2026-07-21: drafted and approved as-is from the build-info + constraint-skip analysis discussion.
• G-107 (achieved - see goals/archive/G-107-buildsuite-library-tests.md) landed the tools/test_gate.tcl generalization this goal's constrained-test runs reuse: -mode record, -summaryfile/-library evidence summaries, and the no-totals-fails-in-every-mode semantics. It also added the -notfiles engine option + -Dtestnotfiles- recipe knob (excluding whole test FILES that cannot run in a context) - directly reusable if a debug-tier run needs to exclude problem files. The recipe's LibSuite pattern (per-library step + policy/testargs/notfiles options) is the shape a tclcore-dbg record step slots into.
• G-105 relationship (recorded 2026-07-24 after overlap review): debug members join the family x target matrix - the -dbg tier suffix composes with -target as a dimension sibling, not a separate suite tree.
• G-117 relationship (achieved 2026-07-24 - see goals/archive/G-117-self-describing-runtimes.md): debug-tier artifacts carry the same schema v1 record; the -dbg tier distinction belongs to the artifact-name/variant fields family_check already probes, not new schema.
• G-116 relationship: its static crypto + tls battery enlarges the TCL_MEM_DEBUG all-or-nothing rebuild set this goal's kit-family feasibility item must resolve.