Proposal: cross-platform source-level debugging for native, embedded, WASI, and browser WebAssembly

[cpunion]

Summary

Provide source-level debugging across native, embedded, WASI and browser targets through shared debug artifacts and a versioned LLGo runtime schema, with platform-specific execution-control adapters.

The focused native LLDB proposal remains #2154. This umbrella owns debug-artifact packaging, the common contract across consumers, the llgo debug entry point and platform acceptance.

This plan was revised on 2026-10-01 after auditing current main at f06143ba2aac3e1658ddeecdf0ed69e1eebfe1f7. Integration is consolidated into four contributions, all rooted in current main. Old fork branches are source material; their complete historical commit chains are not prerequisites.

Architecture and compatibility contracts

Keep three layers distinct:

1. Compiler and artifacts: valid DWARF locations/scopes/types, executable identity, optional external DWARF, and independent runtime pclntab data.
2. Execution control: native LLDB/GDB, embedded remote probes/emulators, browser DevTools, or a runtime's supported Wasm guest-debug protocol.
3. Runtime presentation: versioned adapters for LLGo strings, slices, interfaces, functions, closures, maps, channels and supported goroutine/thread views.

Native compile units retain DW_LANG_C for stock-debugger interoperability and DW_AT_producer = LLGo. This does not introduce a Go-language LLDB fork or a general Go expression evaluator. The canonical debugger schema and native/Wasm records identify target size, byte order, ABI and runtime-layout versions. Unsupported records disable LLGo presentation with a clear explanation while preserving ordinary raw debugging.

Port the schema to the current single C ABI and runtime layouts. Removed none/cfunc/allfunc modes and the old module path must not become new compatibility obligations. Share schema and fixtures across LLDB/GDB/browser consumers; do not force them to share implementation language or private APIs.

Debug artifacts and defaults

Native macOS, Linux and Windows builds follow the platform toolchain's default DWARF packaging. Retention policy (-w) is separate from physical placement: this proposal does not require native DWARF embedding, extraction, standalone dSYM/debug-file generation, or an additional packaging acceptance gate. Explicit embedded/external packaging applies to Wasm; embedded devices retain the host debug ELF and separate deployment image. These rules follow the target, independently of the build-host OS.

Mode	Contract
embedded	Retain DWARF in the Wasm module; native use only requests preservation with platform-default packaging
external	Publish a debugger-owned Wasm sidecar paired with the deployed module
host	Retain the linked debug ELF on the host and derive separate flash/deployment bytes
none	Omit DWARF according to the typed build policy

The intended flag is -debug-artifact=embedded|external|host|none. Unsupported target/mode combinations must fail explicitly. Keep this separate from pclntab's runtime loading and packaging: external DWARF is read by a debugger, not by the running LLGo program.

Go -w controls DWARF, and -s implies -w unless explicitly overridden by -w=false. The native default-DWARF correction belongs to #2142. This consolidation does not turn ordinary Wasm/embedded production builds into debug builds. llgo debug explicitly requests retained debug information and defaults to O0 unless the user selects another supported optimization level.

Embedded debug sections remain host-side non-loadable data. Producing a debug ELF must not alter the corresponding flashed .bin/.hex/.uf2 bytes. Artifact reporting distinguishes executable, debug, deployment and runtime-symbolization roles and reports actual file sizes.

For Wasm, publish external DWARF with standard external_debug_info, verified module identity, URL-safe paths and atomic publication/cleanup. Validate the final artifact after all post-link transformations. Use the supported patched Binaryen build baseline from #2632/#2652; do not reintroduce a temporary, separate Binaryen pin or treat the already-fixed Asyncify DWARF issue as a new prerequisite.

Current main versus staged implementation

Area	Main status	Remaining work
Typed Go flags and native pclntab modes	#2113 and #2120 merged	Keep their metadata classes independent
Native DWARF and stock LLDB baseline	#2141, #2143, #2211 and #2240 merged; newer synthetic-location fixes in #2530	Implemented and locally validated in #2142; review/CI/integration remain
Windows debugger qualification	#2465 merged	Preserve current supported configurations
Native runtime traceback diagnostics	#2675 merged	Debugger-specific goroutine presentation is still separate work
Final Wasm Go/C++ DWARF	#2662 and #2697 merged	External artifacts and interactive frontend acceptance
Full common schema and advanced LLDB/GDB values	Not merged	Implemented and locally validated in #2712; review/CI/integration remain
Typed debug artifacts, embedded remote and session CLI	Not merged	Implemented and locally validated in #2269, stacked on #2712
Browser frontend and WASI session capability reporting	Not merged	Implemented and locally validated in #2713, stacked on #2269; current W32 interactive WASI sessions remain unavailable

