Build, Test, and Publish¶

This document is the practical build/test/publish guide for the repository. For the test design rationale, see TestStrategy.md. For trimming and NativeAOT details, see Trimming.md. For packaging contents, see packaging/README.md.

1. Prerequisites¶

The repository does not include BIOS ROMs, game images, or extracted assets.

Check the SDK:

dotnet --version
dotnet --list-sdks

2. Repository layout¶

5DO.sln
Directory.Build.props        # net10.0, nullable, warnings-as-errors, version, analyzers
Directory.Build.targets      # OpenAL Soft native copy for Windows builds
Directory.Packages.props     # central package versions
global.json                  # SDK pin/roll-forward
src/
  FiveDo.Core/               # contracts, value types, constants, state primitives, logging
  FiveDo.Cpu/                # ARM60 interpreter and disassembler
  FiveDo.Memory/             # RAM/ROM/NVRAM, word-swapped bus
  FiveDo.Madam/              # CEL/pixel/matrix engine
  FiveDo.Clio/               # timers, FIFOs, DMA, interrupts, XBUS/DSP windows
  FiveDo.Dsp/                # audio DSP
  FiveDo.Sport/              # VRAM fill/copy engine
  FiveDo.Video/              # VDLP, frame assembly, mailbox, CPU presenter
  FiveDo.Video.OpenGL/       # OpenGL/GLES presenter, filters, shaders
  FiveDo.Video.Vulkan/       # optional Vulkan presenter and probes
  FiveDo.Video.Direct3D/     # optional Direct3D 11 presenter (Windows)
  FiveDo.Xbus/               # XBUS controller and devices
  FiveDo.Cdrom/              # MEI CD-ROM device
  FiveDo.Storage/            # ISO/BIN/CUE/CHD, BIOS/NVRAM, game database
  FiveDo.Audio/              # WAV/OpenAL/audio analysis/tap
  FiveDo.Input/              # controller state, PBUS, profiles, scripts
  FiveDo.Tas/                # TAS movie container, record/replay, branching
  FiveDo.Diagnostics/        # logging, tracing, PNG/frame dumps, benchmark gates
  FiveDo.Machine/            # composition root, frame loop, Quartz
  FiveDo.Host/               # core runner, pacing, settings, save slots, library, fixes
  FiveDo.Cli/                # headless commands
  FiveDo.Frontend.Avalonia/  # desktop shell and GPU probe
tests/FiveDo.Tests/          # xUnit tests, one folder per subsystem
benchmarks/FiveDo.Benchmarks # stopwatch frame benchmark and CI gate
packaging/                   # bundle/archive scripts and Linux desktop entry
tools/                       # release soak and HQx generation
docs/                        # this documentation set

Project dependency rule: arrows point downward only. FiveDo.Core has no project references; chip projects reference only Core; FiveDo.Machine references all chips; FiveDo.Host references Machine plus host services; frontends reference Host. See Architecture.md section 3.

3. Restore, build, test¶

From the repository root:

dotnet restore 5DO.sln
dotnet build 5DO.sln -c Release
dotnet test 5DO.sln -c Release

The current suite is 1,597 tests (verified 2026-11-03) and completes in a few seconds on the development machine. The build treats warnings as errors and runs the .NET analyzers plus Meziantou and Roslynator analyzers.

Debug builds compile the emulator core projects (FiveDo.Core, Cpu, Memory, Machine, Madam, Clio, Dsp, Sport, Video, Xbus, Cdrom, and Host) with JIT optimizations, while the frontend/UI projects stay unoptimized. This keeps IDE gameplay near Release speed; pass -p:FiveDoOptimizeDebug=false to restore fully unoptimized Debug core assemblies. If Visual Studio's debugger is set to suppress JIT optimization on module load, gameplay will still be slow while attached; use Start Without Debugging or disable that debugger option.

Useful variants:

# Debug build and test
dotnet build 5DO.sln
dotnet test tests/FiveDo.Tests/FiveDo.Tests.csproj

# One test class
dotnet test tests/FiveDo.Tests/FiveDo.Tests.csproj --filter "FullyQualifiedName~ArmDataProcessingTests"

# One test by name fragment
dotnet test tests/FiveDo.Tests/FiveDo.Tests.csproj --filter "DisplayName~state_roundtrip"

