# 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 ` 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 `. `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/` 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.