An issue being closed, a fork test passing, and a fix being merged are different facts. In particular, closed #2115/#2119 do not substitute for integrating and revalidating #2157/#2202. The old Wasm prerequisite list (#2192/#2197 and related scheduler/GC branches) is retired in favor of current main's implementation.

Four-contribution delivery plan

Contribution	Integration target and sources	Acceptance owned by the contribution
Native DWARF correctness and defaults	#2142, head 08d0aef2e, implemented and ready for review; directly based on main	Parameters/locals, current C ABI homes, source stepping/stacks, cold/warm Darwin debug maps, pclntab line precision, native default/explicit -w, fault/inline-frame acceptance
Common debugger ABI and runtime presentation	#2712, head 316408b1c, implemented and ready for review; directly based on main	Schema v1/runtime layout v2, real LLDB/GDB value fixtures, native traceback-registry goroutine/thread views, unknown-schema fallback
Debug artifacts, session entry point and embedded remote	#2269, head 735510143, implemented and ready for review; stacked on #2712	Typed artifact policy, size/identity reporting, sidecar lifecycle, llgo debug, real QEMU remote debugging, unchanged flash bytes and 12-case Wasm artifact matrix
Wasm debug frontend and capability reporting	#2713, head b4d3f52dd, implemented and ready for review; stacked on #2269	Browser source/variable/remapping/sidecar sessions using actual Emscripten glue; explicit rejection of unavailable current-W32 WASI interactive sessions

The concrete dependency chain is #2712 → #2269 → #2713. #2142 is independent and can be reviewed in parallel. All branches are rooted in main f06143ba2; the stacked contributions intentionally include their unmerged prerequisites. Artifact/session integration consumes the common schema/adapter interfaces, and the Wasm frontend consumes the artifacts and session entry point. The compiler fixes are validated together before claiming completion, but do not recreate the old artificial sixteen-PR chain.

Distribute the acceptance from cpunion#138 into the corresponding functional contributions. Do not create separate documentation/test-only PRs for this consolidation. cpunion#139 is closed and is not a dependency; extract only the still-relevant work from #140. Existing merged functionality must not be duplicated.

Retired contributions

The following 15 superseded PRs in cpunion/llgo are closed with replacement links; their branches are retained, including the branch reused by #2269. Closure means the old contribution is retired, not that its replacement is merged.

Old fork PRs	Current destination
cpunion#99, cpunion#101, cpunion#103, cpunion#106	#2712
cpunion#120, cpunion#130	#2712 and #2269
cpunion#108, cpunion#112, cpunion#114, cpunion#126, cpunion#131	#2269
cpunion#137	#2713
cpunion#138, cpunion#140	Relevant acceptance is distributed across the four contributions; hardware and later runtime capability gaps remain explicit below
cpunion#135	Retired Wasmtime prototype; current W32 host requirements are not supported by the tested official CLI, as detailed below

The upstream PRs #2235, #2148, #2157 and #2202 are covered by #2142. They are no longer dependencies; closure remains a separate maintainer action.

Platform capabilities and staged scope

Platform	Initial integrated capability	Required evidence / limits
Native Darwin/Linux/Windows	Stock LLDB; schema-driven runtime views; GDB where qualified	Record exact tool/platform configurations; preserve raw-debugger fallback
Embedded	Host debug ELF plus deployment artifact; GDB Remote through configured server/emulator; compatible LLDB remote use	Real QEMU source breakpoint/locals/globals/backtrace; record physical-probe results separately and do not infer them from emulator success
Browser	Chrome Language Extension, final-module source mapping/scopes/variables, embedded/external DWARF and source remapping	Real browser fixtures on current Memory32/Memory64 outputs; state any worker/goroutine limitations explicitly
WASI	Final DWARF/artifact validation and execution under WAMR; no qualified interactive source-debug session for current W32 yet	WAMR pthread remains the default execution runtime. Official Wasmtime CLI 48.0.1 cannot instantiate the current threaded artifact; the command must report this capability gap

