Building from Source

Building from Source

This page describes how to build the PICO9918 firmware and configurator ROMs from source.

If you're not interested in building yourself, pre-built firmware and configurator ROMs are available from the Releases page.

Prerequisites

Required Tools

• CMake 3.13+ - Build system generator
• ARM GNU Toolchain 13.2.1-1.1 - Cross-compiler for ARM Cortex-M0+
• Raspberry Pi Pico SDK 2.1.1 - Firmware compilation (this specific version is recommended)
• Python 3 with Pillow library - Build scripts and asset conversion
• Git - For submodules and dependencies

Important: Use Pico SDK 2.1.1 specifically. Newer versions (e.g. 2.2.0) may cause linker errors and memory overflow issues.

Platform-Specific Setup

Windows

# Download and install ARM GNU Toolchain 13.2.1-1.1 from:
# https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases/download/v13.2.1-1.1/xpack-arm-none-eabi-gcc-13.2.1-1.1-win32-x64.zip
# Extract to C:\arm-toolchain\ and add to PATH

# Python dependencies
pip install pillow

# Install Pico SDK 2.1.1
git clone -b 2.1.1 --depth 1 https://github.com/raspberrypi/pico-sdk.git pico-sdk
cd pico-sdk
git submodule update --init
git apply --ignore-whitespace --ignore-space-change --3way ../picosdk-2.0.0-visrealm-fastboot.patch
cd ..

Linux (Ubuntu/Debian)

# Install system dependencies
sudo apt-get update
sudo apt-get install -y build-essential cmake python3 python3-pip git gcc-arm-none-eabi

# Python dependencies
pip3 install pillow

# Install Pico SDK 2.1.1
git clone -b 2.1.1 --depth 1 https://github.com/raspberrypi/pico-sdk.git pico-sdk
cd pico-sdk
git submodule update --init
git apply --ignore-whitespace --ignore-space-change --3way ../picosdk-2.0.0-visrealm-fastboot.patch
cd ..

macOS

# Install dependencies via Homebrew
brew install cmake ninja python3 git

# Install ARM GNU Toolchain
curl -L "https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases/download/v13.2.1-1.1/xpack-arm-none-eabi-gcc-13.2.1-1.1-darwin-arm64.tar.gz" -o arm-toolchain.tar.gz
sudo tar -xzf arm-toolchain.tar.gz -C /opt
echo 'export PATH="/opt/xpack-arm-none-eabi-gcc-13.2.1-1.1/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Python dependencies (may require --break-system-packages on newer macOS)
pip3 install pillow

# Install Pico SDK 2.1.1
git clone -b 2.1.1 --depth 1 https://github.com/raspberrypi/pico-sdk.git pico-sdk
cd pico-sdk
git submodule update --init
git apply --ignore-whitespace --ignore-space-change --3way ../picosdk-2.0.0-visrealm-fastboot.patch
cd ..

Development Environment

To set up your development environment for the Raspberry Pi Pico, follow the Raspberry Pi C/C++ SDK Setup instructions.

The latest PICO9918 source can be configured and built using the official Raspberry Pi Pico VSCode plugin.

Building Firmware

Quick Start (Automatic SDK Download)

mkdir build && cd build
cmake .. -DPICO_SDK_FETCH_FROM_GIT=ON -DPICO_SDK_FETCH_FROM_GIT_TAG=2.1.1
cmake --build .

Output in build/dist/: firmware .uf2 file and configurator ROMs for all platforms.

Combined Build (Recommended)

Builds firmware for both PICO9918 (RP2040) and PICO9918 PRO (RP2350), plus all configurator ROMs:

mkdir build && cd build
cmake .. -DPICO9918_BUILD_COMBINED=ON
cmake --build . --target combined
cmake --build . --target build_configurators

Outputs in build/dist/:

• Combined firmware: pico9918-vga-<version>.uf2 - works on both RP2040 and RP2350
• Configurator ROMs: All platform ROMs, each embedding the combined firmware

Firmware Only (RP2040)

mkdir build && cd build
cmake ..
cmake --build . --target firmware

Output: build/dist/pico9918-vga-build-<version>.uf2

Firmware Configuration Options

Configure output mode and features with -D flags:

Option	Default	Description
PICO9918_SCART_RGBS	OFF	Enable SCART RGBs output instead of VGA
PICO9918_SCART_PAL	OFF	Use PAL 576i timing instead of NTSC 480i
PICO9918_NO_SPLASH	OFF	Disable splash screen on startup
PICO9918_DIAG	OFF	Enable diagnostic overlays by default

Examples

# VGA output (default)
cmake ..

# SCART RGBs NTSC output
cmake .. -DPICO9918_SCART_RGBS=ON

# SCART RGBs PAL output
cmake .. -DPICO9918_SCART_RGBS=ON -DPICO9918_SCART_PAL=ON

