Migrate to CMake; integrate openvcl+masp for all 13 VU1 renderers

.github/workflows/compilation.yml

@@ -5,58 +5,78 @@ on:
   pull_request:
   repository_dispatch:
     types: [run_build]
+  workflow_dispatch: {}
 
 jobs:
   build:
     runs-on: ubuntu-latest
     container: ps2dev/ps2sdk:latest
     steps:
     - uses: actions/checkout@v4
-    
-    - name: Install dependencies
+
+    - name: Setup dependencies
       run: |
-        apk add build-base git
+        apk update
+        apk add cmake build-base git make bash
+        # Create /bin/bash symlink if it doesn't exist (Alpine installs to /usr/bin/bash)
+        [ -f /bin/bash ] || ln -s /usr/bin/bash /bin/bash
 
     - name: Install ps2stuff
       run: |
         git clone https://github.com/ps2dev/ps2stuff.git
-        cd ps2stuff 
-        make -j $(getconf _NPROCESSORS_ONLN) clean
-        make -j $(getconf _NPROCESSORS_ONLN) all
-        make -j $(getconf _NPROCESSORS_ONLN) install
+        cd ps2stuff
+        git checkout cmake
+        mkdir build
+        cd build
+        cmake ..
+        make -j $(getconf _NPROCESSORS_ONLN)
+        make install
 
-    - name: Compile project
+    - name: Compile masp
       run: |
-        make -j $(getconf _NPROCESSORS_ONLN) clean
-        make -j $(getconf _NPROCESSORS_ONLN) all
-        make -j $(getconf _NPROCESSORS_ONLN) install
+        git clone https://github.com/fjtrujy/masp.git
+        cd masp
+        cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$PS2DEV"
+        cmake --build build -j $(getconf _NPROCESSORS_ONLN)
+        cmake --install build
+
+    - name: Install openvcl
+      run: |
+        git clone https://github.com/fjtrujy/openvcl.git
+        cd openvcl
+        cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$PS2DEV" -DBUILD_TESTING=OFF
+        cmake --build build -j $(getconf _NPROCESSORS_ONLN)
+        cmake --install build
+
 
-    - name: Compile GLUT
+    - name: Configure with CMake
       run: |
-        cd glut 
-        make -j $(getconf _NPROCESSORS_ONLN) clean
-        make -j $(getconf _NPROCESSORS_ONLN) all
-        make -j $(getconf _NPROCESSORS_ONLN) install
-
-    - name: Compile examples
+        mkdir build
+        cd build
+        cmake -DBUILD_GLUT=ON -DBUILD_EXAMPLES=ON ..
+
+    - name: Build project with CMake
       run: |
-        cd examples
-        cd box && make clean all && cd ..
-        cd logo && make clean all && cd ..
-        cd performance && make clean all && cd ..
-        cd tricked_out && make clean all && cd ..
-        cd nehe/lesson02 && make clean all && cd ../..
-        cd nehe/lesson03 && make clean all && cd ../..
-        cd nehe/lesson04 && make clean all && cd ../..
-        cd nehe/lesson05 && make clean all && cd ../..
+        cd build
+        make -j $(getconf _NPROCESSORS_ONLN)
+
+    - name: Install libraries
+      run: |
+        cd build
+        make -j $(getconf _NPROCESSORS_ONLN) install
+
 
+    - name: Get short SHA
+      id: slug
+      run: echo "sha8=$(echo ${GITHUB_SHA} | cut -c1-8)" >> $GITHUB_OUTPUT
 
     - name: Upload artifacts
+      if: ${{ success() }}
       uses: actions/upload-artifact@v4
       with:
-        name: examples
+        name: ps2gl-examples-${{ steps.slug.outputs.sha8 }}
         path: |