# List tests without running
dotnet test tests/FiveDo.Tests/FiveDo.Tests.csproj --list-tests

# Formatting check (CI runs this on Linux)
dotnet format 5DO.sln --verify-no-changes --no-restore

# Apply formatting locally
dotnet format 5DO.sln

# Parser and CD command-stream fuzzing (deterministic)
dotnet run --project tools/FiveDo.Fuzz -c Release -- --seconds 30 --target all --json

# Reproduce one reported fuzz case
dotnet run --project tools/FiveDo.Fuzz -c Release -- --target state --seed 397 --iterations 43

Test project layout¶

The suite is one xUnit project with subsystem folders:

Opt-in test environment variables¶

Examples:

$env:FIVEDO_BIOS = "C:\3DO\panafz1.bin"
$env:FIVEDO_FRAME_DUMP = "artifacts\bios-frames"
dotnet test tests/FiveDo.Tests/FiveDo.Tests.csproj -c Release

$env:FIVEDO_GPU_TESTS = "1"
dotnet test tests/FiveDo.Tests/FiveDo.Tests.csproj -c Release --filter "FullyQualifiedName~GpuProbeIntegrationTests"

$env:FIVEDO_AUDIO_TESTS = "1"
$env:ALSOFT_DRIVERS = "null"
dotnet test tests/FiveDo.Tests/FiveDo.Tests.csproj -c Release --filter "FullyQualifiedName~OpenAlAudioOutputTests"

Real-content tests skip cleanly when the required environment variables are absent.

4. Benchmarks¶

The benchmark is a dependency-free stopwatch harness, not BenchmarkDotNet. It runs a synthetic ARM program by default so CI can gate the core without copyrighted content.

dotnet run --project benchmarks/FiveDo.Benchmarks -c Release -- --frames 600
dotnet run --project benchmarks/FiveDo.Benchmarks -c Release -- --frames 600 --json

Real-content variants:

dotnet run --project benchmarks/FiveDo.Benchmarks -c Release -- `
  --bios bios/panafz1.bin --disc "game.chd" --frames 600 --label "disc"

dotnet run --project benchmarks/FiveDo.Benchmarks -c Release -- `
  --state-in artifacts/compat-current/roadrash-race.state --frames 600 --label "roadrash-race"

Options:

JSON shape (abridged):

{
  "ok": true,
  "label": "synthetic",
  "frames": 600,
  "warmupFrames": 60,
  "stateWarnings": [],
  "core": { "totalMs": 0.0, "msPerFrame": 0.0, "p50Ms": 0.0, "p95Ms": 0.0, "p99Ms": 0.0, "maxMs": 0.0, "fps": 0.0, "millionInstructionsPerSecond": 0.0, "instructionsPerFrame": 0 },
  "pack": { "totalMs": 0.0, "microsecondsPerFrame": 0.0 },
  "mailbox": { "totalMs": 0.0, "microsecondsPerFrame": 0.0 },
  "read": { "totalMs": 0.0, "microsecondsPerFrame": 0.0 },
  "total": { "msPerFrame": 0.0, "p50Ms": 0.0, "p95Ms": 0.0, "p99Ms": 0.0, "maxMs": 0.0, "fps": 0.0, "budget60Ms": 16.667, "headroom": 0.0 },
  "allocations": { "totalBytes": 0, "bytesPerFrame": 0, "coreBytesPerFrame": 0, "packBytesPerFrame": 0, "mailboxBytesPerFrame": 0, "readBytesPerFrame": 0 },
  "machine": { "cyclesPerFrame": 208333, "pc": 0, "frameHash": 0 }
}

The gate (BenchmarkGate) requires:

• allocations.bytesPerFrame == 0
• core.p99Ms <= 8.0
• total.msPerFrame <= 8.0
• total.p99Ms <= 16.667

CI runs:

dotnet run --project benchmarks/FiveDo.Benchmarks -c Release --no-build -- \
  --frames 120 --label ci --json --gate > artifacts/benchmark.json
jq -e '.allocations.bytesPerFrame == 0' artifacts/benchmark.json

The baseline comparison is same-machine only; do not compare numbers across machines. See Performance.md for the measured baselines and methodology.

4a. Differential harness¶

The reference harness is a separate tool; it is not part of the shipped emulator and is not run by the default test job when the BIOS/disc corpus is absent.

