Preparing Open RV on macOS

Open RV 2025 can be built for macOS using the VFX reference platform. Dependencies can be viewed in the cmake/defaults/ folder. eg cmake/defaults/CY2026.cmake

Select your VFX reference platform by clicking on the appropriate tab. Install instructions follows.

  • NOTE: CY2025 and CY2026 are experimental. Noteably CY2026 for RV is still on Qt 6.5.3 pending changes necessary for 6.8.3

Boost               : 1.88.0
Cmake               : 3.31.X+
Imath               : 3.2.2
NumPy               : 2.3.0
OCIO                : 2.5.0
OpenEXR             : 3.4.3
OpenSSL             : 3.6.0
Python              : 3.13.9
Qt                  : 6.8.3 ** RV Still on 6.5.3 pending work
Xcode               : See XCode section

All other dependencies are shared across variations.

Summary

Note

Open RV can be built for x86_64 by changing the architecture of the terminal to x86_64 using the following command:

arch -x86_64 $SHELL

It is important to use that x86_64 terminal for all the subsequent steps.

Allow Terminal to update or delete other applications

From macOS System Settings > Privacy & Security > App Management, allow Terminal to update or delete other applications.

Install Xcode

Heads Up: If you are using >= Xcode 26 you will need to patch Qt 6.5.3 and 6.8.3 to implement the fix for QTBUG-137687.

This patch is run during the sourcing of rvcmds.sh. You can also run it directly via sh apply_qt_fix.sh

Alternately you can use Xcode 16.4 on the latest macOS Tahoe 26 to build Open RV.

From the App Store, download Xcode 16.4. Make sure that it is the source of the active developer directory.

xcode-select -p should return /Applications/Xcode.app/Contents/Developer. If that is not the case, run sudo xcode-select -s /Applications/Xcode.app

Install CMake

Homebrew’s CMake could previously be used to build Open RV on macOS, but now it installs CMake version 4, which is too recent and causes dependency issues. An earlier version of CMake must be installed separately: cmake-3.31.7-macos-universal.dmg.

Add the CMake tool to the PATH using the following command:

sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install=/usr/local/bin

Install Homebrew

Homebrew is the one-stop shop providing all the build requirements. You can install it by following the instructions on the Homebrew page.

Make sure Homebrew’s binary directory is in your PATH and that brew can be resolved from your terminal.

Install tools and build dependencies

Most of the build requirements can be installed by running the following brew install command:

brew install ninja readline sqlite3 xz zlib tcl-tk@8 autoconf automake libtool python@3.11 yasm clang-format black meson nasm pkg-config glew rust ccache

Warning

Rust version 1.92 or later is required to build certain Python dependencies (such as cryptography) that contain Rust components. Homebrew will install the latest stable version of Rust.

Compiler Caching (ccache)

ccache dramatically speeds up rebuild times by caching compiled objects (50-80% faster rebuilds). It was installed in the previous step.

Configure ccache with a larger cache size:

ccache --max-size=10G

OpenRV will automatically detect and use ccache when available. To verify it’s working after building:

ccache --show-stats

Note

First-time build: ccache has no effect on the first build as it establishes the cache. Subsequent builds: You’ll see significant speedups (50-80% faster) on incremental or clean rebuilds.

To disable ccache if needed:

export RV_DISABLE_COMPILER_CACHE=1

Make sure xcode-select -p still returns /Applications/Xcode.app/Contents/Developer. If that is not the case, run sudo xcode-select -s /Applications/Xcode.app

Install Qt

Download the Qt version corresponding to your chosen VFX reference platform using the online installer on the Qt page. Qt logs, Android, iOS, and WebAssembly are not required to build Open RV.

Download Qt 6.5.3 using the online installer.
This version should be available in the regular Qt installer without needing archives.
The CI build agents are currently using Qt 6.5.3.

WARNING: If you fetch Qt from another source, make sure it is built with SSL support, contains everything required to build PySide6 (for VFX-CY2024) or PySide2 (for VFX-CY2023), and that the file structure is similar to the official package.

Note: Qt from homebrew is known to not work well with Open RV.

Build Open RV

Once the platform-specific installation process is complete, building Open RV follows the same process for all platforms. Please refer to the Common Build Instructions for the complete build process.

macOS-Specific Build Notes

Executable Location

Once the build is completed, the Open RV application can be found in the Open RV directory under _build/stage/app/RV.app/Contents/MacOS/RV.

9. Setting up debugging in VSCode

For a general understanding on how to debug C++ code in VSCode, please refer to the Microsoft documentation.

To set up the C++ debugger in VSCode for Open RV, use the following steps:

  1. Install the CodeLLDB extension

  2. Configure the debugger
    Create a .vscode folder at the root of the project if it doesn’t already exist. Inside this folder, create a launch.json file to configure the debugger with the following content:

    {
  "version": "0.2.0",
  "configurations": [
    {
      "type": "lldb",
      "request": "launch",
      "name": "Debug Open RV (Debug Build)",
      "program": "${workspaceFolder}/_build_debug/stage/app/RV.app/Contents/MacOS/RV",
      "args": [],
      "cwd": "${workspaceFolder}",
      "preLaunchTask": "build"
    }
  ]
}

    NOTE: program should point to the build of the Open RV executable you want to debug. preLaunchTask is only necessary if you decide to follow step 3.

  3. Set up automatic rebuild (Optional)
    If you want to automatically rebuild Open RV before starting the debugger, add a tasks.json file in the .vscode folder created in the previous step:

    {
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "type": "shell",
      "command": "cmake",
      "args": ["--build", "_build_debug", "--target", "main_executable"],
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "presentation": {
        "reveal": "always"
      }
    }
  ]
}