macOS: stabilize OpenRV build (Qt 6.6, AGL workaround, disable optional plugins)

This commit stabilizes OpenRV on macOS (Apple Silicon, macOS Tahoe) and completes a successful RV.app build.

Key changes:
- Added build options to disable optional components:
  - RV_BUILD_PYSIDE (disable PySide6)
  - RV_BUILD_NDI (disable NDI output plugin)
  - RV_BUILD_TESTS (disable test targets)
- Implemented a dummy AGL.framework workaround to satisfy Qt/OpenGL link requirements on modern macOS where AGL is removed.
- Fixed multiple NULL-pointer crashes in Mu/Python integration by adding defensive checks before Python C-API calls.
- Hardened Python startup paths to tolerate missing optional Qt/PySide components.
- Ensured PySide6 and Homebrew Qt are not pulled into the build.
- Verified RV.app builds and launches successfully on Apple Silicon (arm64).

Result:
- RV.app builds successfully on macOS using Qt 6.6.x.
- No startup crashes.
- Optional plugin warnings are non-fatal.
- This commit represents a stable macOS build checkpoint.

Note:
RV.app is not committed to the repository. Built artifacts are excluded per standard practice.

Author: CreativeLyons

BUILD_MACOS_FIXES.md

@@ -0,0 +1,98 @@
+# macOS Build Fixes for OpenRV
+
+This document summarizes the fixes applied to enable building OpenRV on macOS (Apple Silicon).
+
+## Issues Identified and Fixed
+
+### 1. Qt Path Priority Issue (FIXED)
+**Problem:** CMake was finding Qt6 from Homebrew (`/opt/homebrew/lib/cmake/Qt6`) instead of the user-specified Qt installation, causing build failures because Homebrew Qt lacks QtWebEngineCore.
+
+**Fix Applied:** Modified `cmake/dependencies/qt6.cmake` to:
+- Prepend the specified Qt location to `CMAKE_PREFIX_PATH` (instead of appending)
+- Clear cached Qt6 variables to force re-discovery with the specified location
+- Updated error message to reference Qt 6.5.3 instead of Qt 5.15
+
+**Files Changed:**
+- `cmake/dependencies/qt6.cmake`
+
+### 2. Missing Dependencies
+
+#### Required but Missing:
+1. **Qt 6.5.3** - Must be installed from official Qt installer (not Homebrew)
+   - Download from: https://www.qt.io/download-open-source
+   - Install Qt 6.5.3 to `~/Qt/6.5.3/macos` or similar location
+   - Set `QT_HOME` environment variable or let `rvcmds.sh` auto-detect
+
+2. **Xcode Developer Directory** - Currently pointing to Command Line Tools
+   - Run: `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`
+   - Verify with: `xcode-select -p` (should return `/Applications/Xcode.app/Contents/Developer`)
+
+#### Already Installed:
+- ✅ CMake 3.31.2 (meets requirement of 3.31.X+)
+- ✅ Ninja build system
+- ✅ Most Homebrew packages (ninja, readline, sqlite, xz, zlib, autoconf, automake, libtool, python@3.11, yasm, clang-format, black, meson, nasm, pkg-config, glew, rust)
+
+#### Potentially Missing:
+- ✅ `tcl-tk` - Now installed
+
+## Build Instructions
+
+### Prerequisites Setup
+
+1. **Install Qt 6.5.3:**
+   ```bash
+   # Download Qt 6.5.3 from https://www.qt.io/download-open-source
+   # Install to default location: ~/Qt/6.5.3/macos
+   ```
+
+2. **Fix Xcode Developer Directory:**
+   ```bash
+   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+   xcode-select -p  # Verify it returns /Applications/Xcode.app/Contents/Developer
+   ```
+
+3. **Install Missing Homebrew Packages (if needed):**
+   ```bash
+   brew install tcl-tk  # Already installed
+   ```
+
+### Building OpenRV
+
+1. **Navigate to OpenRV directory:**
+   ```bash
+   cd /Users/tonylyons/Dropbox/Public/GitHub/OpenRV
+   ```
+
+2. **Source the build commands:**
+   ```bash
+   export RV_VFX_PLATFORM=CY2024
+   source rvcmds.sh
+   ```
+
+3. **First-time build:**
+   ```bash
+   rvbootstrap
+   ```
+
+4. **Subsequent builds:**
+   ```bash
+   rvmk
+   ```
+
+### Build Output Location
+
+- **Release build:** `_build/stage/app/RV.app/Contents/MacOS/RV`
+- **Debug build:** `_build_debug/stage/app/RV.app/Contents/MacOS/RV`
+
+## CMake Configuration
+
+The build system will automatically:
+- Download and build most dependencies (Boost, OpenEXR, OCIO, Python, etc.)
+- Use the specified Qt installation via `RV_DEPS_QT_LOCATION`
+- Configure for Apple Silicon (arm64) architecture
+
+## Notes
+
+- The fix ensures that when `RV_DEPS_QT_LOCATION` is specified, CMake will prioritize that location over system-installed Qt (like Homebrew)
+- All other dependencies are built from source during the build process
+- The build process uses a Python virtual environment (`.venv`) for Python dependencies