dotnet build tools/FiveDo.DiffHarness -c Release
tools/FiveDo.DiffHarness/bin/Release/net10.0/FiveDo.DiffHarness.exe `
  validate benchmarks/diff/smoke.json --strict
tools/FiveDo.DiffHarness/bin/Release/net10.0/FiveDo.DiffHarness.exe `
  run benchmarks/diff/smoke.json --out artifacts/diff/smoke

It needs bios/panafz1.bin, the local disc collection, and the bundled References/CPP_SimpleGui/.../OperaCore.dll. The Lemmings smoke is the quick health check; the five-title showcase takes about ten minutes because the reference core runs in real time. See DifferentialHarness.md for the manifest and report contracts.

5. GPU presentation probe¶

The probe opens the real Avalonia OpenGL surface, presents synthetic 320x240 VDL frames at a requested output size, and writes per-frame present/GPU timings, capabilities, allocations, and optional CPU/GPU parity as JSON. It does not load a BIOS or disc.

dotnet run -c Release --project src/FiveDo.Frontend.Avalonia -- `
  --gl-probe artifacts/gl-probe/4k-sharp.json `
  --gl-probe-size 3840x2160 --gl-probe-frames 120 --gl-probe-warmup 30 `
  --gl-probe-filter sharp-bilinear --gl-probe-offscreen

Options:

A 1:1 accurate capture at 320x240 triggers an automatic CPU/GPU parity comparison against FrameAssembler; the report includes Parity.Compared, Matches, DifferentPixels, CpuHash, GpuHash, and VerticalFlip.

Vulkan probe¶

The optional Vulkan backend has a headless probe. It does not open an Avalonia window and requires a Vulkan 1.0 device and loader.

dotnet run -c Release --project src/FiveDo.Frontend.Avalonia -- `
  --vk-probe artifacts/vk-probe/4k-sharp.json `
  --vk-probe-size 3840x2160 --vk-probe-frames 30 --vk-probe-warmup 10 `
  --vk-probe-filter sharp-bilinear

Set FIVEDO_VULKAN_TESTS=1 to run the opt-in in-process parity/source-size and xBR/FSR orientation tests plus the probe integration test. See Vulkan.md for the measured results and limitations.

Direct3D 11 probe¶

The optional Direct3D 11 backend has a headless probe and a native Win32 swapchain probe. It requires Windows and Direct3D 11 feature level 11_0.

dotnet run -c Release --project src/FiveDo.Frontend.Avalonia -- `
  --d3d-probe artifacts/d3d-probe/4k-sharp.json `
  --d3d-probe-size 3840x2160 --d3d-probe-frames 30 --d3d-probe-warmup 10 `
  --d3d-probe-filter sharp-bilinear

Set FIVEDO_D3D_TESTS=1 to run the opt-in parity, size-change, letterbox, and xBR/FSR/HQx orientation tests. The HLSL compile test runs on Windows without an opt-in flag. See Direct3D.md for measured results and limitations.

See Video.md and Performance.md for interpretation.

6. Publish¶

Framework-dependent single file (release shape)¶

dotnet publish src/FiveDo.Cli/FiveDo.Cli.csproj -c Release -r win-x64 `
  --self-contained false -p:PublishSingleFile=true -p:PublishTrimmed=false -m:1 `
  -o artifacts/cli/win-x64

dotnet publish src/FiveDo.Frontend.Avalonia/FiveDo.Frontend.Avalonia.csproj -c Release -r win-x64 `
  --self-contained false -p:PublishSingleFile=true -p:PublishTrimmed=false -m:1 `
  -o artifacts/frontend/win-x64

Release bundles are produced for win-x64, win-arm64, linux-x64, linux-arm64, osx-x64, and osx-arm64. They contain no .NET runtime; users must install the .NET 10 runtime on their machine.

Both executables are single-file framework-dependent apphosts. The frontend also ships native Skia/HarfBuzz/ANGLE assets. OpenAL Soft is copied as OpenAL32.dll on Windows by Directory.Build.targets; Linux/macOS use the package's native names. PDB and XML documentation files are removed by packaging/package-bundle.ps1.

NativeAOT (opt-in, win-x64)¶

dotnet publish src/FiveDo.Cli/FiveDo.Cli.csproj -c Release -r win-x64 `
  --self-contained true -p:FiveDoNativeAot=true -p:PublishSingleFile=true -m:1 `
  -o artifacts/cli-aot

dotnet publish src/FiveDo.Frontend.Avalonia/FiveDo.Frontend.Avalonia.csproj -c Release -r win-x64 `
  --self-contained true -p:FiveDoNativeAot=true -m:1 `
  -o artifacts/frontend-aot

AOT is not part of the six-RID default matrix. The CLI AOT path opens live OpenAL; the frontend AOT audio path is not validated yet. See Trimming.md.

Smoke tests¶

artifacts/cli/win-x64/FiveDo.Cli.exe --version
artifacts/cli/win-x64/FiveDo.Cli.exe selftest --json
artifacts/cli/win-x64/FiveDo.Cli.exe bench --frames 2 --json

artifacts/frontend/win-x64/FiveDo.Frontend.Avalonia.exe `
  --smoke-test --smoke-output artifacts/frontend-smoke.txt

