Building Gaffer for Windows (Patreon)

Gaffer always provides up to date Windows builds, but sometimes it's nice to compile your own version from source. A lot of Gaffer is customizable "on the fly" using Python, but many things are hardcoded via C++. The code is very easy to read and it's often pretty straightforward to make small modifications to meet your requirements.

I got some great guidance from Eric over at Gaffer about how to set up a Windows build environment. Gaffer is one of the easiest projects I've ever built, a great testament to how well-designed it is. I wanted to share what I've learned to help others get started as smoothly as possible.

This article assumes you have at least a bit of experience with Git, Visual Studio Code and scripting. Let's get started!

Required apps

To build Gaffer you'll need Visual Studio Community 2022, Git, Inkscape and 3Delight. VS Code is also required for this guide. You can use any IDE or editor you like, but there is a bunch of VS Code-specific stuff in my setup. Here are the links to all these apps:

Visual Studio: https://visualstudio.microsoft.com/vs/community/VS Code: https://code.visualstudio.comGit: https://git-scm.com/downloads/winInkscape: https://inkscape.org/release/3Delight: https://www.3delight.com/download

Download the installers and follow the default setup instructions for each, with one exception for Visual Studio.

Visual Studio setup

The main thing you need to configure when installing VS is selecting the "Desktop development with C++" Workload. Not all the modules are required, but it's easier just to leave it at the defaults.

Setting up the build environment

Open up a PowerShell terminal and enter the following commands. Note that the paths can be changed to whatever you want, but you'll have to update all the scripts to match.

mkdir c:\source\gaffercd c:\source\gaffergit clone -b 1.5_maintenance https://github.com/GafferHQ/gaffer.git .

Next, download the attached bhgc_gaffer_build.zip archive and extract all the files to c:\source\gaffer.

Back in your PowerShell terminal, type:

./install_deps

This will download the official pre-compiled Gaffer dependencies and extract them to c:\source\gaffer-build.

After that finishes, open c:\source\gaffer\gaffer-build.cmd in any text editor and change C:\Users\Brian\AppData\Local\Programs\Microsoft VS Code\bin to point to your VS Code installation folder. Most likely all you'll have to do is replace Brian with your username.

Back in PowerShell, type:

./gaffer-build

This launches a VS Code editor with all the required Gaffer build environment variables. Open c:\source\gaffer\gaffer.code-workspace to load all the source code.

The final configuration step is to open the terminal within VS Code and type:

python -m pip install Scons

We're ready to build!

Building Gaffer

Still in the VS Code terminal, type:

scons -j 8 build BUILD_TYPE=RELEASE OPTIONS=.github\workflows\main\sconsOptions

You can replace the 8 with however many CPU cores you want to use. It's a pretty quick build; with 8 cores on my laptop it takes maybe 10-15 minutes tops.

The terminal will show the progress of the build. When it's done, you'll be able to launch Gaffer by running c:\source\gaffer-build\bin\gaffer.cmd.

With a little bit of luck it will work on the first try! Whenever you make changes to the source code all you have to do is run the last scons command again. It will skip all unchanged code and just update what needs updating. It's often possible to make changes in a file or two and have a new working build in a few seconds.

Good luck and have fun!