BUILD_REQUIREMENTS.md

@@ -0,0 +1,51 @@
+# OpenRV macOS Build Requirements
+
+## Current Status
+
+✅ **Qt 6.6.3 detected** at `/Users/tonylyons/Qt/6.6.3/macos`
+✅ **QtWebEngine confirmed present**
+❌ **Qt6Multimedia missing** - Required for audio functionality
+
+## Required Qt Components
+
+OpenRV requires the following Qt 6.6.3 components:
+
+1. ✅ **Qt WebEngine** - Already installed
+2. ❌ **Qt Multimedia** - **MISSING** - Required for audio playback
+
+## Fix: Install Qt Multimedia
+
+**Install via Qt Maintenance Tool:**
+
+```bash
+open ~/Qt/MaintenanceTool
+```
+
+Then:
+1. Click "Add or remove components"
+2. Select your Qt 6.6.3 installation
+3. Expand "Qt 6.6.3" → "Additional Libraries"
+4. Check "Qt Multimedia" component
+5. Click "Next" and complete the installation
+
+**Verify installation:**
+```bash
+ls -d /Users/tonylyons/Qt/6.6.3/macos/lib/cmake/Qt6Multimedia
+```
+Should show the directory exists.
+
+## Build Commands (After Installing Qt Multimedia)
+
+```bash
+cd /Users/tonylyons/Dropbox/Public/GitHub/OpenRV
+export RV_VFX_PLATFORM=CY2024
+export QT_HOME=/Users/tonylyons/Qt/6.6.3/macos
+source rvcmds.sh
+rvbootstrap
+```
+
+## Verification
+
+To verify Qt detection is working (not using Homebrew Qt):
+- Check that `QT_HOME` points to `/Users/tonylyons/Qt/6.6.3/macos`
+- CMake should find Qt components from that location, not `/opt/homebrew/lib/cmake/Qt6`

BUILD_STATUS.md

