gaffer-macos

Build Gaffer with Cycles rendering on macOS Apple Silicon.

This repo contains a self-contained build script that downloads Gaffer source, applies patches to fix macOS-specific issues, downloads pre-built dependencies, and compiles everything with SCons. It defaults to the latest tested version, Gaffer 1.7.2.0, and also builds 1.6.19.1 via TAG=1.6.19.1.

Pre-built binary

A ready-to-use build for Apple Silicon is available on the Releases page. You need to remove quarantine attributes on the downloaded build to avoid "Not Opened". Below are instructions for the pre-built binary.

Known limitations

• Cycles OSL is unstable on Apple Silicon in this build path; viewer defaults to SVM
• No OSL shader compile support in Metal mode
• OpenGL 2.1

Build from source

git clone https://github.com/vitusli/gaffer-macos.git
cd gaffer-macos
make build   # ~30 min first time, builds Gaffer 1.7.2.0
make run

To build the older 1.6.19.1 line instead:

make build TAG=1.6.19.1
make run TAG=1.6.19.1

Requirements

• macOS on Apple Silicon
• Xcode command-line tools (xcode-select --install)
• Homebrew
• ~10 GB disk space

The build script will install scons and inkscape via Homebrew if not present.

Cycles device selection on macOS

Metal GPU rendering is enabled by default when a compatible Apple GPU is available.

To force CPU-only mode for debugging or compatibility:

GAFFER_CYCLES_FORCE_CPU=1 ./build-1.7.2.0/bin/gaffer

Make targets

Target	Description
make build	Download, patch, and build Gaffer
make run	Launch Gaffer
make smoke	Quick import test
make clean	Remove source + build directories

Optional GPU visibility smoke test

This repository includes a deterministic Cycles test that verifies geometry and material are visible on both CPU and METAL devices:

./build-1.7.2.0/bin/gaffer env python smoke_gpu_visibility.py

Expected result includes:

• CPU session: CPU ...
• METAL session: METAL_...
• OK: Cycles METAL renders visible geometry/material

Project structure

gaffer-macos/
  build.sh        # Main build script with all patches
  Makefile         # Convenience targets
  .gitignore       # Ignores release-*/, build-*/

After building:

  release-1.xxx/   # Patched Gaffer source (kept for incremental rebuilds)
  build-1.xxx/     # Build output + dependencies (the Gaffer installation)

Gatekeeper note (downloaded builds)

If a downloaded/extracted build triggers many macOS "Not Opened" dialogs for .dylib files, remove quarantine attributes from both files and symlinks:

BUILD_DIR="$HOME/Downloads/build-1.7.2.0"
chmod -R u+w "$BUILD_DIR"
xattr -dr com.apple.quarantine "$BUILD_DIR"
xattr -drs com.apple.quarantine "$BUILD_DIR"

Community

Work like this depends on help from Gaffer's friendly community on Discord. Their shared testing, build notes, and troubleshooting make these macOS builds possible. Join the community here: https://discord.gg/sEm8dDw

Other fixes (details)

Show patch details

Cycles viewer SVM default

Older Gaffer builds could crash in OSL/LLVM on ARM64 macOS. Gaffer is patched to default the interactive viewer to Cycles' built-in SVM shading system on macOS. Gaffer 1.6.17.0 and newer include macOS OSL fixes, so the renderer itself keeps OSL available for manual selection.

OpenGL viewport crash (SIGSEGV)

macOS provides only an OpenGL 2.1 compatibility context. Gaffer's viewport code uses GL_TEXTURE_BUFFER and glTexBuffer (GL 3.1+) which resolve to NULL function pointers. The patches replace these with GL_TEXTURE_1D / glTexImage1D and downgrade GLSL shaders from #version 330 compatibility to #version 120 with GL_EXT_gpu_shader4.

• Python.framework launcher -- macOS bundles Python as a framework; the bin/gaffer launcher is patched to set PYTHONHOME correctly.
• fmt::format enum error -- TweakPlug.cpp passes an enum to fmt::format which newer clang rejects; patched to use the string conversion.
• DiffuseBsdf fallback -- empty Cycles shader graphs crash the SVM compiler; a DiffuseBsdf node is inserted as fallback.
• Expression engine -- two OSL expressions in cyclesViewerSettings.gfr are changed to Python expressions.
• Dependency path relocation -- pre-built dependencies ship with hardcoded /Users/admin/build/... paths; install_name_tool rewrites them.
• Build-time RPATH repair -- Python extension modules and Gaffer dylibs are repaired during a one-time SCons retry if the export phase cannot load them.
• macOS 15+/Tahoe cursor crash workaround -- an AppKit cursor swizzle is loaded from bundled Python startup to avoid ImageIO using Gaffer's bundled libpng through flat namespace lookup.
• Cycles viewer restart on shading-system changes -- switching between SVM and OSL recreates the Cycles viewer renderer so the new mode takes effect.
• Clang warning suppression -- -Wno-error=cast-function-type-mismatch and -Wno-unknown-warning-option added for newer Apple Clang versions.

1.7.x-specific notes

Several 1.6.x macOS patches were upstreamed into Gaffer 1.7.x directly (the Python.framework launcher, DYLD_LIBRARY_PATH removal, and OSL-everywhere Renderer.cpp defaults), so the patch script quietly no-ops those steps on 1.7.x source. What's new for 1.7.x:

• Bare libz install names -- the platform25 Cortex 10.7.1.3 dependency bundle ships several dylibs (libfreetype, libOpenColorIO, libOpenImageIO, libopenvdb, ...) with a bare libz.1.dylib reference (no @rpath/ prefix), which fails dlopen once Gaffer's own Python runs mid-build. The dependency relocation pass now rewrites any bare (non-absolute, non-@) install name to @rpath/<basename>, not just absolute build-machine paths.
• clang 21 warning -- -Wno-error=implicit-const-int-float-conversion is added alongside the existing suppressions; it's new in Xcode 27's clang and fires in the new (1.7.x) PrimitiveVariableType.cpp on half/int conversions at numeric_limits boundaries.
• convertWalk signature change -- ShaderNetworkAlgo.cpp's DiffuseBsdf fallback patch matches both the 1.6.x (shaderManager) and 1.7.x (scene) parameter name for the function it patches.

License

The build script and patches in this repository are provided under the BSD 3-Clause License, matching Gaffer's own license. Gaffer itself is copyright its respective authors.