Initial commit

wip/patch-format.md

@@ -0,0 +1,85 @@
+# Kobopatch Patch Format
+
+## kobopatch.yaml (Main Config)
+
+```yaml
+version: 4.45.23646
+in: src/kobo-update-4.45.23646.zip
+out: out/KoboRoot.tgz
+log: out/log.txt
+patchFormat: kobopatch
+
+patches:
+  src/nickel.yaml: usr/local/Kobo/nickel
+  src/nickel_custom.yaml: usr/local/Kobo/nickel
+  src/libadobe.so.yaml: usr/local/Kobo/libadobe.so
+  src/libnickel.so.1.0.0.yaml: usr/local/Kobo/libnickel.so.1.0.0
+  src/librmsdk.so.1.0.0.yaml: usr/local/Kobo/librmsdk.so.1.0.0
+  src/cloud_sync.yaml: usr/local/Kobo/libnickel.so.1.0.0
+
+overrides:
+  src/nickel.yaml:
+    Patch Name Here: yes
+    Another Patch: no
+  src/libnickel.so.1.0.0.yaml:
+    Some Other Patch: yes
+```
+
+The `overrides` section is what the web UI generates. Everything else stays fixed.
+
+## Patch YAML Files
+
+Each file contains one or more patches as top-level YAML keys:
+
+```yaml
+Patch Name:
+  - Enabled: no
+  - PatchGroup: Optional Group Name    # patches in same group are mutually exclusive
+  - Description: |
+      Multi-line description text.
+      Can span multiple lines.
+  - <patch instructions...>            # FindZlib, ReplaceBytes, etc. (opaque to UI)
+```
+
+### Fields the UI cares about
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Name | yes | Top-level YAML key |
+| Enabled | yes | `yes` or `no` - default state |
+| Description | no | Human-readable description (single line or multi-line `\|` block) |
+| PatchGroup | no | Mutual exclusion group - only one patch per group can be enabled |
+
+### Patch Files and Their Targets
+
+| File | Binary Target | Patch Count |
+|------|--------------|-------------|
+| nickel.yaml | nickel (main UI) | ~17 patches |
+| nickel_custom.yaml | nickel | ~2 patches |
+| libnickel.so.1.0.0.yaml | libnickel.so | ~50+ patches (largest) |
+| libadobe.so.yaml | libadobe.so | 1 patch |
+| librmsdk.so.1.0.0.yaml | librmsdk.so | ~10 patches |
+| cloud_sync.yaml | libnickel.so | 1 patch |
+
+## PatchGroup Rules
+
+Patches with the same `PatchGroup` value within a file are mutually exclusive.
+Only one can be enabled at a time. The UI should render these as radio buttons.
+
+Example from libnickel.so.1.0.0.yaml:
+- "My 10 line spacing values" (PatchGroup: Line spacing values alternatives)
+- "My 24 line spacing values" (PatchGroup: Line spacing values alternatives)
+
+## YAML Parsing Strategy
+
+PHP doesn't have `yaml_parse` available on this system. Options:
+1. Use a simple line-by-line parser that extracts only the fields we need
+2. Install php-yaml extension
+3. Use a pure PHP YAML library (e.g., Symfony YAML component)
+
+The patch YAML structure is regular enough for a targeted parser:
+- Top-level keys (no indentation, ending with `:`) are patch names
+- `- Enabled: yes/no` on the next level
+- `- Description: |` followed by indented text, or `- Description: single line`
+- `- PatchGroup: group name`
+- Everything else can be ignored