The official Wasmtime CLI 48.0.1 was tested against a freshly built current W32 module. Wasmtime removed WASI threads starting in version 47 (upstream removal); its 48.0.1 CLI source rejects the threads option. In this round, -Sthreads=y reports that the flag is no longer supported. The W32 artifact imports shared env.memory, wasi.thread-spawn and env.pthread_exit; running it with -Wexceptions=y fails because env.memory is undefined.

Therefore the old cpunion#135 Wasmtime session cannot be counted as a working current-W32 frontend. The earlier shared-memory inspection issue bytecodealliance/wasmtime#14062 is not the only blocker: the tested official CLI cannot instantiate this profile. This is a statement about the tested CLI and artifact, not a claim that a future custom host adapter is impossible.

Do not restore the obsolete single-threaded profile, inject fake thread/memory imports, or silently change the runtime contract to obtain a debugger demo. Report the missing capability explicitly. Full WAMR source debugging remains the second-stage work below.

The following remain explicit second-stage, unfinished work:

• Qualify and integrate a complete WAMR source-debug backend against LLGo's current pthread/shared-memory/EH profile.
• WASI shared-memory heap/global inspection and the runtime formatters that depend on it.
• Complete Wasm multi-worker/goroutine stack reconstruction and unified runtime views, including suspended stackless goroutines where applicable.

These capability gates must not block independent native, embedded or browser work. They also must not disappear from the proposal or be counted as completed merely because its first delivery stage lands.

Current validation evidence (2026-10-01)

Results below are from the current contribution series; subsequent changes received focused regression checks. None of the four published contributions is merged into main yet; historical August fork results are not reused as current passes.

Contribution/configuration	Observed result
#2142, macOS/arm64, Go 1.27.0, LLVM 22.1.8, Apple LLDB 2100	Full SSA/CL/cltest; C ABI home regressions; final DWARF O0/O2; default/explicit policy; Darwin cold/warm debug maps and runtime line precision passed
#2142, interactive native acceptance	241 LLDB main assertions and 3 mixed Go/C assertions passed, plus marker fallbacks, exact panic/divide/nil caller locations, O2 inline frames and step-over
#2712, macOS/arm64, Apple LLDB 2100	276/276 runtime/value/goroutine assertions, 3/3 mixed Go/C assertions and record fallback tests passed
#2712, Linux/arm64, LLVM 22 and GDB	Advanced values, goroutine enumeration/backtraces, selected-thread restoration and unsupported-record fallbacks passed
#2269, Cortex-M QEMU, GDB 17.2 and Apple LLDB	Real source breakpoints, parameters, locals, aggregates, globals and frames passed; owned debugger/server cleanup passed; debug and stripped ELF produce identical flash bytes; GC-linked debug ELF passes llvm-dwarfdump --verify
#2269, J32/J64/W32 × O0/O2 × embedded/external	All 12 artifact cases passed final DWARF verification, Go/C++ source resolution and real Node/WAMR execution. External pairs passed module identity and byte-identical standard-section checks
#2713, Chrome for Testing 152, J32/J64 × embedded/external	All four interactive cases passed a real C++ source breakpoint, cpp_local=21 from paused Wasm through the installed extension, Go completion output, source/index matching and no-extension fallback
#2713, actual default-output CLI builds	-target=wasm, raw GOOS=js GOARCH=wasm and -target=emscripten-memory64 each passed fake-browser HTTP inspection of the actual Emscripten host, module, filesystem host, DWARF index and 4/4/8-byte pointer records; owned profile/server cleanup passed
Windows	Existing complete LLDB qualification passes x64/x86/ARM64 with MSVC and MinGW. The new GDB capability matrix and its upstream unwind limits are recorded below.
Physical hardware	Physical-probe execution was not performed

The 12 Wasm cases verify artifacts and execution; they do not establish browser interactive sessions, WASI guest-debug sessions, or Wasm goroutine reconstruction. The separate four-case browser evidence above qualifies #2713; it does not establish WASI guest-debug sessions or Wasm goroutine reconstruction. An Emscripten browser runtime may remain alive after Go main returns, so these tests check actual completion output without inventing a process exit. Broader optimization/tool/platform qualification remains an explicit gate; local combined integration is recorded below.

Current review and CI status

Published heads: #2142 08d0aef2e, #2712 316408b1c, #2269 735510143, #2713 b4d3f52dd. All remain contributions, not merged delivery. The four new #2142 and five new #2712 review threads have been addressed and replied to. The previous #2142 and #2712 heads passed all applicable PR checks; fresh CI is running after the review fixes and dependent restack.

