Files
CoCo3_Plus_MiSTer/docs/BUILD_WINDOWS.md
T

9.7 KiB

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:

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:

& C:\intelFPGA_lite\17.0\quartus\bin64\quartus_sh.exe --version

Obtain installers through the official Altera software download center. See also MiSTer's compilation guidance. 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

.\windows\Setup-Tools.ps1

This downloads native Windows x64 LWTOOLS 4.25, eight pinned ToolShed 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

.\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

.\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:

.\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:

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

.\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:

# 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:

$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.