Files
CoCo3_Plus_MiSTer/docs/BUILD_WINDOWS.md
T

183 lines
9.2 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.
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.