@@ -0,0 +1,92 @@
+# OpenRV macOS Build Status
+
+## Current Status
+
+✅ **Qt Detection Fixed**: CMake now correctly prioritizes the specified Qt installation (`/Users/tonylyons/Qt/6.5.3/macos`) over Homebrew Qt.
+
+✅ **Build Environment Ready**: All required Homebrew packages installed, CMake configured, Python virtual environment set up.
+
+❌ **QtWebEngine Missing**: Qt 6.5.3 installation is missing the QtWebEngine component, which is required for building OpenRV.
+
+## Required Action: Install QtWebEngine
+
+QtWebEngine must be installed via the Qt Maintenance Tool. Follow these steps:
+
+1. **Open Qt Maintenance Tool:**
+   ```bash
+   open ~/Qt/MaintenanceTool
+   ```
+   (If not found there, check `~/Qt/` directory or re-download from https://www.qt.io/download-open-source)
+
+2. **In Qt Maintenance Tool:**
+   - Click "Add or remove components"
+   - Select your Qt 6.5.3 installation
+   - Expand "Qt 6.5.3" → "Additional Libraries"
+   - Check "Qt WebEngine" component
+   - Click "Next" and complete the installation
+
+3. **Verify Installation:**
+   ```bash
+   ls -d /Users/tonylyons/Qt/6.5.3/macos/lib/cmake/Qt6WebEngineCore
+   ```
+   Should show the directory exists.
+
+## Build Commands (After Installing QtWebEngine)
+
+Once QtWebEngine is installed, run:
+
+```bash
+cd /Users/tonylyons/Dropbox/Public/GitHub/OpenRV
+export RV_VFX_PLATFORM=CY2024
+export QT_HOME=/Users/tonylyons/Qt/6.5.3/macos
+source rvcmds.sh
+rvbootstrap
+```
+
+Or step by step:
+```bash
+source rvcmds.sh
+rvsetup    # Install Python dependencies (already done)
+rvcfg      # Configure CMake
+rvbuild    # Build the project
+```
+
+## Final Output Location
+
+After successful build:
+- **Release build:** `_build/stage/app/RV.app/Contents/MacOS/RV`
+- **Debug build:** `_build_debug/stage/app/RV.app/Contents/MacOS/RV`
+
+**To launch:**
+```bash
+open _build/stage/app/RV.app
+# or
+_build/stage/app/RV.app/Contents/MacOS/RV
+```
+
+## Fixes Applied
+
+1. **Qt Path Priority** (`cmake/dependencies/qt6.cmake`):
+   - Prepend Qt location to `CMAKE_PREFIX_PATH` to prioritize over Homebrew
+   - Clear cached Qt6 variables to force re-discovery
+   - Updated error message for Qt 6.5.3
+
+2. **QtWebEngine Installation Guidance**:
+   - Clear error message directing users to install via Qt Maintenance Tool
+   - Qt 6.5.3 WebEngine cannot be auto-downloaded (unlike 6.8.3)
+
+## Verification
+
+To verify Qt detection is working correctly (not picking up Homebrew Qt):
+
+```bash
+cd /Users/tonylyons/Dropbox/Public/GitHub/OpenRV
+export RV_VFX_PLATFORM=CY2024
+export QT_HOME=/Users/tonylyons/Qt/6.5.3/macos
+source rvcmds.sh
+rvcfg 2>&1 | grep -i "qt\|webengine"
+```
+
+Should show:
+- `Using Qt 6.5 installation already set at /Users/tonylyons/Qt/6.5.3/macos`
+- No references to `/opt/homebrew/lib/cmake/Qt6`

CMakeLists.txt

@@ -94,7 +94,12 @@ INCLUDE(rv_targets) # RV's build platform definitions
 INCLUDE(rv_globals) # RV's CMake-build global variables
 INCLUDE(rv_stage) # RV's local appplication packaging
 INCLUDE(rv_vfx)
-INCLUDE(CTest)
+IF(RV_BUILD_TESTS)
+  INCLUDE(CTest)
+  ENABLE_TESTING()
+ELSE()
+  MESSAGE(STATUS "Tests are disabled (RV_BUILD_TESTS=OFF)")
+ENDIF()
 
 # The 'cxx_defaults' module will sets global C/C++ compiler defaults Note that variable such as 'CMAKE_CXX_COMPILER_ID' is only available after the 'project'
 # statement just above.

cmake/defaults/rv_options.cmake

@@ -116,3 +116,25 @@ SET_PROPERTY(
   CACHE RV_FFMPEG
   PROPERTY STRINGS ${_RV_FFMPEG}
 )
+
+#
+# PySide option
+#
+# This option controls whether PySide2/PySide6 is built as part of the Python3 dependency. PySide is not required for RV runtime, but may be needed for Python
+# bindings.
+#
+OPTION(RV_BUILD_PYSIDE "Build PySide2/PySide6 as part of Python3 dependency" ON)
+
+#
+# NDI plugin option
+#
+# This option controls whether the NDI output plugin is built. NDI is an optional plugin that requires the NDI SDK to be installed.
+#
+OPTION(RV_BUILD_NDI "Build NDI output plugin (requires NDI SDK)" ON)
+
+#
+# Tests option
+#
+# This option controls whether test targets are built and enabled. Tests are not required for RV runtime.
+#
+OPTION(RV_BUILD_TESTS "Build and enable test targets" ON)

cmake/defaults/rv_targets.cmake

@@ -90,6 +90,29 @@ IF(APPLE)
     -DOSX_VERSION=${_macos_version_string}
   )
 
