|
| 1 | +# Maintaining the bundled CnPack subset (boss-installability) |
| 2 | + |
| 3 | +**Read this before touching `CnPack/`, releasing a new tag, or running the fork-sync.** |
| 4 | + |
| 5 | +## Why this fork exists |
| 6 | + |
| 7 | +`freitasjca/Delphi-Cross-Socket` is a fork of |
| 8 | +[`winddriver/Delphi-Cross-Socket`](https://github.com/winddriver/Delphi-Cross-Socket) |
| 9 | +whose **only reason to exist is to be installable with [Boss](https://github.com/HashLoad/boss)** |
| 10 | +(the Delphi package manager). Two upstreams block that: |
| 11 | + |
| 12 | +- **`winddriver/Delphi-Cross-Socket`** ships no `boss.json`. |
| 13 | +- **CnPack / [`cnpack/cnvcl`](https://github.com/cnpack/cnvcl)** — a *dependency* of |
| 14 | + Delphi-Cross-Socket's SSL/crypto layer — also has no `boss.json` and is a huge repo. |
| 15 | + |
| 16 | +So this fork adds (a) a `boss.json`, (b) the **minimal CnPack subset** that |
| 17 | +Delphi-Cross-Socket actually needs, vendored under `CnPack/`, and (c) the mTLS additions |
| 18 | +(`Net/Net.CrossSslSocket.{Base,OpenSSL}.pas`). A consumer (e.g. |
| 19 | +[`horse-provider-crosssocket`](https://github.com/freitasjca/horse-provider-crosssocket)) |
| 20 | +can then `boss install` this fork and compile **without ever touching cnvcl**. |
| 21 | + |
| 22 | +> The `boss.json` `description` currently says *"adds Boss package manifest only. Zero source |
| 23 | +> changes"* — that is **stale**: the fork also vendors the CnPack subset and the mTLS patches. |
| 24 | +> Update it when convenient. |
| 25 | +
|
| 26 | +## The invariant — what must always hold |
| 27 | + |
| 28 | +The vendored subset **must be a complete, self-contained transitive closure** so the package |
| 29 | +compiles standalone: |
| 30 | + |
| 31 | +1. **`CnPack/Common/CnPack.inc` must be present.** Every Cn unit begins with `{$I CnPack.inc}`; |
| 32 | + without it nothing compiles. |
| 33 | +2. **Every unit named in any `uses` clause of a bundled unit must also be bundled.** If you add |
| 34 | + a Crypto unit that pulls in a new `Cn*` dependency, that dependency has to be copied in too. |
| 35 | +3. The split mirrors cnvcl's own layout: foundation units in `CnPack/Common/`, crypto in |
| 36 | + `CnPack/Crypto/`. |
| 37 | + |
| 38 | +### Current inventory (18 files — keep this list and the fork-sync in step) |
| 39 | + |
| 40 | +``` |
| 41 | +CnPack/Common/ CnPack.inc CnConsts.pas CnFloat.pas CnStrings.pas CnWideStrings.pas |
| 42 | +CnPack/Crypto/ CnAES.pas CnBase64.pas CnDES.pas CnKDF.pas CnMD5.pas CnNative.pas |
| 43 | + CnPemUtils.pas CnRandom.pas CnSHA1.pas CnSHA2.pas CnSHA3.pas |
| 44 | + CnSM3.pas CnSM4.pas |
| 45 | +``` |
| 46 | + |
| 47 | +> History: earlier releases kept everything under `CnPack/Crypto/` (14 units). cnvcl later |
| 48 | +> moved the foundation units to `Source/Common/` and added `CnStrings`, `CnWideStrings`, |
| 49 | +> `CnSM4`; the v1.0.3 re-sync follows that — hence the `Common/` directory. |
| 50 | +
|
| 51 | +## Re-syncing the subset when cnvcl updates |
| 52 | + |
| 53 | +1. Update your local cnvcl: `cd cnvcl && git pull --ff-only origin master`. |
| 54 | +2. Copy the units above from cnvcl into the fork: |
| 55 | + - `cnvcl/Source/Common/{CnPack.inc,CnConsts,CnFloat,CnStrings,CnWideStrings}` → `CnPack/Common/` |
| 56 | + - `cnvcl/Source/Crypto/{the 13 crypto units}.pas` → `CnPack/Crypto/` |
| 57 | + - (verify the cnvcl source-side paths — cnvcl occasionally relocates units between |
| 58 | + `Source/Common` and `Source/Crypto`.) |
| 59 | +3. **Re-validate the closure** — the only authoritative check (the CnPack sources are |
| 60 | + **GBK/ANSI-encoded**, which defeats `grep`-based scans): `boss install` this fork into a |
| 61 | + throwaway project, or build `horse-provider-crosssocket` against it, and confirm a clean |
| 62 | + compile with **no missing `Cn*` unit**. If the compiler reports a missing unit, copy it in |
| 63 | + and repeat. |
| 64 | +4. Commit the subset change on its own (`git add -A CnPack/` so renames register), separate |
| 65 | + from version bumps and `.gitattributes` changes. |
| 66 | + |
| 67 | +## ⚠️ Keep the fork-sync automation in step — or it reverts the subset |
| 68 | + |
| 69 | +The fork-sync (`crosssocket-fork-sync-action/` → deployed to the fork's `master` as a daily |
| 70 | +GitHub Action) **resets `master` to upstream's tip and re-layers the CnPack subset from a |
| 71 | +hardcoded list**. If that list doesn't match the inventory above, the next nightly run |
| 72 | +**silently restores the wrong subset and breaks the boss build.** Two files must be updated |
| 73 | +together with any subset change: |
| 74 | + |
| 75 | +- `.github/workflows/sync-upstream.yml` — the `Clone CnPack (cnvcl) and copy required files` |
| 76 | + step (the actual `cp` list + the `mkdir CnPack/Common CnPack/Crypto`). |
| 77 | +- `.sync/README.md` — the human-readable manifest table (fork path ← cnvcl source path). |
| 78 | + |
| 79 | +Optionally pin `CNVCL_REF` in `sync-upstream.yml` to a validated cnvcl tag/sha instead of |
| 80 | +`master`, so a surprise upstream cnvcl change can't break a nightly sync. |
| 81 | + |
| 82 | +## Consumer-side note |
| 83 | + |
| 84 | +Because the foundation units live in `CnPack/Common/`, any consuming project's search path must |
| 85 | +include **both** `CnPack/Common` **and** `CnPack/Crypto` (see the "Required search paths" list |
| 86 | +in `horse-provider-crosssocket`'s README). Adding only `Crypto/` will fail to resolve |
| 87 | +`CnConsts`/`CnFloat`/`CnStrings`/`CnWideStrings`. |
| 88 | + |
| 89 | +## Don't track build/IDE artifacts |
| 90 | + |
| 91 | +`.dcu`, `.res`, `.dproj.local`, `.dsv`, `__history/` must stay out of the repo (they bloat it |
| 92 | +and create false "modified" churn). They are covered by `.gitignore`; if any are already |
| 93 | +tracked, `git rm --cached` them. |
| 94 | + |
| 95 | +## Endgame |
| 96 | + |
| 97 | +The mTLS additions are pending an upstream PR. Once upstream merges them **and** a boss-friendly |
| 98 | +distribution of Delphi-Cross-Socket + CnPack exists, this fork (and this whole subset-maintenance |
| 99 | +burden) can be retired. Until then, every cnvcl bump is a re-sync chore — keep this doc, the |
| 100 | +inventory, and the fork-sync manifest aligned. |
0 commit comments