-          examples/**/*.elf
-          examples/**/*.gl
-          examples/**/*.rtx
-          examples/**/*.bin
+          build/examples/*.elf
+          build/examples/*.gl
+          build/examples/*.rtx
+          build/examples/*.bin

.gitignore

@@ -11,3 +11,6 @@ prebuilddone
 *.a
 *.elf
 *.orig
+
+# CMake
+build/

CMAKE_BUILD.md

@@ -0,0 +1,199 @@
+# Building ps2gl with CMake
+
+This document describes how to build ps2gl using CMake instead of the traditional Makefile.
+
+## Prerequisites
+
+- PS2DEV environment installed and configured
+- `PS2DEV` environment variable set
+- CMake 3.13 or later
+- VU1 development tools (optional - see note below):
+  - **Open-source tools (recommended):** `openvcl`, `masp`, `dvp-as`
+  - **Proprietary tools (legacy):** `vcl`, `gasp`, `dvp-as`
+
+**Note:**
+- VU1 tools are only required for building VU1 renderers from source
+- The build automatically detects and prefers open-source tools (`openvcl` + `masp`) over proprietary ones (`vcl` + `gasp`)
+- If VU1 tools are not available (e.g., on macOS), the build will automatically use pre-built `.vo` object files from the `vu1/` directory
+- Pre-built objects can be generated by running the build once with VU1 tools available
+- **OpenVCL compatibility**: all 13 renderers (including `indexed` and `scei`) now compile successfully with `openvcl` + `masp`. The proprietary `vcl` + `gasp` toolchain remains supported as a fallback, but is no longer required.
+
+## Building
+
+### Basic Build
+
+```bash
+mkdir build
+cd build
+cmake ..
+make
+```
+
+### Debug Build
+
+To enable debug symbols and `_DEBUG` definition:
+
+```bash
+cmake -DDEBUG=ON ..
+make
+```
+
+### Building with Tests
+
+To build the test executables (when available):
+
+```bash
+cmake -DBUILD_TESTS=ON ..
+make
+```
+
+## Installing
+
+To install the library and headers to `$PS2SDK/ports`:
+
+```bash
+make install
+```
+
+This will:
+- Install `libps2gl.a` to `$PS2SDK/ports/lib/`
+- Install GL headers to `$PS2SDK/ports/include/GL/`
+- Install ps2gl headers to `$PS2SDK/ports/include/ps2gl/`
+
+## Configuration Options
+
+The following CMake options are available:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `DEBUG` | OFF | Enable debug build with `_DEBUG` definition |
+| `BUILD_TESTS` | OFF | Build test executables |
+| `BUILD_EXAMPLES` | OFF | Build the example ELFs under `examples/` |
+| `BUILD_GLUT` | ON | Build the GLUT-compat library |
+| `PS2GL_USE_SCE_VSM` | OFF | Bypass the .vcl pipeline; assemble Sony's reference VSMs (`vu1/sce_<X>_vcl.vsm`) directly with `dvp-as`. Diagnostic mode: lets us isolate "openvcl produces wrong VSMs" from "ps2gl host-side bug" by comparing the SCE-built ELF behavior against the openvcl-built one. |
+
+## Build Flags
+
+The CMake build automatically applies the following flags:
+
+- `-DNO_VU0_VECTORS` - Disables VU0 vector code (currently broken)
+- `-DNO_ASM` - Disables assembly optimizations
+- `-Wno-strict-aliasing` - Suppresses strict aliasing warnings
+- `-Wno-conversion-null` - Suppresses conversion null warnings
+
+## VU1 Renderer Pipeline
+
+ps2gl includes VU1 assembly renderers that go through a complex preprocessing pipeline:
+
+1. **Step 1**: Remove C preprocessor directives and fix include paths
+2. **Step 2**: `gasp`/`masp` assembler preprocessing
+3. **Step 3**: Array notation conversion
+4. **Step 4**: C preprocessor with memory layout headers
+5. **Step 5**: `vcl`/`openvcl` compiler generates `.vsm` files
+6. **Step 6**: `dvp-as` assembler generates `.vo` object files
+
+The CMake build handles all these steps automatically for all 13 renderers:
+
+- fast_nolights, fast
+- general, general_quad, general_tri
+- general_nospec, general_nospec_quad, general_nospec_tri
+- general_pv_diff, general_pv_diff_quad, general_pv_diff_tri
+- indexed
+- scei
+
+All 13 build with either `openvcl + masp` (preferred) or `vcl + gasp` (legacy
+fallback). The output `.vsm` from the open pipeline can be compared against
+the in-tree Sony reference (`vu1/sce_*_vcl.vsm`) for validation.
+
+## CMake Toolchain
+
+The build uses the PS2DEV CMake toolchain file located at:
+```
+$PS2DEV/share/ps2dev.cmake
+```
+
+This toolchain file is automatically detected when `PS2DEV` is set.
+
+## Clean Build
+
+To perform a clean build:
+
+```bash
+rm -rf build
+mkdir build
+cd build
+cmake ..
+make
+```
+
+## Comparison with Makefile Build
+
+The CMake build produces the same output as the traditional Makefile:
+- Same compiler flags
+- Same source files
+- Same VU1 preprocessing pipeline
+- Same install locations
+- Compatible library format
+
+## Migration Notes
+
+The CMake build system was designed to be compatible with the existing Makefile build. Both build systems can coexist in the repository.
+
+### Key Differences:
+
+1. **Out-of-source builds**: CMake uses a separate `build/` directory
+2. **Dependency tracking**: CMake automatically handles dependencies
+3. **Parallel VU1 processing**: CMake can process multiple VU1 renderers in parallel
+4. **Cross-platform**: CMake can generate build files for different build systems
+
+## Troubleshooting
+
+### PS2DEV not found
+
+If you get an error about PS2DEV not being set:
+
+```bash
+export PS2DEV=/path/to/ps2dev
+export PS2SDK=$PS2DEV/ps2sdk
+```
+
+### Toolchain file not found
+
+Make sure the toolchain file exists at `$PS2DEV/share/ps2dev.cmake`.
+
+### VU1 tools not found
+
+Make sure the VU1 tools are in your PATH. For open-source tools:
+
+```bash
+which openvcl masp dvp-as
+```
+
+Or for proprietary tools:
+
+```bash
+which vcl gasp dvp-as
+```
+
+The `dvp-as` tool should be installed as part of PS2DEV. For `openvcl` and `masp`:
+- openvcl: https://github.com/ps2dev/openvcl
+- masp: https://github.com/AzagraMac/masp
+
+### Build errors
+
+Try a clean build:
+
+```bash
+rm -rf build
+mkdir build
+cd build
+cmake ..
+make
+```
+
+### VU1 preprocessing errors
+
+If VU1 preprocessing fails, check that:
+1. All `.vcl` source files exist in `vu1/`
+2. Memory layout headers exist: `vu1/vu1_mem_linear.h` and `vu1/vu1_mem_indexed.h`
+3. VU1 tools are properly installed