patch pico sdk using cmake

Author: visrealm

.github/workflows/build-common.yml

@@ -56,19 +56,11 @@ jobs:
         Expand-Archive -Path $output -DestinationPath "C:\arm-toolchain"
         echo "C:\arm-toolchain\xpack-arm-none-eabi-gcc-13.2.1-1.1\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
         
-    - name: Install Pico SDK 2.1.1 manually
-      run: |
-        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 || echo "Patch failed or already applied"
-        cd ..
-        
-    - name: Configure CMake
+    - name: Configure CMake (with automatic SDK fetch and patch)
       run: |
         mkdir build
         cd build
-        cmake -S .. -B . -G Ninja -DPICO_SDK_PATH="$PWD/../pico-sdk" -DPICO_BOARD_HEADER_DIRS="../src/boards" -DPICO_BOARD=pico9918 -DBUILD_TOOLS_FROM_SOURCE=ON
+        cmake -S .. -B . -G Ninja -DPICO_SDK_FETCH_FROM_GIT=ON -DPICO_SDK_FETCH_FROM_GIT_TAG=2.1.1 -DPICO_BOARD_HEADER_DIRS="../src/boards" -DPICO_BOARD=pico9918 -DBUILD_TOOLS_FROM_SOURCE=ON
         
     - name: Build Firmware
       if: ${{ inputs.build-firmware }}
@@ -115,19 +107,11 @@ jobs:
         sudo apt-get install -y build-essential cmake python3 python3-pip git gcc-arm-none-eabi
         pip3 install pillow
         
-    - name: Install Pico SDK 2.1.1 manually
-      run: |
-        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 || echo "Patch failed or already applied"
-        cd ..
-        
-    - name: Configure CMake
+    - name: Configure CMake (with automatic SDK fetch and patch)
       run: |
         mkdir build
         cd build
-        cmake -S .. -B . -G Ninja -DPICO_SDK_PATH="$PWD/../pico-sdk" -DPICO_BOARD_HEADER_DIRS="../src/boards" -DPICO_BOARD=pico9918 -DBUILD_TOOLS_FROM_SOURCE=ON
+        cmake -S .. -B . -G Ninja -DPICO_SDK_FETCH_FROM_GIT=ON -DPICO_SDK_FETCH_FROM_GIT_TAG=2.1.1 -DPICO_BOARD_HEADER_DIRS="../src/boards" -DPICO_BOARD=pico9918 -DBUILD_TOOLS_FROM_SOURCE=ON
         
     - name: Build Firmware
       if: ${{ inputs.build-firmware }}
@@ -180,19 +164,11 @@ jobs:
         sudo tar -xzf arm-toolchain.tar.gz -C /opt
         echo "/opt/xpack-arm-none-eabi-gcc-13.2.1-1.1/bin" >> $GITHUB_PATH
         
-    - name: Install Pico SDK 2.1.1 manually
-      run: |
-        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 || echo "Patch failed or already applied"
-        cd ..
-        
-    - name: Configure CMake
+    - name: Configure CMake (with automatic SDK fetch and patch)
       run: |
         mkdir build
         cd build
-        cmake -S .. -B . -G Ninja -DPICO_SDK_PATH="$PWD/../pico-sdk" -DPICO_BOARD_HEADER_DIRS="../src/boards" -DPICO_BOARD=pico9918 -DBUILD_TOOLS_FROM_SOURCE=ON
+        cmake -S .. -B . -G Ninja -DPICO_SDK_FETCH_FROM_GIT=ON -DPICO_SDK_FETCH_FROM_GIT_TAG=2.1.1 -DPICO_BOARD_HEADER_DIRS="../src/boards" -DPICO_BOARD=pico9918 -DBUILD_TOOLS_FROM_SOURCE=ON
         
     - name: Build Firmware
       if: ${{ inputs.build-firmware }}

BUILDING.md

