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

mkdir build
cd build
cmake ..
make

Debug Build

To enable debug symbols and _DEBUG definition:

cmake -DDEBUG=ON ..
make

Building with Tests

To build the test executables (when available):

cmake -DBUILD_TESTS=ON ..
make

Installing

To install the library and headers to $PS2SDK/ports:

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:

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:

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:

which openvcl masp dvp-as

Or for proprietary tools:

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:

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