Harden release packaging and recoverable installation after review
This commit is contained in:
1 parent
cb40fed3b9
commit
8088c1fbf6
14 files changed
+933
-101
No files matched your search
+54
-1
@@ -6,6 +6,24 @@ Use 64-bit Windows, Git for Windows and Python **3.10 or newer**. Scripts use th
|
||||
Python standard library. PowerShell wrappers accept `-Python <full-path>` when
|
||||
`python` is not on PATH. All commands below run from the repository root.
|
||||
|
||||
Use a full Git checkout. An extracted source-review ZIP has no `.git` metadata
|
||||
and deliberately omits inherited binary/manual artifacts still present in the
|
||||
historical project inventory; it is not the supported build checkout. A release's
|
||||
`SOURCE-CHECKOUT.txt` gives the exact immutable revision and clone commands:
|
||||
|
||||
```powershell
|
||||
git clone https://vccplus-git.brianholman.com/VCCPlus/CoCo3_Plus_MiSTer.git coco3plus
|
||||
cd coco3plus
|
||||
# Replace RELEASE_SOURCE_REVISION with the full hash in SOURCE-CHECKOUT.txt.
|
||||
git checkout --detach RELEASE_SOURCE_REVISION
|
||||
git rev-parse HEAD
|
||||
```
|
||||
|
||||
Do not pass `--depth`; the clone preserves the original upstream history. Access
|
||||
to the repository is required. Build tools invoke Git to record the source
|
||||
revision; merely installing the Git executable does not make an archive a Git
|
||||
checkout. Keep the pinned checkout unchanged while building and qualifying it.
|
||||
|
||||
Install **Quartus Prime Lite 17.0.2, Build 602**, including Cyclone V device files.
|
||||
The device is **5CSEBA6U23I7**. The project originated in Quartus 17.0; its pinned
|
||||
settings record 17.0.2. Install the 17.0 base package and matching device package,
|
||||
@@ -71,6 +89,9 @@ the maintained `tools/project_inputs.json` inventory too. The builder rejects
|
||||
unlisted HDL/constraint/IP inputs in the source directories before copying.
|
||||
`validation/source-import.json` is historical provenance, not the build inventory.
|
||||
The receipt derives the seed from the actual single QSF assignment.
|
||||
It also records the SHA-256 of the maintained project inventory. Packaging
|
||||
requires this identity, the exact current hashed-input set, and matching bytes
|
||||
for every input. A subset receipt cannot qualify additional or omitted inputs.
|
||||
Generated caches/IP upgrades stay in build copies.
|
||||
Outputs are preserved: use `-Output build/fpga-next` for another build, with matching
|
||||
`--build` arguments when packaging/auditing it, rather than deleting prior results.
|
||||
@@ -120,10 +141,42 @@ Packaging verifies the RBF and boot/SSC ROM identities, writes a manifest and
|
||||
SHA256SUMS, and creates a copyable `fat/` overlay. No files from build caches or
|
||||
source-reference downloads are installed. Packaging requires reviewed changes
|
||||
committed; corresponding source comes only from that committed Git tree, never
|
||||
untracked local files. `-PublicPackage` omits all separately obtained/assembled ROMs
|
||||
untracked local files. Installed notices are also read from committed Git blobs,
|
||||
so an untracked file in `LICENSES/` is excluded from both archive layers. The
|
||||
source-review payload uses a maintained path/type allowlist in `tools/release.py`;
|
||||
historical RBFs, PDFs and Office files remain in full Git history but are omitted
|
||||
from that payload. `SOURCE-CHECKOUT.txt` records the pinned full-clone build route.
|
||||
`-PublicPackage` omits all separately obtained/assembled ROMs
|
||||
and produces a core/source distribution requiring user ROM preparation. It is
|
||||
distinct from a complete local install package. Details: docs/INSTALL.md.
|
||||
|
||||
Legacy fitted receipts without `project_inventory_sha256` are rejected rather
|
||||
than silently upgraded. Preserve the old build directory, RBF and evidence. The
|
||||
supported independent qualification route is a fresh `Build-FPGA.ps1 -Output
|
||||
build/fpga-qualified` run from the pinned checkout, followed by its own functional,
|
||||
detailed timing and hardware checks appropriate to release acceptance. A
|
||||
prepare-only comparison establishes input equality; it does not create fit or
|
||||
timing evidence. Do not add an inventory hash to an old receipt and present it as
|
||||
newly qualified. Packaging-only changes need not alter RTL, but do not waive this
|
||||
receipt requirement.
|
||||
|
||||
The real local-package guards can target a new qualified build and package
|
||||
without moving or editing historical evidence. From the checkout in PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:COCO3PLUS_TEST_BUILD = 'build/fpga-audit-receipt'
|
||||
$env:COCO3PLUS_TEST_RELEASE = 'dist/coco3plus-audit'
|
||||
python -B tests/test_release_guards.py
|
||||
```
|
||||
|
||||
Paths are resolved relative to the repository root unless absolute. Defaults
|
||||
remain `build/fpga` and `dist/coco3plus` when the overrides are absent. Missing
|
||||
actual local artifacts cause explicit skips; these are separate from portable
|
||||
fixture tests in `tests/test_tooling_guards.py`. A selected complete package must
|
||||
have the current source inventory, outer ZIP, exact committed source revision,
|
||||
and committed Greg Miller notice; an existing historical package lacking those
|
||||
properties is a failure rather than a substitute for checking the new package.
|
||||
|
||||
Portable Python entry points under tools/ support native macOS/Linux tooling
|
||||
where available. Quartus itself has no native macOS build; use the Windows or
|
||||
supported Linux toolchain. The automatic prebuilt-tool download is Windows x64.
|
||||
Reference in new issue
Block a user