@@ -84,8 +84,18 @@ The latest PICO9918 source can be configured and built using the official [Raspb
 The PICO9918 firmware is the primary component - a TMS9918A VDP emulator for Raspberry Pi Pico.
 
 ### Quick Start - Firmware Only
+
+**Option 1: Automatic SDK Download (Recommended)**
 ```bash
 mkdir build && cd build
+cmake .. -DPICO_SDK_FETCH_FROM_GIT=ON -DPICO_SDK_FETCH_FROM_GIT_TAG=2.1.1
+cmake --build . --target firmware
+```
+
+**Option 2: Manual SDK Setup**
+```bash
+# First: Follow platform-specific setup above to install SDK
+mkdir build && cd build
 cmake ..
 cmake --build . --target firmware
 ```
@@ -152,20 +162,34 @@ Set build options in `.vscode/settings.json`:
 - **DMA**: Memory transfers and sprite processing
 - **Flash**: Configuration storage in upper 1MB
 
-### Automatic SDK Patches
-The build system automatically applies performance patches to the Pico SDK:
-- **Fast Boot**: Optimizes ROSC (Ring Oscillator) for faster boot times
-- Patches are applied automatically when using `PICO_SDK_FETCH_FROM_GIT=ON`
+### SDK Performance Patch
+
+> **✅ Automatic Patch Application**
+> 
+> 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**: Still required when manually installing SDK (see platform instructions above)
+
+#### How It Works
+- **FetchContent builds**: CMake automatically applies `picosdk-2.0.0-visrealm-fastboot.patch` after downloading the SDK
+- **Manual SDK installs**: You must run the `git apply` command shown in platform setup above
+- **Safe Operation**: Patch command includes fallback - build continues even if patch fails
 
 ## Building Configurator
 
 The configurator creates ROM files for retro computers that can upload firmware to PICO9918.
 
 ### Prerequisites - Configurator
-In addition to firmware requirements:
-- **CVBasic**: Retro BASIC compiler (auto-built if missing)
-- **GASM80**: Z80 assembler (auto-built if missing)
-- **XDT99**: TI-99/4A tools (auto-built if missing)
+
+> **✅ No Manual Tool Installation Required!** 
+> 
+> The build system **automatically downloads and builds** all required tools:
+> - **CVBasic** (Retro BASIC compiler)
+> - **GASM80** (Z80 assembler)  
+> - **XDT99** (TI-99/4A development tools)
+>
+> Simply run the build commands below - all tools will be built from source automatically.
 
 ### Quick Start - Configurator
 ```bash
@@ -206,15 +230,21 @@ cmake --build . --target creativision      # CreatiVision
 All configurator tasks automatically depend on firmware build.
 
 ### Tool Auto-Building
-By default, the build system automatically builds CVBasic, GASM80, and XDT99 from source. This ensures builds work on any platform without pre-installed tools.
 
-The system will:
-1. Clone tool repositories from GitHub
-2. Build tools from source using CMake
-3. Cache built tools for subsequent builds
-4. Use locally-built tools for ROM generation
+> **🚀 Zero-Configuration Tool Management**
+>
+> **By default**, the build system automatically handles all configurator tools:
 
-To use existing tools instead (if available):
+The system will automatically:
+1. **Clone** tool repositories from GitHub
+2. **Build** tools from source using CMake  
+3. **Cache** built tools for subsequent builds
+4. **Use** locally-built tools for ROM generation
+
+**No manual tool installation needed!** Works on all platforms out-of-the-box.
+
+#### Advanced: Use Pre-installed Tools (Optional)
+If you have CVBasic, GASM80, and XDT99 already installed in PATH:
 ```bash
 cmake .. -DBUILD_TOOLS_FROM_SOURCE=OFF
 ```
@@ -328,6 +358,18 @@ cmake ..
 # Note: PICO_SDK_FETCH_FROM_GIT_TAG has known issues with tag resolution
 ```
 
+**SDK patch issues**
+```bash
+# If patch fails to apply:
+git apply --ignore-whitespace --ignore-space-change --3way ../picosdk-2.0.0-visrealm-fastboot.patch
+
+# If patch was already applied or conflicts:
+echo "Patch failed or already applied" # This is normal, firmware will still build
+
+# Patch is optional but improves boot performance
+# Firmware works without it, just boots slower
+```
+
 **Missing splash/font assets**
 ```bash
 # Install pillow for image conversion

README.md

@@ -123,8 +123,9 @@ To install, just hold the 'BOOTSEL' (or 'BOOT') button while plugging the Pico i
 Quick start - build both firmware and configurator ROMs:
 
 ```bash
+# Automatic SDK download (recommended)
 mkdir build && cd build
-cmake ..
+cmake .. -DPICO_SDK_FETCH_FROM_GIT=ON -DPICO_SDK_FETCH_FROM_GIT_TAG=2.1.1
 cmake --build .
 ```
 

pico_sdk_import.cmake

@@ -47,14 +47,14 @@ if (NOT PICO_SDK_PATH)
                     GIT_REPOSITORY https://github.com/raspberrypi/pico-sdk
                     GIT_TAG ${PICO_SDK_FETCH_FROM_GIT_TAG}
                     GIT_SUBMODULES_RECURSE FALSE
-                    PATCH_COMMAND ""
+                    PATCH_COMMAND ${CMAKE_COMMAND} -E chdir <SOURCE_DIR> git apply --ignore-whitespace --ignore-space-change --3way ${CMAKE_SOURCE_DIR}/picosdk-2.0.0-visrealm-fastboot.patch || ${CMAKE_COMMAND} -E echo "PICO9918: SDK patch failed or already applied (this is normal)"
             )
         else ()
             FetchContent_Declare(
                     pico_sdk
                     GIT_REPOSITORY https://github.com/raspberrypi/pico-sdk
                     GIT_TAG ${PICO_SDK_FETCH_FROM_GIT_TAG}
-                    PATCH_COMMAND ""
+                    PATCH_COMMAND ${CMAKE_COMMAND} -E chdir <SOURCE_DIR> git apply --ignore-whitespace --ignore-space-change --3way ${CMAKE_SOURCE_DIR}/picosdk-2.0.0-visrealm-fastboot.patch || ${CMAKE_COMMAND} -E echo "PICO9918: SDK patch failed or already applied (this is normal)"
             )
         endif ()