gamertan/sandwich-hime-tutorial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: teach the Beta 2 compiler path

Browse Source 
Signed-off-by: Cole Speelman <crspeelman@gmail.com>
This commit is contained in:
gamertan
2026-08-12 21:20:01 -04:00
parent 83fdc9ae9e
commit 649e747c12
4 changed files with 29 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
GENERATED_CODE.md
+4 -2
View File
@@ -3,8 +3,10 @@
# Generated code # Generated code
Every `*.sando.go` file is an owned output of the neighboring `*.sando` source. 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 The committed neighbors were produced by `himesan v1.0.0-beta.1` and remain
builds need only ordinary Go and the small `sando` runtime. 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`, Never hand-edit a generated neighbor. Run `himesan generate internal/views`,
review the deterministic diff, and use `himesan check internal/views` in local review the deterministic diff, and use `himesan check internal/views` in local
README.md
+7 -6
View File
@@ -25,7 +25,7 @@ The starter demonstrates the boundary plainly:
time through `Server-Timing`. time through `Server-Timing`.
- Production imports the Apache-2.0 `sando` runtime, not the compiler. - 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 Install Go 1.25 or newer, then resolve the tiny runtime before installing the
immutable classroom compiler: immutable classroom compiler:
@@ -34,7 +34,7 @@ immutable classroom compiler:
git clone https://gitea.speelman.ca/gamertan/sandwich-hime-tutorial.git git clone https://gitea.speelman.ca/gamertan/sandwich-hime-tutorial.git
cd sandwich-hime-tutorial cd sandwich-hime-tutorial
GOWORK=off go mod download gamertan.com/sandwich-hime/sando@v1.0.0-beta.1 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 ./scripts/verify.sh
GOWORK=off go run ./cmd/site 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 Set-Location sandwich-hime-tutorial
$env:GOWORK = "off" $env:GOWORK = "off"
go mod download gamertan.com/sandwich-hime/sando@v1.0.0-beta.1 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 .\scripts\verify.ps1
go run ./cmd/site 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 `PATH`, or set `HIMESAN_BIN` to the full compiler path before running either
verifier. The starter deliberately runs with `GOWORK=off`: it proves the verifier. The starter deliberately runs with `GOWORK=off`: it proves the
application resolves the published Apache-2.0 runtime rather than a neighboring application resolves the published Apache-2.0 runtime rather than a neighboring
development checkout. The verification scripts also reject any compiler or development checkout. The verification scripts require compiler
runtime version other than `v1.0.0-beta.1`. `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 If an earlier compiler-first attempt reports that the parent module does not
contain `gamertan.com/sandwich-hime/sando`, repair only that module selection: 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 Then run the verifier again. You do not need to clear your whole Go module
cache. 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 interfaces may still change before final v1. Linux and Windows have been
maintainer-tested; macOS is provisional while native maintainer testing is maintainer-tested; macOS is provisional while native maintainer testing is
pending. Useful Mac compatibility reports are welcome on canonical Gitea. pending. Useful Mac compatibility reports are welcome on canonical Gitea.
scripts/verify.ps1
+10 -8
View File
@@ -11,9 +11,10 @@ Set-Location $repoRoot
$env:GOWORK = "off" $env:GOWORK = "off"
$himesan = if ($env:HIMESAN_BIN) { $env:HIMESAN_BIN } else { "himesan" } $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)) { 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) { function Assert-LastExitCode([string]$Step) {
@@ -32,19 +33,20 @@ function Get-GeneratedDigest {
return ($lines -join "`n") return ($lines -join "`n")
} }
$versionLine = (& $himesan version | Select-Object -First 1) $versionOutput = & $himesan version
Assert-LastExitCode "himesan version" Assert-LastExitCode "himesan version"
$versionLine = ($versionOutput | Select-Object -First 1)
if ($versionLine -notmatch '^himesan ([^ ]+) ') { if ($versionLine -notmatch '^himesan ([^ ]+) ') {
throw "could not parse himesan version output: $versionLine" throw "could not parse himesan version output: $versionLine"
} }
if ($Matches[1] -ne $expectedVersion) { if ($Matches[1] -ne $expectedCompilerVersion) {
throw "himesan version is $($Matches[1]); expected $expectedVersion" throw "himesan version is $($Matches[1]); expected $expectedCompilerVersion"
} }
$runtimeVersion = (go list -m -f '{{.Version}}' gamertan.com/sandwich-hime/sando | Select-Object -First 1) $runtimeVersion = (go list -m -f '{{.Version}}' gamertan.com/sandwich-hime/sando | Select-Object -First 1)
Assert-LastExitCode "sando runtime version" Assert-LastExitCode "sando runtime version"
if ($runtimeVersion -ne $expectedVersion) { if ($runtimeVersion -ne $expectedRuntimeVersion) {
throw "sando runtime version is $runtimeVersion; expected $expectedVersion" throw "sando runtime version is $runtimeVersion; expected $expectedRuntimeVersion"
} }
& $himesan check internal/views & $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" 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"
scripts/verify.sh
+8 -7
View File
@@ -7,23 +7,24 @@ repo_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
cd "$repo_root" cd "$repo_root"
himesan_bin=${HIMESAN_BIN:-himesan} 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 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 exit 1
fi fi
export GOWORK=off export GOWORK=off
actual_version=$("$himesan_bin" version | awk 'NR == 1 { print $2 }') actual_version=$("$himesan_bin" version | awk 'NR == 1 { print $2 }')
if [[ "$actual_version" != "$expected_version" ]]; then if [[ "$actual_version" != "$expected_compiler_version" ]]; then
echo "himesan version is $actual_version; expected $expected_version" >&2 echo "himesan version is $actual_version; expected $expected_compiler_version" >&2
exit 1 exit 1
fi fi
runtime_version=$(go list -m -f '{{.Version}}' gamertan.com/sandwich-hime/sando) runtime_version=$(go list -m -f '{{.Version}}' gamertan.com/sandwich-hime/sando)
if [[ "$runtime_version" != "$expected_version" ]]; then if [[ "$runtime_version" != "$expected_runtime_version" ]]; then
echo "sando runtime version is $runtime_version; expected $expected_version" >&2 echo "sando runtime version is $runtime_version; expected $expected_runtime_version" >&2
exit 1 exit 1
fi fi
@@ -64,4 +65,4 @@ if grep -Eq '^gamertan\.com/sandwich-hime$|^gamertan\.com/sandwich-hime/(cmd|int
exit 1 exit 1
fi 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"