The frontend smoke test opens the real window, runs one UI pass (GL hidden for headless CI), writes FRONTEND SMOKE OK <version>, and exits 0.

Portable bundles¶

pwsh -File packaging/package-bundle.ps1 -Rid win-x64 `
  -CliPublishDirectory artifacts/cli/win-x64 `
  -FrontendPublishDirectory artifacts/frontend/win-x64 `
  -OutputDirectory artifacts/bundles

The bundle contains both framework-dependent apphosts and their native libraries, README.md, LICENSE, THIRD-PARTY-NOTICES.md, whatsnew.md, docs/Licensing.md, docs/ReleaseLegalReview.md, the latest docs/ReleaseNotes-*.md, and a generated PACKAGE.txt with component, RID, version, commit, and build time. Linux bundles also include 5do.desktop. PDB and XML documentation files are removed, and no .NET runtime is copied into the bundle. The archive name includes the product version, for example 5do-1.2.1-win-x64.zip, 5do-1.2.1-win-arm64.zip, or 5do-1.2.1-linux-arm64.tar.gz; the version is read from Directory.Build.props unless -Version is supplied.

7. CI jobs¶

The workflow is .github/workflows/ci.yml.

Separate workflows add:

CI does not download BIOS ROMs or game images. GPU tests and real-audio tests are opt-in and not part of the default matrix. The repository is public; secret scanning with push protection and private vulnerability reporting are enabled in GitHub settings.

7.1 Local Linux VM validation¶

The local Linux validation target is the Hyper-V VM LinuxMint (D:\Hyper-V\VMs\LinuxMint, generation 2, 8 GB assigned). It is a manual validation target, not a CI replacement. The guest is reachable over SSH; machine-specific credentials are in the gitignored AGENTS.local.md.

Suggested flow:

1. Start the VM (Start-VM -Name LinuxMint) and confirm the guest has the .NET 10 SDK, or publish linux-x64 on the host and copy the publish folder into the guest.
2. Copy the repository or the published CLI/frontend into the guest.
3. Run dotnet test tests/FiveDo.Tests/FiveDo.Tests.csproj -c Release.
4. Run dotnet run -c Release --project src/FiveDo.Cli -- selftest --json.
5. Run the frontend smoke test (--smoke-test) and, when the VM has a usable GL display, the OpenGL probe (--gl-probe).
6. Run a reduced compatibility sweep with -NoFrameCapture; the PNG analysis uses System.Drawing.Common, which is Windows-oriented. Record the CLI JSON results.
7. Record the renderer/vendor/version and any fallback behavior in Compatibility.md and KnownIssues.md.

The Linux pass should use the same BIOS/disc set as the Windows pass. Do not commit BIOS or disc images.

8. Build properties and dependencies¶

Key properties in Directory.Build.props:

Central package versions live in Directory.Packages.props. The notable dependencies are Avalonia 12.1.4, CommunityToolkit.Mvvm, Silk.NET.OpenGL/OpenAL, CHDSharp 1.6.0, xUnit, and BenchmarkDotNet (present but the current benchmark harness is custom). The 3DO Opera file-system reader used by 5do fs is first-party (FiveDo.Storage.OperaFileSystem).

9. Build/test troubleshooting¶

If a failure is emulation-related rather than build-related, see Troubleshooting.md and Diagnostics.md.