One module for Keel, Gio and typesetting
Status: implemented and locally validated; see the validation record.
Production release publication and desktop CGO migration remain pending.
The user's request to maintain one
go.mod supersedes the former separate-fork delivery design and the instruction
to preserve upstream module paths. Here, “typing” means typesetting
(github.com/go-text/typesetting). This step merges modules; desktop CGO removal
remains subsequent work described in the desktop plan.
Target structure
github.com/dyike/keel/
├── go.mod # the only maintained module manifest
├── go.sum
├── ui/
├── native/
├── cmd/
├── gio/ # ordinary packages, no go.mod/go.sum
├── typesetting/ # ordinary packages, no go.mod/go.sum
└── third_party/ # attribution and patch logs only
The libraries live in the root-level gio/ and typesetting/ directories. Preserve
licenses, attribution, patch history and upstream source style. Both libraries
ship inside Keel's module zip and share its version.
No nested releases, fork lock manifest, upstream replacement mode or application
replace is needed. No go.work, symlinks, replacement shim modules or duplicate
copies are introduced. External dependencies still retain their own modules;
one manifest refers to the source maintained in this repository.
| Former import prefix | Current import prefix |
|---|---|
gioui.org (Gio root module packages) |
github.com/dyike/keel/gio |
github.com/go-text/typesetting |
github.com/dyike/keel/typesetting |
github.com/dyike/keel/third_party/gio (unpublished intermediate path) |
github.com/dyike/keel/gio |
github.com/dyike/keel/third_party/typesetting (unpublished intermediate path) |
github.com/dyike/keel/typesetting |
gioui.org/shader is a separate external module and stays unchanged, including
gioui.org/shader/gio. Do not rewrite every gioui.org/ string indiscriminately.
The currently used shader packages do not require a second Gio implementation;
shader/piet has separate gioui.org/cpu imports and must not be pulled in by
an overbroad rewrite. Verify package graphs for every supported target/tag.
Compatibility and architectural boundaries
Changing package paths changes the identity of named Go types. Preserve
component names, behavior and method shapes, but do not promise full source
compatibility to applications directly importing upstream Gio/go-text. For
example core.C/core.D alias the newly located layout types; an application
with a Layout(gioui.org/layout.Context) method must migrate that import.
Publish the two-prefix migration table and compile an external custom widget
using the new Gio layout/unit/op packages. Third-party upstream Gio widgets
must migrate or be adapted explicitly; no implicit interchangeability or full
compatibility alias layer is part of this change. Old Keel releases stay intact.
Update AGENTS.md, architecture and dependency checks before source migration:
uimay use the appropriate Gio/typesetting packages;nativeand the CLI must still work without importing the GUI, directly or transitively.- Gio may depend on typesetting and its own internals. Typesetting must not
depend on Gio. Neither fork may depend on Keel
ui,native,cmdor its application-level helpers, despite now sharing a module prefix. - Preserve ui/native separation, all existing layer restrictions and opt-in
heavy dependencies. Teach
internal/depsabout the two foundation subtrees explicitly. Do not exempt foundation dependencies from validation. - Go's
internalvisibility still follows directory ancestry. Keep each library's internal hierarchy, and rewrite its own imports consistently.
Implementation sequence
- Capture the baseline. Record the current working tree and build/test
results, including known CGO/MCP failures. Preserve concurrent changes and
the ABI probe in
gio/internal/nativeabi. Source relocation must not absorb a renderer rewrite or claim to fix the existing CGO failure. - Unify dependencies and imports in one coherent change. Merge the dependency requirements from all three manifests into the root, retaining the currently selected versions initially (do not downgrade root x/image/x/sys/x/text). Rewrite Go imports in all source/test/generated files, examples and templates; update import-path comments and generation inputs. Remove both nested go.mod/go.sum files and the root require/replace entries for the two former modules. Run root tidy and review the resulting dependency changes. Preserve build tags, shader contents, native code and runtime behavior.
- Migrate path-bearing tooling. Update
-X gioui.org/app.IDincmd/keel/run.go, tests andscripts/build-ios-hello.sh; audit other linker symbols, package discovery, permission detection, generators and doc examples. Audit strings and native/assembly symbols, not only import declarations. - Simplify scaffold and delivery.
keel newwrites one Keel requirement, then tidy;new -replace <checkout>writes only a Keel replacement. Offline generation with an exact version needs no fork metadata and does no network work; version queries such as latest require cached resolution or an actionable error. Keep transactional generation, failure rollback, path quoting and concurrent-file protection from the current work. Remove the unpublished backend-lock manifest, fork resolver, fork-specificdeps/doctor behavior,-backendselection and their obsolete tests. Retain general doctor checks. Do not auto-edit existing applications' custom replacements; document removing obsolete ones after migrating their imports. No new dependency-manager CLI is needed. Historical separate-module releases use their matching historical CLI. - Update packaging and CI. Complete the packager adaptation below. Rewrite
scripts/check-backend-release.pyas a single-root-module archive fixture; root./...now includes both libraries, so updatescripts/check-desktop-cgo-free.sh, workflows and tests accordingly. Targeted commands usego test ./gio/... ./typesetting/...from root. Convert the old upstream-replace-removal test into a check for no upstream core packages in the application graph. Document and release only the root Keel version, with no nested tags.
Packaging is a required part of the path migration
The installed gioui.org/cmd/gogio@v0.10.0 hardcodes more than app.ID:
build_info.go sets app/internal/log.appID and app.extraArgs;
androidbuild.go discovers gioui.org/app/ and permission prefixes;
iosbuild.go discovers the original app path. Passing one additional linker
flag cannot repair those lookups.
Use a small maintained copy of the required gogio Go packager sources as ordinary
packages at internal/gogio, invoked in-process through a testable
entrypoint by the existing CLI. Retain its license and record its upstream
version/patches in bilingual documentation. Parameterize the Gio package root
and set it to the new path; use it for all link symbols, resource discovery and
permission imports. Keep it independent of UI imports. Merge necessary tool
dependencies into root go.mod. Do not add another module, patch the module cache,
introduce native sources or rewrite platform packaging algorithms. Replace
external gogio invocations in CLI/site scripts with the Keel packaging entrypoint;
cover macOS, Android, iOS and Web outputs and Windows resource behavior. Update
architecture/dependency tables for the helper before adding it.
This adapter is necessary even though mobile CGO removal is deferred: changing Gio paths must not break existing mobile packaging. Keep the separate shader module and iOS shader adapter until their own requirements change. Verify actual app IDs, launch arguments, permissions and resources, not just successful linking.
Acceptance and handoff
- Exactly one maintained go.mod/go.sum pair;
go list -jsonon both relocated package trees reports the root Keel module inModule.Path. The ordinary app's module graph has no required/replacedgioui.orgorgithub.com/go-text/typesettingroot modules; externalgioui.org/shaderis allowed. Scan all platforms/tags for stale core imports, with explicit exceptions for historical/attribution text. - Root formatting, vet, test and race checks include both trees. Windows amd64/arm64 no-cgo builds still pass; native-only cross-builds stay intact. macOS/Linux retain their current toolchain requirements until binding migration. Record pre-existing failures separately; new failures require fixes.
- A file-module-proxy fixture serves the real root archive, including both
former submodules, with a fresh module cache and
GOWORK=off. Generate an external app with only a Keel requirement, then tidy/build without any local replacements. Inspect each fork package'sModule.Pathand files. Also installcmd/keel@<fixture-version>to a temporary GOBIN to verify that removing the root replacements restores normal versioned CLI installation. Real remote installation is a release gate, not a claim that an unpublished version exists. - Compile the custom-widget fixture; exercise default, offline and local scaffold modes (including spaces), preserve generator failure/rollback tests, and validate packaging discovery and new linker symbols on supported targets.
- Compare same-host hello/component screenshots and run real-window fixtures after migration. Package identity changes must not change rendering or lifecycle. No new benchmark suite or CGO migration is necessary to accept this structural change; existing performance patches and tests remain included.
For impl, finish this single-module change before resuming M0/M1/M2/L1/L2 of
the desktop plan. Replace the former D1 delivery work rather than implementing
both approaches. Keep its useful transactional scaffolding tests and the D0/ABI
work. The previous validation report records historical results, not acceptance
of this new architecture. Completion means a real external application receives
both libraries through the single Keel module, with preserved packaging behavior.