# 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-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.