From 5c19f51a4d405b5974405e47490e20f6bf2c4c39 Mon Sep 17 00:00:00 2001 From: Hojun-Cho Date: Wed, 12 Aug 2026 15:18:54 +0900 Subject: [PATCH] docs: record package library-root parity --- docs/build-system.md | 60 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 56 insertions(+), 4 deletions(-) diff --git a/docs/build-system.md b/docs/build-system.md index 9d819e58..ab81810e 100644 --- a/docs/build-system.md +++ b/docs/build-system.md @@ -2654,10 +2654,11 @@ limit; the dynamically sized WWstage scanner differs. There is no regression test for this stage divergence. Compiler, assembler, and linker launches now use structured argument vectors in both stages. Both drivers honor exact executable paths in `WW_W6C`, `WW_W6A`, and `WW_W6L` and otherwise select their -stage-specific sibling tools. Cstage additionally honors `WW_LIB` and -source-library fallbacks; the self-hosted driver still uses relative source and -runtime libraries. The two implementations remain parallel production -algorithms rather than one protocol implementation. +stage-specific sibling tools. Both drivers distinguish the package-source root +selected by `WW_SRCLIB` from the runtime-artifact root selected by `WW_LIB`, and +apply the same empty-value and repository/install fallbacks. The two +implementations remain parallel production algorithms rather than one protocol +implementation. Build and test disagree about source symlinks. External package tests are built from a generated single-file root plus `-I`; an external import of a multi-file @@ -3024,6 +3025,57 @@ builder, while package loading and action construction remain separate WW adopts that exact-tool boundary without adding a command schema, generalized action graph, scheduler, manifest, cache protocol, or package-manager behavior. +### 11.9 Implemented package and runtime library-root parity slice + +Cstage and WWstage now apply the same two-root contract. A nonempty +`WW_SRCLIB` selects the toolchain package-source search root. It is appended +after the entry directory and explicit `-I` roots for every package context, +and compiler-generated test support is resolved from that toolchain root rather +than from a user package that happens to have the same name. A nonempty +`WW_LIB` independently selects runtime artifacts; executable and test links use +`$WW_LIB/libwwrt.a`. If that archive is absent, both stages pass their sibling +`start.o` and `syscall.o` runtime objects instead. Missing and explicitly empty +values use the same deterministic fallbacks in both stages. + +Bare logical build and run targets search the current directory, explicit +`-I` roots, then one selected library root. That last root is a nonempty +`WW_SRCLIB`, else a nonempty `WW_LIB`, else an existing +`/../../lib`, else an existing `./lib`, else +`/../lib`. Once a target is resolved, its import graph retains the +ordinary entry-directory-first context and its separate source-root policy: +without `WW_SRCLIB`, that policy prefers the repository and `./lib` source +trees before falling back to the runtime root. This preserves Cstage's +existing distinction between locating a requested package and selecting the +toolchain source tree used by that package's imports. + +The variables select local directories only. They do not add manifests, +dependency declarations, network lookup, package-manager behavior, or a second +graph: source `import` declarations still create every language edge, resolved +directories still intern to canonical package identities, compilers still +receive only direct `.wwi` exports, and final links still receive the complete +reachable `.a` closure. Directory tests continue to build same-package and +external-package variants through the same command-scoped package universe. + +Repository-native coverage uses distinct source and runtime roots whose paths +contain spaces, resolves a bare logical target found only through `WW_SRCLIB`, +places a same-named decoy under `WW_LIB`, records exact compiler, assembler, and +linker arguments, inspects `.unit.ww`, `.wwi`, `.a`, diagnostics, binaries, and +runtime results, and compares both stages. It separately exercises the runtime +object fallback and explicitly empty variables. The package-test observer copies +the toolchain source library to a selected root, marks the compiler-generated +test-support source, and proves that both the marker and the selected runtime +archive reach real same-package test builds through the coordinator. + +The ownership boundary follows the pinned Go 1.26.5 implementation: source +headers supply imports in +[`go/build/read.go`](https://go.googlesource.com/go/+/refs/tags/go1.26.5/src/go/build/read.go#272), +the loader canonicalizes and reuses packages in +[`cmd/go/internal/load/pkg.go`](https://go.googlesource.com/go/+/refs/tags/go1.26.5/src/cmd/go/internal/load/pkg.go#633), +tests remain real package variants in +[`cmd/go/internal/load/test.go`](https://go.googlesource.com/go/+/refs/tags/go1.26.5/src/cmd/go/internal/load/test.go#85), +and direct compile dependencies are expanded separately for linking in +[`cmd/go/internal/work/action.go`](https://go.googlesource.com/go/+/refs/tags/go1.26.5/src/cmd/go/internal/work/action.go#628). + ## 12. Candidate architectures and hard-gate decision Five candidates were developed as coherent systems, not as feature bins.