The required acceptance distinguishes complete native runtime inspection from narrower, working debugger capabilities:

Target / host	LLDB	GDB
Native Linux x64	Complete runtime/value/worker-stack CI	Values/registry plus strict complete-worker CI
Native Linux arm64	Locally qualified	Both acceptance levels locally qualified
Native macOS arm64	Complete runtime acceptance	Native process backend unavailable; remote embedded sessions work
Native macOS Intel	Complete runtime acceptance	Values, three-thread mapping, main stack and fallback checks; blocked-worker unwind remains unavailable
Native Windows x64/x86, MSVC and MinGW	Complete runtime acceptance in all four configurations	Both levels pass in all four configurations
Native Windows ARM64, MSVC and MinGW	Complete runtime acceptance	Basic values/registry/main-stack acceptance passes both ABIs; complete-worker unwind remains limited by stock GDB 18 PAC handling
Embedded Cortex-M3, Linux x64/macOS arm64/Windows x64 hosts	Real preloaded and reset/download/reset QEMU sessions	Same real sessions, including actual image writes

Intel GDB's dyld image-info ABI limit reproduces with a plain C pthread program. Windows ARM64 GDB truncates stacks at PAC-signed system return addresses. The strict complete-worker test is retained and remains required on supported platforms; neither restricted platform is counted as complete GDB runtime support. No patched GDB is bundled. Broader MCU architectures require their own target qualification; no physical-probe execution is claimed.

Evidence: Intel LLDB full / GDB basic, Windows GDB matrix, Linux/Windows embedded matrix, Windows LLDB launcher fix and successful download/session rerun. The last fix configures Python only in LLDB child processes, leaving the host Python debug-server process unchanged.

The four contributions merge without conflicts. After the review fixes, their combined tree passes eight debugger/ABI/browser/SSA Go packages, changed workflow syntax checks, the native panic/inline/O2 mutable-aggregate acceptance, and LLDB runtime acceptance (293 assertions plus 3 mixed Go/C assertions). Native registry retention also passes actual macOS and Linux ARM64 LTO/section-GC checks. The dedicated panic/inline suite remains qualified on Linux/macOS, separately from Windows runtime LLDB and PCLN coverage. Browser/WASI capability limits below are unchanged; native or QEMU passes do not imply Wasm source-debugger or worker-stack support.

Completion and evidence

• Shared flag/pclntab foundation, native LLDB baseline and final Wasm DWARF are in main.
• Publish the four consolidated contributions rooted in current main, with accurate dependencies and no duplicate historical chains; all are ready for review, not merged.
• Port the canonical schema/runtime views and validate the recorded Darwin/Linux configurations in debug: unify runtime schema and LLDB/GDB views #2712; the PR is not merged.
• Implement and locally validate typed artifacts, embedded remote and the session CLI in debug: unify artifacts and native/embedded sessions #2269; the PR is not merged.
• Complete review/CI, integrate the contributions together and merge them upstream.
• Publish and locally qualify browser/Wasm frontend debug: add browser DWARF sessions for current Wasm profiles #2713, including explicit rejection of unsupported current-W32 WASI sessions; the PR is not merged.
• Record compiler/runtime/debugger/browser versions and the exact tested configurations, including optimized-out values, source identities and debug/deployed sizes.
• Retain physical-probe and second-stage capability gaps as unfinished until direct evidence exists.

Every PR carries its meaningful acceptance tests and truthful results. Historical fork CI is useful provenance, not a current-main pass. This umbrella remains open while its agreed later capabilities are unfinished; #2154 may complete independently once its focused native scope is merged and validated.

Compact nil-store panic metadata (#2406) and general binary-size optimization (#2679) remain separate workstreams. They are not prerequisites for this four-PR debug integration.

Acceptance test layout

Standalone native, runtime-adapter, embedded and hardware acceptance lives under test/debug/{native,runtime,embedded,hardware}. Existing fixture modules are preserved; package-private tests stay with their implementation. User documentation is in doc/debugging.md. Both debuggers use real binaries, strict source/value assertions and explicit capability boundaries. QEMU results do not establish physical-board qualification.

Current-head full PR CI remains in progress. Local and focused integration results above are separate from completion of that matrix; no coverage threshold or assertion has been relaxed.