# Diagnostic build with no splash
cmake .. -DPICO9918_DIAG=ON -DPICO9918_NO_SPLASH=ON

Building Configurator ROMs

Auto-Building Tools

The build system automatically downloads and builds all required tools:

• CVBasic (Retro BASIC compiler)
• GASM80 (Z80 assembler)
• XDT99 (TI-99/4A development tools)

No manual tool installation is needed. Simply run the build commands.

Building All Configurator ROMs

mkdir build && cd build
cmake .. -DPICO9918_BUILD_COMBINED=ON
cmake --build . --target combined
cmake --build . --target build_configurators

Building Individual Platforms

cmake --build . --target ti99              # TI-99/4A
cmake --build . --target coleco            # ColecoVision
cmake --build . --target msx_asc16         # MSX ASCII16
cmake --build . --target msx_konami        # MSX Konami
cmake --build . --target nabu              # NABU
cmake --build . --target creativision      # CreatiVision
cmake --build . --target nabu_mame_package # NABU MAME (.npz)

Using Pre-installed Tools (Optional)

If you have CVBasic, GASM80, and XDT99 already installed in your PATH:

cmake .. -DBUILD_TOOLS_FROM_SOURCE=OFF

How the Configurator Build Works

1. Firmware Dependency - Checks for pre-built firmware in ../build/src/
2. UF2 Conversion - Converts firmware to CVBasic data using uf2cvb.py
3. CVBasic Compilation - Compiles .bas sources for each target platform
4. Assembly - Uses GASM80 (most platforms) or XAS99 (TI-99) for final ROM creation
5. Packaging - Creates platform-specific ROM files (.bin, .rom, .nabu, etc.)

VSCode Integration

Firmware Build

Use the Raspberry Pi Pico VSCode extension:

• Compile Project - Builds firmware with current configuration
• Run Project - Flashes firmware to connected Pico
• Flash - Programs firmware via OpenOCD

Set build options in .vscode/settings.json:

{
  "cmake.configureArgs": [
    "-DPICO9918_SCART_RGBS=OFF",
    "-DPICO9918_SCART_PAL=OFF",
    "-DPICO9918_NO_SPLASH=OFF",
    "-DPICO9918_DIAG=OFF"
  ]
}

Configurator Tasks

• Build All Configurator ROMs - All configurator targets
• Build TI-99 Configurator - TI-99/4A ROM only
• Build ColecoVision Configurator - ColecoVision ROM only
• Build MSX Configurator - MSX ROM only

Faster Builds with Ninja

cmake .. -DPICO9918_BUILD_COMBINED=ON -G Ninja
ninja combined
ninja build_configurators

Parallel Builds

cmake --build . --target combined --parallel 8

Output Structure

Combined Build

build/
├── dist/                                      # Final artifacts
│   ├── pico9918-vga-<version>.uf2             # Combined RP2040+RP2350 firmware
│   ├── pico9918_<version>_ti99_8.bin          # TI-99/4A ROM
│   ├── pico9918_<version>_cv.rom              # ColecoVision ROM
│   ├── pico9918_<version>_msx_asc16.rom       # MSX ROM
│   └── ...                                    # Other platform ROMs
├── pico9918/dist/                             # RP2040-only firmware
├── pico9918pro/dist/                          # RP2350-only firmware
└── configurators/                             # Configurator build tree

Firmware-Only Build

build/
├── dist/                                      # Final artifacts
│   └── pico9918-vga-build-<version>.uf2       # RP2040 firmware
└── src/                                       # Build intermediates

SDK Performance Patch

A performance patch is automatically applied for optimal boot times:

• Fast Boot - Optimizes ROSC (Ring Oscillator) for faster startup
• Automatic - Applied by CMake when using PICO_SDK_FETCH_FROM_GIT=ON
• Manual Setup - Required when manually installing SDK (see platform setup above)

The patch is optional. Firmware works without it, just boots slower.

Troubleshooting

Build fails with missing SDK

# Set PICO_SDK_PATH environment variable to your SDK installation
export PICO_SDK_PATH=/path/to/pico-sdk

SDK version compatibility issues

PICO9918 is developed with Pico SDK 2.1.1. SDK 2.2.0 may cause linker errors and memory overflow. Recommended approach:

git clone -b 2.1.1 https://github.com/raspberrypi/pico-sdk.git
cd pico-sdk && git submodule update --init
export PICO_SDK_PATH=$PWD

SDK patch issues

If the patch fails to apply, the firmware will still build - the patch is optional and only improves boot performance.

Missing splash/font assets

pip install pillow

Configurator tool errors

Auto-build is enabled by default. If you disabled it:

cmake .. -DBUILD_TOOLS_FROM_SOURCE=ON

Clean build

rm -rf build/
mkdir build && cd build
cmake ..

Verbose output

cmake --build . --verbose