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