From 649e747c120e68b48c79a4bd4bbbed7533efeba3 Mon Sep 17 00:00:00 2001 From: Cole Speelman Date: Wed, 12 Aug 2026 21:17:38 -0400 Subject: [PATCH] docs: teach the Beta 2 compiler path Signed-off-by: Cole Speelman --- GENERATED_CODE.md | 6 ++++-- README.md | 13 +++++++------ scripts/verify.ps1 | 18 ++++++++++-------- scripts/verify.sh | 15 ++++++++------- 4 files changed, 29 insertions(+), 23 deletions(-) diff --git a/GENERATED_CODE.md b/GENERATED_CODE.md index a4f3443..64f85d9 100644 --- a/GENERATED_CODE.md +++ b/GENERATED_CODE.md @@ -3,8 +3,10 @@ # Generated code Every `*.sando.go` file is an owned output of the neighboring `*.sando` source. -The exact generator is `himesan v1.0.0-beta.1`. Commit both files so production -builds need only ordinary Go and the small `sando` runtime. +The committed neighbors were produced by `himesan v1.0.0-beta.1` and remain +byte-current under `himesan v1.0.0-beta.2`; Beta 2 intentionally preserves an +honest producer marker when generated semantics are unchanged. Commit both +files so production builds need only ordinary Go and the small `sando` runtime. Never hand-edit a generated neighbor. Run `himesan generate internal/views`, review the deterministic diff, and use `himesan check internal/views` in local diff --git a/README.md b/README.md index 39f134b..4f270b0 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ The starter demonstrates the boundary plainly: time through `Server-Timing`. - Production imports the Apache-2.0 `sando` runtime, not the compiler. -## Walk the path with Beta 1 +## Walk the path with the Beta 1 runtime and Beta 2 compiler Install Go 1.25 or newer, then resolve the tiny runtime before installing the immutable classroom compiler: @@ -34,7 +34,7 @@ immutable classroom compiler: git clone https://gitea.speelman.ca/gamertan/sandwich-hime-tutorial.git cd sandwich-hime-tutorial GOWORK=off go mod download gamertan.com/sandwich-hime/sando@v1.0.0-beta.1 -go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-beta.1 +go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-beta.2 ./scripts/verify.sh GOWORK=off go run ./cmd/site ``` @@ -46,7 +46,7 @@ git clone https://gitea.speelman.ca/gamertan/sandwich-hime-tutorial.git Set-Location sandwich-hime-tutorial $env:GOWORK = "off" go mod download gamertan.com/sandwich-hime/sando@v1.0.0-beta.1 -go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-beta.1 +go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-beta.2 .\scripts\verify.ps1 go run ./cmd/site ``` @@ -55,8 +55,8 @@ Make sure Go's install directory—normally `$(go env GOPATH)/bin`—is on `PATH`, or set `HIMESAN_BIN` to the full compiler path before running either verifier. The starter deliberately runs with `GOWORK=off`: it proves the application resolves the published Apache-2.0 runtime rather than a neighboring -development checkout. The verification scripts also reject any compiler or -runtime version other than `v1.0.0-beta.1`. +development checkout. The verification scripts require compiler +`v1.0.0-beta.2` and runtime `v1.0.0-beta.1` exactly. If an earlier compiler-first attempt reports that the parent module does not contain `gamertan.com/sandwich-hime/sando`, repair only that module selection: @@ -69,7 +69,8 @@ GOWORK=off go get gamertan.com/sandwich-hime/sando@v1.0.0-beta.1 Then run the verifier again. You do not need to clear your whole Go module cache. -Beta 1 is intended for classrooms, learning, prototypes, and evaluation. Its +The Beta 2 compiler and Beta 1 runtime are intended for classrooms, learning, +prototypes, and evaluation. Their interfaces may still change before final v1. Linux and Windows have been maintainer-tested; macOS is provisional while native maintainer testing is pending. Useful Mac compatibility reports are welcome on canonical Gitea. diff --git a/scripts/verify.ps1 b/scripts/verify.ps1 index 84f4f0f..91ac419 100644 --- a/scripts/verify.ps1 +++ b/scripts/verify.ps1 @@ -11,9 +11,10 @@ Set-Location $repoRoot $env:GOWORK = "off" $himesan = if ($env:HIMESAN_BIN) { $env:HIMESAN_BIN } else { "himesan" } -$expectedVersion = "v1.0.0-beta.1" +$expectedCompilerVersion = "v1.0.0-beta.2" +$expectedRuntimeVersion = "v1.0.0-beta.1" if (-not (Get-Command $himesan -ErrorAction SilentlyContinue)) { - throw "himesan was not found; install v1.0.0-beta.1 or set HIMESAN_BIN" + throw "himesan was not found; install v1.0.0-beta.2 or set HIMESAN_BIN" } function Assert-LastExitCode([string]$Step) { @@ -32,19 +33,20 @@ function Get-GeneratedDigest { return ($lines -join "`n") } -$versionLine = (& $himesan version | Select-Object -First 1) +$versionOutput = & $himesan version Assert-LastExitCode "himesan version" +$versionLine = ($versionOutput | Select-Object -First 1) if ($versionLine -notmatch '^himesan ([^ ]+) ') { throw "could not parse himesan version output: $versionLine" } -if ($Matches[1] -ne $expectedVersion) { - throw "himesan version is $($Matches[1]); expected $expectedVersion" +if ($Matches[1] -ne $expectedCompilerVersion) { + throw "himesan version is $($Matches[1]); expected $expectedCompilerVersion" } $runtimeVersion = (go list -m -f '{{.Version}}' gamertan.com/sandwich-hime/sando | Select-Object -First 1) Assert-LastExitCode "sando runtime version" -if ($runtimeVersion -ne $expectedVersion) { - throw "sando runtime version is $runtimeVersion; expected $expectedVersion" +if ($runtimeVersion -ne $expectedRuntimeVersion) { + throw "sando runtime version is $runtimeVersion; expected $expectedRuntimeVersion" } & $himesan check internal/views @@ -86,4 +88,4 @@ if ($dependencies | Where-Object { $_ -match '^gamertan\.com/sandwich-hime$|^gam throw "production dependency graph contains the Sandwich Hime compiler" } -Write-Output "verified Beta 1 identity, deterministic generation, tests, vet, build, and runtime-only production dependencies" +Write-Output "verified Beta 2 compiler, Beta 1 runtime, deterministic generation, tests, vet, build, and runtime-only production dependencies" diff --git a/scripts/verify.sh b/scripts/verify.sh index bf5d9fb..1d236e4 100755 --- a/scripts/verify.sh +++ b/scripts/verify.sh @@ -7,23 +7,24 @@ repo_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) cd "$repo_root" himesan_bin=${HIMESAN_BIN:-himesan} -expected_version=v1.0.0-beta.1 +expected_compiler_version=v1.0.0-beta.2 +expected_runtime_version=v1.0.0-beta.1 if ! command -v "$himesan_bin" >/dev/null 2>&1; then - echo "himesan was not found; install v1.0.0-beta.1 or set HIMESAN_BIN" >&2 + echo "himesan was not found; install v1.0.0-beta.2 or set HIMESAN_BIN" >&2 exit 1 fi export GOWORK=off actual_version=$("$himesan_bin" version | awk 'NR == 1 { print $2 }') -if [[ "$actual_version" != "$expected_version" ]]; then - echo "himesan version is $actual_version; expected $expected_version" >&2 +if [[ "$actual_version" != "$expected_compiler_version" ]]; then + echo "himesan version is $actual_version; expected $expected_compiler_version" >&2 exit 1 fi runtime_version=$(go list -m -f '{{.Version}}' gamertan.com/sandwich-hime/sando) -if [[ "$runtime_version" != "$expected_version" ]]; then - echo "sando runtime version is $runtime_version; expected $expected_version" >&2 +if [[ "$runtime_version" != "$expected_runtime_version" ]]; then + echo "sando runtime version is $runtime_version; expected $expected_runtime_version" >&2 exit 1 fi @@ -64,4 +65,4 @@ if grep -Eq '^gamertan\.com/sandwich-hime$|^gamertan\.com/sandwich-hime/(cmd|int exit 1 fi -echo "verified Beta 1 identity, deterministic generation, tests, vet, build, and runtime-only production dependencies" +echo "verified Beta 2 compiler, Beta 1 runtime, deterministic generation, tests, vet, build, and runtime-only production dependencies"