193 lines
9.7 KiB
Markdown
193 lines
9.7 KiB
Markdown
# Windows build and validation
|
|
|
|
## Required tools
|
|
|
|
Use 64-bit Windows, Git for Windows and Python **3.10 or newer**. Scripts use the
|
|
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,
|
|
then the 17.0 Update 2 package when using the separate installers. Check:
|
|
|
|
```powershell
|
|
& C:\intelFPGA_lite\17.0\quartus\bin64\quartus_sh.exe --version
|
|
```
|
|
|
|
Obtain installers through the [official Altera software download center](https://www.altera.com/downloads).
|
|
See also [MiSTer's compilation guidance](https://mister-devel.github.io/MkDocs_MiSTer/developer/compile/).
|
|
Setup does not silently install Quartus, accept its license or select a newer IP
|
|
generator. Other Quartus versions require separate baseline/timing validation.
|
|
|
|
## Download public build dependencies
|
|
|
|
```powershell
|
|
.\windows\Setup-Tools.ps1
|
|
```
|
|
|
|
This downloads native Windows x64 [LWTOOLS 4.25](https://www.lwtools.ca/releases/lwtools/),
|
|
eight pinned [ToolShed cocoroms](https://github.com/nitros9project/toolshed/tree/3667a41c9605b7fcb150eace29cc7f42d460be1a/cocoroms)
|
|
source files and four pinned MiSTer Main source files used only by parser tests.
|
|
Archives, extracted files and individual source files are checked against
|
|
`tools/toolchain.json` and `tools/cocoroms.json`. Existing changed downloads are
|
|
rejected, not silently replaced. `.cache`, `.tools` and `.deps` are ignored.
|
|
No SSC firmware, software library or emulator source is fetched.
|
|
|
|
## Assemble boot ROMs
|
|
|
|
```powershell
|
|
.\windows\Build-ROMs.ps1
|
|
```
|
|
|
|
The native LWASM recipe follows ToolShed's dependency order: BASIC 1.3,
|
|
`dumpcb_equates`, Extended BASIC 1.1, `dumpecb_equates`, Disk BASIC 1.1 with
|
|
`noindex0tonone`, then the CoCo3 ROM. Four output SHA-256 values must match before
|
|
`boot0.rom` and `boot1.rom` are staged in `build/roms`. The receipt records every
|
|
command and input/output identity. No C compiler or CMOC is required.
|
|
|
|
The assembly rebuild is reproducible; availability of source is not a blanket
|
|
permission to redistribute the resulting third-party ROMs. See LICENSING.md.
|
|
The ToolShed tree inspected contains SSC documentation but no original SSC
|
|
TMS7040 or SP0256 ROM source. Those chips cannot be reconstructed with this
|
|
6809 assembly recipe; supply their verified originals as described in roms/README.md.
|
|
|
|
## Compile the FPGA
|
|
|
|
```powershell
|
|
.\windows\Build-FPGA.ps1 -QuartusSh C:\intelFPGA_lite\17.0\quartus\bin64\quartus_sh.exe
|
|
```
|
|
|
|
This makes a fresh `build/fpga/project` copy, records individual source hashes,
|
|
uses the committed seed 5 and original build-ID flow, and invokes the native
|
|
Quartus compile. It leaves checked-in source/IP untouched. Logs, reports, bitstream
|
|
and `build.json` remain under `build/fpga`. Success requires a generated RBF,
|
|
nonnegative timing-summary slack and unchanged input hashes. Warning details
|
|
remain in the native log; success is not a claim that no warnings occurred.
|
|
|
|
Never compile in the source checkout or let the GUI replace HDL assignments.
|
|
New HDL belongs in `files.qip`; add it and any new source/IP/data dependencies to
|
|
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.
|
|
|
|
## Functional and detailed timing checks
|
|
|
|
Optional HDL tooling can be downloaded with:
|
|
|
|
```powershell
|
|
.\windows\Setup-Tools.ps1 -IncludeSimulator
|
|
.\windows\Test.ps1
|
|
```
|
|
|
|
The pinned OSS CAD Suite supplies Icarus Verilog. The native Main parser fixtures
|
|
also need Visual Studio 2022 C++ Build Tools (MSVC and Windows SDK), or a native
|
|
C++17 compiler on macOS/Linux. These fixtures compile selected original parser
|
|
functions with mocked file/transport calls; they do not build or replace Main.
|
|
Supply an existing suite with `Test.ps1 -Suite <oss-cad-suite-folder>`.
|
|
|
|
`scripts/run_regressions.py` runs 15 independent jobs: MPI modules and actual core
|
|
bindings, original-firmware SSC integration, memory/reset/keyboard/peripheral
|
|
phase checks, SDRAM command/delayed-data tests, audio/pixel/I2C contracts, native
|
|
startup/menu parsing and original-versus-new video fetch. Several include
|
|
deliberately faulty negative controls. Complete repeat runs require a new
|
|
`--output build/<name>` directory. SSC integration requires the ignored chip ROMs.
|
|
|
|
After a full fit, run detailed path audits with:
|
|
|
|
```powershell
|
|
python tools/audit_timing.py --quartus C:\intelFPGA_lite\17.0\quartus\bin64\quartus_sta.exe
|
|
```
|
|
|
|
The audits inspect the fitted MPI, CPU/reset, NMI, UART, video, SSC and conditional
|
|
external-I/O profile at both timing corners. Empty reports are never treated as
|
|
substantive passes; synchronous-only recovery/removal reports may be empty where
|
|
explicitly documented. These checks do not remove the remaining physical-board
|
|
assumptions listed in docs/VALIDATION.md.
|
|
|
|
## Release/install
|
|
|
|
```powershell
|
|
.\windows\Package-Release.ps1
|
|
.\windows\Install-MiSTer.ps1 -Release dist\coco3plus -Load
|
|
```
|
|
|
|
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. 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.
|
|
|
|
Select that new fit explicitly when packaging; `-Build` defaults to `build/fpga`
|
|
only when omitted. Use fresh output names to preserve previous packages:
|
|
|
|
```powershell
|
|
# Complete local install package using your separately supplied verified ROMs.
|
|
.\windows\Package-Release.ps1 -Build build/fpga-qualified -Output dist/coco3plus-qualified
|
|
# Public core/source package; all separately supplied/assembled ROMs omitted.
|
|
.\windows\Package-Release.ps1 -Build build/fpga-qualified -Output dist/coco3plus-qualified-public -PublicPackage
|
|
```
|
|
|
|
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.
|