mirr
This commit is contained in:
1 parent
f0972f0d5b
commit
cd82f445d3
2 files changed
+167
-201
No files matched your search
@@ -1,218 +1,120 @@
|
|||||||
# OGS Mahjong (`mj`)
|
# OGS applications (`mj`)
|
||||||
|
|
||||||
A macOS SwiftUI app for **OGS Mahjong**, built on the **Dialect v4** declarative
|
Native SwiftUI applications using the Dialect v4 declarative reactive engine.
|
||||||
reactive engine (see the sibling `../dialect` repo — this project is a
|
Version: `2.0.0`. Remote: `https://git.opengamestudio.org/mahjong/mahjong`.
|
||||||
downstream consumer of its code generator).
|
|
||||||
|
|
||||||
Business logic lives in `dialect.yml` (YAML). A generator turns it into
|
## Current status
|
||||||
`game/ver-mac/src/dialect.swift` (the runtime engine + `struct F` field
|
|
||||||
constants + component/should/effect registration). The Swift app shell
|
|
||||||
(`GameApp`/`AppDelegate`) and the SwiftUI views live outside the generated file
|
|
||||||
and talk to the engine through generated functions like `rootSet(...)`.
|
|
||||||
|
|
||||||
Remote: `https://git.opengamestudio.org/mahjong/mahjong` · Version: `2.0.0`
|
- `ogs-blue/` is the active minimal graphics example for macOS and iOS: a solid
|
||||||
|
blue raylib background with a SwiftUI overlay. It has no model/texture/shadow
|
||||||
|
scene; rlgl still creates its default internal GPU resources.
|
||||||
|
- `ogs-mahjong/` contains the macOS Mahjong scaffold and counter-template logic;
|
||||||
|
Mahjong gameplay has not been implemented.
|
||||||
|
- `ogs-chkgfx/` is a companion graphics scaffold with macOS/iOS project files.
|
||||||
|
Older targets can lag behind shared-component changes; verify each target
|
||||||
|
separately before claiming it builds.
|
||||||
|
- The previous `game/ver-mac` and root `dialect.yml` layout is obsolete.
|
||||||
|
|
||||||
> `dialect.yml` is still the "Root / counter" template with a `Render` context
|
## Source layout
|
||||||
> bolted on: the Mahjong game logic has not been written yet. The app shell,
|
|
||||||
> packaging, symlink wiring and the raylib renderer are in place.
|
|
||||||
|
|
||||||
## Structure
|
- `<app>/dialect.yml`: per-application logic; generates
|
||||||
|
`<app>/ver-mac/src/dialect.swift`. Blue iOS links to its macOS generated file.
|
||||||
|
- `components/`: shared source of truth. App `src/` files use relative symlinks;
|
||||||
|
edit real component files and preserve symlink parity.
|
||||||
|
- `components/render/`: shared component/model/constants, plus mirrored `ios/`
|
||||||
|
and `mac/` effects, helpers and native/SwiftUI views. macOS additionally has
|
||||||
|
`renderConstMac.swift` for native pixel-format attributes.
|
||||||
|
- `components/raybri/raybri.h`: declarations plus implementation gated by
|
||||||
|
`RAYBRI_IMPLEMENTATION`; clears blue, renders and shuts down rlgl.
|
||||||
|
- `components/raybri/raybriConst.h`: shared constants with an implementation macro.
|
||||||
|
`components/raybri/mac/raybriAux.h`: macOS OpenGL symbol loader.
|
||||||
|
- `components/egl/egl.h` and `eglConst.h`: EGL state/helpers and configuration,
|
||||||
|
using single-header implementation macros.
|
||||||
|
- `ogs-blue/ver-{mac,ios}/src/Blue.c`: platform C implementation translation units.
|
||||||
|
- `history/gitjs/`: historical JavaScript Mahjong reference, outside the build.
|
||||||
|
`ref/swiftraylib` links to the sibling renderer sample.
|
||||||
|
|
||||||
```
|
## Graphics ownership and platform differences
|
||||||
dialect.yml Single source of truth for the reactive logic.
|
|
||||||
Generates game/ver-mac/src/dialect.swift
|
|
||||||
|
|
||||||
components/ SHARED source-of-truth for all components.
|
Every GPU operation requires its context current on the calling thread.
|
||||||
other/other.swift Shared helpers (otherPrintStderr, otherWriteFile,
|
`rlLoadExtensions` also requires an existing current context; it precedes
|
||||||
otherSetupConsoleLogging, ...)
|
`rlglInit`, not native context creation.
|
||||||
raybri/raybri.h C API of the raylib bridge (raybri_config, raybri_init,
|
|
||||||
raybri_load_model, raybri_resize, raybri_set_rotation,
|
|
||||||
raybri_render, raybri_shutdown); extern "C" guards.
|
|
||||||
raybri/raybri.c Bridge implementation: rlgl scene, shadow pass, shaders.
|
|
||||||
root/root.swift RootComponent (owns DialectController, registers
|
|
||||||
effects + shoulds, sets didSetup on setup())
|
|
||||||
root/rootVM.swift RootVM (ObservableObject / @Published countText)
|
|
||||||
root/mac/view/RootView.swift SwiftUI view: RenderView in a ZStack + UI
|
|
||||||
render/render.swift RenderComponent (controller, effects + shoulds)
|
|
||||||
render/renderVM.swift RenderVM (weak shared; glView, didPrepareGL,
|
|
||||||
pixelSize, startTime, timer)
|
|
||||||
render/renderConst.swift RENDER_CONFIG (raybri_config), RENDER_FPS,
|
|
||||||
RENDER_MODEL_CUBE, RENDER_OPENGL_ATTRS
|
|
||||||
render/renderConstShader.swift RENDER_SHADER_* GLSL sources (GLSL 150)
|
|
||||||
render/renderAux.swift renderDraw(vm), renderPixelSize(view)
|
|
||||||
render/renderEffect.swift renderInit, renderLoadCubeModel,
|
|
||||||
renderStartTimer, renderDeinit
|
|
||||||
render/mac/view/RenderGLView.swift Thin NSOpenGLView: pixel format, callbacks
|
|
||||||
-> renderSet(...), draw -> renderDraw
|
|
||||||
render/mac/view/RenderView.swift NSViewRepresentable wrapper
|
|
||||||
|
|
||||||
game/ver-mac/ macOS app (SPM executable target "ogs-mahjong")
|
macOS uses `NSOpenGLView` (OpenGL 3.2 Core). `renderInit` makes its context
|
||||||
Package.swift SPM manifest (macOS 13+, swift-tools 5.9); C target
|
current, enables VSync, loads extensions with the C loader callback and starts
|
||||||
"RaylibBridge" (path src/raybri, publicHeadersPath ".") +
|
raylib. The timer requests `needsDisplay`; `draw(_:)` forwards to `renderDraw`,
|
||||||
links Homebrew raylib; the Swift target excludes raybri
|
which activates the context, renders and presents via `flushBuffer`.
|
||||||
and gets -Xcc -DGL_SILENCE_DEPRECATION
|
|
||||||
Info.plist Bundle id org.opengamestudio.Mahjong, exec ogs-mahjong
|
|
||||||
Resources/AppIcon.icns App icon
|
|
||||||
Resources/assets/ Bundled glTF assets: cube.gltf (static),
|
|
||||||
cube_texture.png, cube_normal.png
|
|
||||||
src/
|
|
||||||
GameApp.swift @main SwiftUI App entry
|
|
||||||
AppDelegate.swift Creates Render/Root components + VMs, calls setup()
|
|
||||||
dialect.swift GENERATED — do not hand-edit (see chicken-egg below)
|
|
||||||
other/other.swift -> symlink components/other/other.swift
|
|
||||||
raybri/raybri.c -> symlink components/raybri/raybri.c
|
|
||||||
raybri/raybri.h -> symlink components/raybri/raybri.h
|
|
||||||
render/render.swift -> symlink components/render/render.swift
|
|
||||||
render/renderAux.swift -> symlink components/render/renderAux.swift
|
|
||||||
render/renderConst.swift -> symlink components/render/renderConst.swift
|
|
||||||
render/renderConstShader.swift -> symlink .../renderConstShader.swift
|
|
||||||
render/renderEffect.swift -> symlink components/render/renderEffect.swift
|
|
||||||
render/renderVM.swift -> symlink components/render/renderVM.swift
|
|
||||||
render/view/RenderGLView.swift -> symlink components/render/mac/view/...
|
|
||||||
render/view/RenderView.swift -> symlink components/render/mac/view/...
|
|
||||||
root/root.swift -> symlink components/root/root.swift
|
|
||||||
root/rootVM.swift -> symlink components/root/rootVM.swift
|
|
||||||
root/view/RootView.swift -> symlink components/root/mac/view/...
|
|
||||||
|
|
||||||
ref/swiftraylib Symlink to ../../swiftraylib — the raylib/SwiftUI
|
Blue's SPM `RaylibBridge` target compiles `src/Blue.c`, exposes headers in
|
||||||
renderer sample the game will use for 3D rendering.
|
`src/raybri`, and links Homebrew raylib. It does NOT define
|
||||||
|
`RLGL_IMPLEMENTATION`: Homebrew headers omit the `external/glad.h` needed to
|
||||||
|
compile desktop rlgl locally. Swift imports `RaylibBridge`. `RAYLIB_PREFIX`
|
||||||
|
defaults to `/opt/homebrew`; build scripts detect `brew --prefix raylib`.
|
||||||
|
The installed raylib may produce a deployment-target linker warning.
|
||||||
|
|
||||||
util/ Build/run scripts (see Build & Run)
|
On iOS, UIKit owns the view/layer and `RenderGLView.st` owns an `EGLState`.
|
||||||
paths APP_MAC = .build/OGS Mahjong.app
|
Swift effects create EGL/ANGLE state and surface, make the context current,
|
||||||
build-mac generateDialect -> buildMac -> packageMac
|
and initialize raylib. Timer ticks call rendering directly; presentation uses
|
||||||
run-mac runMac
|
`eglSwapBuffers`. Pixel sizes come from view bounds and content scale.
|
||||||
rm-mac-geom Resets saved window geometry
|
Dialect's resize event triggers `renderRecreateSurface`; the macOS helper is
|
||||||
step/ Sourced steps: generateDialect, buildMac,
|
intentionally a no-op. Teardown must stop the timer, activate the context,
|
||||||
packageMac, runMac
|
release rlgl resources, then destroy EGL surface/context/display resources.
|
||||||
|
|
||||||
history/gitjs/ GitJS "Glavred" history + the original JS source of the
|
Blue iOS uses `src/BlueBridgingHeader.h` to expose C APIs to Swift. `Blue.c`
|
||||||
web Mahjong, kept for reference — not part of the build.
|
compiles EGL helpers and rlgl using their implementation macros exactly once.
|
||||||
|
It uses the raylib-iOS XCFramework headers but does not link its full raylib
|
||||||
|
library. The app links/embeds `libEGL` and `libGLESv2` (ANGLE's Metal backend).
|
||||||
|
The XcodeGen settings define `PLATFORM_IOS`, `GRAPHICS_API_OPENGL_ES3`, and
|
||||||
|
`GL_GLEXT_PROTOTYPES`. Minimum iOS is 15.0; portrait and both landscape
|
||||||
|
orientations are enabled in Blue's Info.plist.
|
||||||
|
|
||||||
|
## Build and prerequisites
|
||||||
|
|
||||||
|
- macOS: `brew install raylib`.
|
||||||
|
- iOS project generation: `brew install xcodegen`; supply sibling
|
||||||
|
`../raylib-ios-xcframeworks` containing raylib/libEGL/libGLESv2 XCFrameworks.
|
||||||
|
`checkRaylibIOS` checks presence; it does not download them.
|
||||||
|
- Dialect: sibling `../dialect`, built with `(cd ../dialect && util/build-generator)`.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
util/build-ogs-blue-mac
|
||||||
|
util/run-ogs-blue-mac
|
||||||
|
util/prepare-ogs-blue-ios
|
||||||
```
|
```
|
||||||
|
|
||||||
## Symlink parity rule
|
The corresponding macOS build/run scripts also exist for `ogs-chkgfx` and
|
||||||
|
`ogs-mahjong`; `prepare-ogs-chkgfx-ios` exists as well. Inspect their individual
|
||||||
|
configuration before assuming parity with Blue.
|
||||||
|
|
||||||
`components/` is the source of truth; `game/ver-mac/src/` contains real
|
macOS build scripts generate Dialect, run `swift build`, and package resources
|
||||||
directories whose files are **relative symlinks** back into `components/`:
|
from `ver-mac/res/` into `ver-mac/.build/<App Name>.app`. iOS preparation checks
|
||||||
|
XCFrameworks, generates Dialect, stages ANGLE include/library symlinks in
|
||||||
|
`ver-ios/.build/`, then runs XcodeGen. Build Blue for Simulator with:
|
||||||
|
|
||||||
```
|
```sh
|
||||||
src/other/other.swift -> ../../../../components/other/other.swift (4 up)
|
xcodebuild -project 'ogs-blue/ver-ios/OGS blue.xcodeproj' -scheme ogs-blue \
|
||||||
src/raybri/raybri.c -> ../../../../components/raybri/raybri.c (4 up)
|
-sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
|
||||||
src/raybri/raybri.h -> ../../../../components/raybri/raybri.h (4 up)
|
CODE_SIGNING_ALLOWED=NO build
|
||||||
src/render/render.swift -> ../../../../components/render/render.swift (4 up)
|
|
||||||
src/render/renderAux.swift -> ../../../../components/render/renderAux.swift (4 up)
|
|
||||||
src/render/renderConst.swift-> ../../../../components/render/renderConst.swift (4 up)
|
|
||||||
src/render/renderConstShader.swift -> ../../../../components/render/renderConstShader.swift (4 up)
|
|
||||||
src/render/renderEffect.swift -> ../../../../components/render/renderEffect.swift (4 up)
|
|
||||||
src/render/renderVM.swift -> ../../../../components/render/renderVM.swift (4 up)
|
|
||||||
src/root/root.swift -> ../../../../components/root/root.swift (4 up)
|
|
||||||
src/root/rootVM.swift -> ../../../../components/root/rootVM.swift (4 up)
|
|
||||||
src/root/view/RootView.swift-> ../../../../../components/root/mac/view/RootView.swift (5 up)
|
|
||||||
src/render/view/RenderGLView.swift -> ../../../../../components/render/mac/view/RenderGLView.swift (5 up)
|
|
||||||
src/render/view/RenderView.swift -> ../../../../../components/render/mac/view/RenderView.swift (5 up)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
SPM silently **skips** a dangling symlink (no error), so after moving
|
Audit dangling source symlinks after moves (SPM can silently skip them):
|
||||||
`components/` or a subdir, audit for broken links:
|
|
||||||
|
|
||||||
```bash
|
```sh
|
||||||
find . -type l ! -exec test -e {} \; -not -path './.build/*'
|
find components ogs-blue ogs-chkgfx ogs-mahjong -type l ! -exec test -e {} \; -not -path '*/.build/*'
|
||||||
```
|
```
|
||||||
|
|
||||||
## Prerequisite: the generator
|
|
||||||
|
|
||||||
`util/step/generateDialect` calls the **sibling** dialect repo:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
$SDIR/../../dialect/util/run-generator --file=$SDIR/../dialect.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
So `/Volumes/MOE/p/dialect` must exist and its generator must be built before
|
|
||||||
`util/build-mac` can regenerate:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
(cd ../dialect && util/build-generator) # once, or after dialect core changes
|
|
||||||
```
|
|
||||||
|
|
||||||
The generator resolves the `output:` path **relative to `dialect.yml`'s
|
|
||||||
directory**, which is why `dialect.yml` says `game/ver-mac/src/dialect.swift`.
|
|
||||||
|
|
||||||
## Prerequisite: raylib
|
|
||||||
|
|
||||||
The 3D scene links against Homebrew **raylib** (`brew install raylib`). The
|
|
||||||
`RaylibBridge` C target and the link step read `RAYLIB_PREFIX` (default
|
|
||||||
`/opt/homebrew`); `util/step/buildMac` auto-detects it via `brew --prefix raylib`.
|
|
||||||
The bridge renders with raylib's rlgl layer into an `NSOpenGLView` — raylib never
|
|
||||||
creates its own window. `RootView` puts `RenderView` (backed by `RenderGLView`)
|
|
||||||
behind the SwiftUI UI in a `ZStack`. A textured cube is drawn from `Resources/assets` (`cube.gltf` +
|
|
||||||
`cube_texture.png` + `cube_normal.png`); the app rotates it each frame via `raybri_set_rotation`.
|
|
||||||
(raylib's `LoadModelAnimations` only handles *skinned* meshes, so a plain
|
|
||||||
node-rotation glTF animation cannot be played by the renderer — hence the cube is
|
|
||||||
app-driven.) `packageMac` bundles `Resources/assets/` into the app.
|
|
||||||
|
|
||||||
Shaders and render constants live in **Swift**, not in C: GLSL sources are
|
|
||||||
`RENDER_SHADER_*` in `components/render/renderConstShader.swift`, and
|
|
||||||
`RENDER_CONFIG` / `raybri_config` tunables are in `renderConst.swift`. `raybri_init`
|
|
||||||
compiles the shaders in place (no storage/`strdup`). `cube_normal.png` drives
|
|
||||||
tangentless normal mapping via the derivative-based `cotangentFrame`. The
|
|
||||||
context is OpenGL 3.2 Core (`RENDER_OPENGL_ATTRS`); on Apple Silicon the driver
|
|
||||||
still reports 4.1/GLSL 4.10.
|
|
||||||
|
|
||||||
## Render architecture
|
|
||||||
|
|
||||||
The `Render` dialect context owns the GL scene. `RenderGLView` is a thin
|
|
||||||
`NSOpenGLView`; it only translates AppKit callbacks into dialect fields, and the
|
|
||||||
`render*` files do the actual work.
|
|
||||||
|
|
||||||
1. `AppDelegate` creates `RenderComponent` + `RenderVM` and calls
|
|
||||||
`render.setup()` -> `didSetup` -> `didLaunch` (should) -> `pixelSize = [1, 1]`.
|
|
||||||
2. SwiftUI builds `RenderView` -> `RenderGLView`; `prepareOpenGL()` sets
|
|
||||||
`F.didPrepareGL`. Its oneliners run `renderInit` (`raybri_init`), set
|
|
||||||
`RenderVM.didPrepareGL = true`, and `renderStartTimer`.
|
|
||||||
3. `reshape()` / `viewDidChangeBackingProperties()` compute the backing pixel
|
|
||||||
size via `renderPixelSize` and set `F.reshapePixelSize` /
|
|
||||||
`F.backingPixelSize`. The `pixelSize` shoulds fold these into `F.pixelSize`,
|
|
||||||
whose oneliner stores `RenderVM.pixelSize`.
|
|
||||||
4. The timer only sets `needsDisplay` every `1 / RENDER_FPS`. `draw(_:)` forwards
|
|
||||||
to `renderDraw` (make context current, `raybri_resize`, `raybri_set_rotation`,
|
|
||||||
`raybri_render`, `flushBuffer`).
|
|
||||||
5. A button click runs `rootSet(F.didClickIncrement)` -> RootComponent oneliner
|
|
||||||
`renderSet(F.didClickIncrement)` -> `renderLoadCubeModel` (the cube is loaded
|
|
||||||
on demand, not at startup).
|
|
||||||
6. `RenderGLView.deinit` sets `F.willDeinit` -> `renderDeinit` (stop timer,
|
|
||||||
`raybri_shutdown`).
|
|
||||||
|
|
||||||
**GL context rule**: every raylib call must run with the view's context current.
|
|
||||||
`renderInit`, `renderLoadCubeModel`, `renderDeinit` and `renderDraw` all call
|
|
||||||
`openGLContext?.makeCurrentContext()` first. Loading a model/texture without it
|
|
||||||
fails silently with `WARNING: TEXTURE: Failed to load texture`.
|
|
||||||
|
|
||||||
## Build & Run
|
|
||||||
|
|
||||||
```bash
|
|
||||||
util/build-mac # generateDialect + swift build + package OGS Mahjong.app
|
|
||||||
util/run-mac # runs .build/OGS Mahjong.app/Contents/MacOS/ogs-mahjong
|
|
||||||
util/rm-mac-geom # reset the app's saved window geometry
|
|
||||||
```
|
|
||||||
|
|
||||||
`build-mac` sources `util/paths` then the `util/step/*` scripts in order:
|
|
||||||
|
|
||||||
1. `generateDialect` — runs the sibling generator, writes `src/dialect.swift`
|
|
||||||
2. `buildMac` — `brew --prefix raylib` -> `RAYLIB_PREFIX`, `swift build`
|
|
||||||
3. `packageMac` — assembles `.build/OGS Mahjong.app` (binary `ogs-mahjong`,
|
|
||||||
`Info.plist`, `Resources/AppIcon.icns`, `Resources/assets/`)
|
|
||||||
|
|
||||||
## Editing the dialect
|
## Editing the dialect
|
||||||
|
|
||||||
- Add/modify contexts and components in `dialect.yml`, then run
|
- Add/modify contexts and components in `<app>/dialect.yml`, then run
|
||||||
`util/build-mac` to regenerate `dialect.swift`.
|
`util/build-<app>-mac` to regenerate `dialect.swift`.
|
||||||
- **Chicken-egg**: `struct F` (field-name constants) lives only in the
|
- **Chicken-egg**: `struct F` (field-name constants) lives only in the
|
||||||
generated `dialect.swift`. Adding a new field to a context in `dialect.yml`
|
generated `dialect.swift`. Adding a new field to a context in `<app>/dialect.yml`
|
||||||
requires hand-patching its `static let <field> = "<field>"` into `struct F`
|
requires hand-patching its `static let <field> = "<field>"` into `struct F`
|
||||||
in `dialect.swift` (ASCII-alphabetical order) if you cannot regenerate first,
|
in `dialect.swift` (ASCII-alphabetical order) if you cannot regenerate first,
|
||||||
otherwise the build fails on `F.<field>` being unresolved.
|
otherwise the build fails on `F.<field>` being unresolved.
|
||||||
- `dialect.swift` is generated — edits there are overwritten on the next
|
- `dialect.swift` is generated — edits there are overwritten on the next
|
||||||
`util/build-mac`. Change the source (`dialect.yml` / `components/`) instead.
|
`util/build-<app>-mac`. Change the source (`<app>/dialect.yml` / `components/`) instead.
|
||||||
- **Validate `dialect.yml` after edits** (e.g. `ruby -ryaml -e 'YAML.load_file("dialect.yml")'`).
|
- **Validate `<app>/dialect.yml` after edits** (e.g. `ruby -ryaml -e 'YAML.load_file("ogs-blue/dialect.yml")'`).
|
||||||
Every should-branch label (`1. Upon each ...`) MUST end with a colon — the
|
Every should-branch label (`1. Upon each ...`) MUST end with a colon — the
|
||||||
parser (`components/yml/ymlFun.swift`) blindly `dropLast()`s it, so a missing
|
parser (`components/yml/ymlFun.swift`) blindly `dropLast()`s it, so a missing
|
||||||
colon silently eats the label's last character in the generated `about`
|
colon silently eats the label's last character in the generated `about`
|
||||||
@@ -246,17 +148,13 @@ Do not flip it on without addressing those.
|
|||||||
- Never call raylib / `raybri_*` without making the view's GL context current first
|
- Never call raylib / `raybri_*` without making the view's GL context current first
|
||||||
(see the GL context rule above).
|
(see the GL context rule above).
|
||||||
|
|
||||||
## Skill: source-file study documents
|
## Source study documents
|
||||||
|
|
||||||
When the task is to produce a source-code study document — a self-contained,
|
|
||||||
downloadable HTML file with a line-by-line table of the file and its
|
|
||||||
explanations (and, on request, a second version highlighting changes after a
|
|
||||||
fix) — follow the skill in `docs/file-summary.md`.
|
|
||||||
|
|
||||||
- Write the result to `docs/<FileName>.html` (e.g. `docs/RaylibGLView.html`) and
|
|
||||||
name the file's Git revision in the header. The file is the source of truth —
|
|
||||||
document the exact revision requested, not the working tree.
|
|
||||||
- Existing example: `docs/RaylibGLView.html` — documents the historical
|
|
||||||
single-cube `RaylibGLView.swift`, since split into `RenderGLView.swift` plus
|
|
||||||
the `render*` files.
|
|
||||||
|
|
||||||
|
- Single-file source studies: follow [docs/file-summary.md](docs/file-summary.md).
|
||||||
|
- Mirrored platform studies: follow [docs/mirror-summary.md](docs/mirror-summary.md).
|
||||||
|
Produce one self-contained downloadable HTML with aligned function starts,
|
||||||
|
original line numbers, green/orange number fills, counts/percentages and a
|
||||||
|
non-repetitive explanation column.
|
||||||
|
- Existing mirrored example: `docs/render-platform-comparison.html`, documenting
|
||||||
|
the revision named in its header. Never silently substitute working-tree code
|
||||||
|
for a requested historical revision.
|
||||||
@@ -0,0 +1,68 @@
|
|||||||
|
# Mirrored source-file study documents
|
||||||
|
|
||||||
|
Use this workflow when comparing corresponding source files across platforms.
|
||||||
|
The established example is `docs/render-platform-comparison.html`.
|
||||||
|
For a single-file study, follow `docs/file-summary.md` instead.
|
||||||
|
|
||||||
|
## Source and scope
|
||||||
|
|
||||||
|
- Read sources from the exact requested Git revision with `git show REV:path`.
|
||||||
|
If no revision is specified, use HEAD and record its full commit hash.
|
||||||
|
- Discover matching relative filenames beneath the two platform directories.
|
||||||
|
State which platform-only files are excluded; never invent a counterpart.
|
||||||
|
- Produce one downloadable, self-contained HTML document in `docs/`, with
|
||||||
|
navigation links and one section per file pair. Preserve earlier documents
|
||||||
|
unless removal is requested.
|
||||||
|
- Record both source paths and the source revision. Preserve every source line,
|
||||||
|
original line number, indentation and blank line. Escape HTML characters.
|
||||||
|
|
||||||
|
## Comparison layout
|
||||||
|
|
||||||
|
- Use one table per pair with three columns: first platform's numbered source,
|
||||||
|
second platform's numbered source, and explanation. Do not create separate
|
||||||
|
line-by-line explanation tables or a Status column.
|
||||||
|
- Align corresponding function starts where possible. Insert missing-line
|
||||||
|
placeholders to keep later functions aligned; preserve source order and
|
||||||
|
original numbers. For example, macOS renderEffect line 12 aligns with iOS
|
||||||
|
line 16 at revision f0972f0d5ba796e3fa417081f43c00a9654b2aa6.
|
||||||
|
- Within each function or intervening block, align lines sequentially unless
|
||||||
|
better semantic alignment is needed. Equal line numbers need not share a row
|
||||||
|
when function alignment requires padding.
|
||||||
|
- Compare the exact source text in each aligned row, including whitespace.
|
||||||
|
Fill BOTH line-number backgrounds green when they match. Fill numbers orange
|
||||||
|
when they differ. A missing line is an orange-filled dash, not a plain dash.
|
||||||
|
Keep code backgrounds neutral and retain syntax highlighting.
|
||||||
|
- Include two filled statistics boxes beneath each section heading: green for
|
||||||
|
matching line count and percentage, orange for mismatched count and percentage.
|
||||||
|
Show the total line count as plain text alongside them.
|
||||||
|
- Count actual lines across BOTH files, including blank lines. A matching pair
|
||||||
|
contributes two matching lines; a differing pair contributes two mismatches;
|
||||||
|
a platform-only line contributes one mismatch. Missing placeholders do not
|
||||||
|
count. Percentages use the combined actual-line total. Recalculate after any
|
||||||
|
alignment change, and explain this counting convention in the document.
|
||||||
|
|
||||||
|
## Explanations
|
||||||
|
|
||||||
|
- Explain each distinct point once across the document, at its first relevant
|
||||||
|
occurrence. Leave later cells empty unless they add information.
|
||||||
|
- Eliminate semantic repetition, not just identical sentences. Do not repeat
|
||||||
|
platform/import boilerplate such as “UIKit serves iOS” for every import.
|
||||||
|
- Explain shared behavior once. Label iOS/macOS details only when needed to
|
||||||
|
distinguish behavior. Explain the reason or consequence of platform differences.
|
||||||
|
- Avoid redundant function summaries when the individual operations already
|
||||||
|
explain the same behavior. Leave blank lines and closing braces unexplained.
|
||||||
|
- When realigning rows, anchor each platform-specific explanation to its own
|
||||||
|
source line rather than to the old visual row.
|
||||||
|
|
||||||
|
## Presentation and verification
|
||||||
|
|
||||||
|
- Inline all CSS and syntax highlighting; no external fonts, scripts or requests.
|
||||||
|
- Use `<pre><code>`, `white-space: pre-wrap`, and `overflow-wrap: anywhere`.
|
||||||
|
Give the code columns equal width; ensure long lines remain readable without
|
||||||
|
horizontal scrolling. Do not use striped row shading.
|
||||||
|
- Verify every source line and number against the named Git revision, in order,
|
||||||
|
with no omissions or duplicates. Check function anchors, placeholder fills,
|
||||||
|
both matching-number fills, statistics, and explanation attachment.
|
||||||
|
- Review explanations for repeated clauses as well as repeated sentences.
|
||||||
|
- Inspect the rendered HTML for layout problems. Return a clickable file link;
|
||||||
|
tell the user to refresh an already open document after updates.
|
||||||
Reference in new issue
Block a user