+  # AGL framework was deprecated and removed in macOS 10.14+ Qt6::OpenGL adds -framework AGL, but it doesn't exist in newer macOS SDKs Check if AGL exists in
+  # the SDK, and if not, use our dummy framework
+  EXECUTE_PROCESS(
+    COMMAND find ${CMAKE_OSX_SYSROOT}/System/Library/Frameworks -name "AGL.framework" 2>/dev/null
+    OUTPUT_VARIABLE AGL_FRAMEWORK_PATH
+    OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET
+  )
+  IF(AGL_FRAMEWORK_PATH STREQUAL "")
+    # AGL doesn't exist in SDK - add our dummy AGL framework to framework search path This allows the linker to find -framework AGL without modifying Qt
+    SET(_dummy_agl_framework_path
+        "${CMAKE_BINARY_DIR}/frameworks"
+    )
+    IF(EXISTS "${_dummy_agl_framework_path}/AGL.framework")
+      # Add dummy AGL framework directory to framework search path
+      ADD_LINK_OPTIONS(-F "${_dummy_agl_framework_path}")
+      MESSAGE(STATUS "Using dummy AGL framework at ${_dummy_agl_framework_path}/AGL.framework")
+    ELSE()
+      # Fallback: use undefined dynamic lookup if framework doesn't exist This is less ideal but allows build to proceed
+      ADD_LINK_OPTIONS(-Wl,-undefined,dynamic_lookup)
+      MESSAGE(WARNING "Dummy AGL framework not found at ${_dummy_agl_framework_path}/AGL.framework, using -undefined dynamic_lookup fallback")
+    ENDIF()
+  ENDIF()
+
   #
   # CXXFLAGS_DARWIN   += -DOSX_VERSION=\"$(shell sw_vers -productVersion)\"
   #

cmake/dependencies/imgui.cmake

@@ -120,6 +120,24 @@ SET(_patch_command_for_imgui
     patch -p1 < ${CMAKE_CURRENT_SOURCE_DIR}/patch/imgui_cpp_h.patch
 )
 
+# On macOS, add framework search path for dummy AGL framework
+IF(RV_TARGET_DARWIN)
+  SET(_dummy_agl_framework_path
+      "${CMAKE_BINARY_DIR}/frameworks"
+  )
+  IF(EXISTS "${_dummy_agl_framework_path}/AGL.framework")
+    # Add framework search path so linker can find dummy AGL framework
+    LIST(APPEND _configure_options "-DCMAKE_EXE_LINKER_FLAGS=-F${_dummy_agl_framework_path}")
+    LIST(APPEND _configure_options "-DCMAKE_SHARED_LINKER_FLAGS=-F${_dummy_agl_framework_path}")
+    LIST(APPEND _configure_options "-DCMAKE_MODULE_LINKER_FLAGS=-F${_dummy_agl_framework_path}")
+  ELSE()
+    # Fallback: use undefined dynamic lookup if framework doesn't exist
+    LIST(APPEND _configure_options "-DCMAKE_EXE_LINKER_FLAGS=-Wl,-undefined,dynamic_lookup")
+    LIST(APPEND _configure_options "-DCMAKE_SHARED_LINKER_FLAGS=-Wl,-undefined,dynamic_lookup")
+    LIST(APPEND _configure_options "-DCMAKE_MODULE_LINKER_FLAGS=-Wl,-undefined,dynamic_lookup")
+  ENDIF()
+ENDIF()
+
 EXTERNALPROJECT_ADD(
   ${_target}
   URL ${_imgui_download_url}