Building Gaffer

Note : These are Shingo Takagi's personal build instructions, and do contain more steps than are necessary for a basic build, and some personal working preferences that are not essential. For instance, there is no real requirement to use Eclipse to build Gaffer, or to download Cortex or Arnold or 3delight. We encourage first-time visitors to use the simpler standard build instructions in our README before concerning themselves with the additional detail here. We are keen to improve our standard build instructions if they prove insufficient though, so please feel free to suggest improvements.

Table of Contents

• Assumptions
• Create an Environment Setup Script
• Install Eclipse
• Install the 3Delight Renderer
• Install the Arnold Renderer
• Install the Gaffer Dependencies
• Build and Install Git
• Clone the Gaffer Repository
• Clone the Cortex Repository
• Build and Install Scons
• Building Gaffer
• Running Gaffer
• Setup Eclipse
• Next Steps

Assumptions

This is my example setup to build or develop code specifically for the Gaffer project on CentOS Linux 7. It doesn't cover modifying other dependent projects like Cortex. I will assume that you already have a GitHub account. It's pretty painless to sign up for GitHub.

• I will refer to your Linux username as USER, and your GitHub username as GITHUB_USER.
• Create the following directories.
  • /home/${USER}/dev
    • We will refer to this as DEV_ROOT.
    • We'll be unpacking and building tools like git in here.
  • /home/${USER}/gaffer-dev
    • We will refer to this as GAFFER_DEV_ROOT.
    • We'll be unpacking and building code related to Gaffer in here.
  • /home/${USER}/apps
    • We will refer to this as APPS_ROOT.
    • We'll be installing pre-built applications in here.

Create an Environment Setup Script

• We will use a bash script to set up a number of environment variables for us.
  • This will allow us to build and run binaries which are yet to be built and installed below.
• Create a text file in GAFFER_DEV_ROOT called dev_setup.sh.
  • Add the following bash code to it and save it.

dev_setup.sh contents

# Setup Eclipse environment.
alias eclipse="/home/${USER}/apps/eclipse/eclipse"

# Setup 3Delight environment.
unset DELIGHT
source /home/${USER}/apps/3delight-12.0.19/.3delight_bash

# Setup Arnold environment.
PATH=":/home/${USER}/apps/arnold-4.2.11.0/bin:${PATH}"
PYTHONPATH=":/home/${USER}/apps/arnold-4.2.11.0/python:${PYTHONPATH}"
LD_LIBRARY_PATH=":/home/${USER}/apps/arnold-4.2.11.0/bin:${LD_LIBRARY_PATH}"
LDFLAGS=" -L/home/${USER}/apps/arnold-4.2.11.0/bin ${LDFLAGS}"

# Setup Git environment.
PATH=":/home/${USER}/dev/local/git-2.5.0/libexec/git-core:/home/${USER}/dev/local/git-2.5.0/bin:${PATH}"
LD_LIBRARY_PATH=":/home/${USER}/dev/local/git-2.5.0/lib64:${LD_LIBRARY_PATH}"

# Setup Gaffer environment.
PATH=":/home/${USER}/gaffer-dev/gafferDependencies-0.19.0.0-linux/bin:${PATH}"
LD_LIBRARY_PATH=":/home/${USER}/gaffer-dev/gafferDependencies-0.19.0.0-linux/lib:${LD_LIBRARY_PATH}"
LDFLAGS=" -L/home/${USER}/gaffer-dev/gafferDependencies-0.19.0.0-linux/lib ${LDFLAGS}"

# Alias to build gaffer. 
alias build_gaffer="scons BUILD_DIR=/home/${USER}/gaffer-dev/gafferDependencies-0.19.0.0-linux RMAN_ROOT=/home/${USER}/apps/3delight-12.0.19/Linux-x86_64 ARNOLD_ROOT=/home/${USER}/apps/arnold-4.2.11.0"

• Finally I will assume you have sourced the dev_setup.sh script. To source this script, simply type the following in a shell. All of the steps below assume that we are working from this shell.

source /home/${USER}/gaffer-dev/dev_setup.sh

Install Eclipse

• I use the latest C++ version of eclipse for Linux (64 bit), which is (mars-1) eclipse-cpp-mars-1-linux-gtk-x86_64.tar.gz. Other versions will also work.
• This can be downloaded from www.eclipse.org.
• Installing it is just a matter of unpacking it into APPS_ROOT.

tar -xzvf eclipse-cpp-mars-1-linux-gtk-x86_64.tar.gz -C /home/${USER}/apps

• In APPS_ROOT/eclipse there will be a file called eclipse.ini, you can increase the memory allocation settings for eclipse by editing this file. Currently I use the following settings.

-XX:MaxPermSize=4G
-Xms4G
-Xmx12G

Install the 3Delight Renderer

• Download the latest version of 3Delight Studio Pro from www.3delight.com.
  • 3Delight offers one free license per customer.
• The latest version is currently 3delight-12.0.19-Linux-x86_64.tar.xz.
• Go to the directory containing the downloaded file and unpack it by typing:

tar -xxvf 3delight-12.0.19-Linux-x86_64.tar.xz

• Install it by typing:

cd 3delight-12.0.19-Linux-x86_64
./install --prefix /home/${USER}/apps

Install the Arnold Renderer

• Download the latest version of Arnold SDK from www.solidangle.com.
  • Solid Angle offers one trial license per customer. It doesn't expire but it places a watermark on rendered images after 15 days.
• The latest version is currently Arnold-4.2.11.0-linux.tgz.
• Go to the directory containing the downloaded file and install it by typing:

mkdir -p /home/${USER}/apps/arnold-4.2.11.0
tar -xzvf Arnold-4.2.11.0-linux.tgz -C /home/${USER}/apps/arnold-4.2.11.0

Install the GafferDependencies

• Download the latest prebuilt gaffer dependencies from the gafferDependencies project.
  • Currently the latest version is gafferDependencies-0.19.0.0-linux.tar.gz.
• Go to the directory containing the downloaded file and install it by typing.

tar -xzvf gafferDependencies-0.19.0.0-linux.tar.gz  -C /home/${USER}/gaffer-dev

Build and Install Git

• I use Git version 2.5.0. But more recent versions will also work.
• Download the source code tarball, git-2.5.0.tar.gz, from git-scm.com.
• Go to the directory containing the downloaded file and install it by typing:

tar -xzvf git-2.5.0.tar.gz -C /home/${USER}/dev
cd /home/${USER}/dev/git-2.5.0
./configure --prefix=/home/${USER}/dev/local/git-2.5.0
make install

Clone the Gaffer Repository

• Fork the ImageEngine/gaffer repository with your GitHub account.

  • Simply log into your GitHub account and then navigate to the ImageEngine/gaffer repository.
  • In the top right area of the page you should see a button labelled "Fork". Click it.
  • Now when you navigate to your GitHub profile page, you will see the gaffer project listed under your "Popular Repositories".

• Locally clone your fork of gaffer to your machine.

  • In your browser navigate to your gaffer fork, GITHUB_USER/gaffer, and copy the clone URL. It will look something like this: https://github.com/GITHUB_USER/gaffer.git
  • In your shell navigate to a directory where you'd like to clone the repo.
  • Source the environment script created above again. This will ensure that we use the recently installed git version.

source /home/${USER}/gaffer-dev/dev_setup.sh

• Now clone your fork of gaffer by typing:

cd /home/${USER}/gaffer-dev
git clone https://github.com/GITHUB_USER/gaffer.git

Clone the Cortex Repository

• When building Gaffer we will be linking to the pre-built Cortex libraries in the gafferDependencies project installed above. However for eclipse C++ parsing, I also like to download the Cortex source code. The steps are similar to gaffer described above. You can fork the ImageEngine/cortex repo, and then clone that fork locally.
• However because I don't modify cortex, I just clone the ImageEngine/cortex repo directly. You can clone it directly as follows:

cd /home/${USER}/gaffer-dev
git clone https://github.com/ImageEngine/cortex.git

Build and Install Scons

• I use Scons version 2.4.1. But other versions will also work.
• Download the source code tarball, scons-2.4.1.tar.gz, from http://www.scons.org/.
• Make sure to source the dev_setup.sh environment script create above. This will ensure that when we type python in the terminal, we will pick up the python binaries in our gafferDependencies directory, installed above.

source /home/${USER}/gaffer-dev/dev_setup.sh

• Goto to directory with the downloaded file and unpack it by typing the following:

tar -xzvf scons-2.4.1.tar.gz -C /home/${USER}/gaffer-dev

• Install it directly into the python directories inside the gafferDependencies directory, by typing the following.

cd /home/${USER}/gaffer-dev/scons-2.4.1
python setup.py install

Building Gaffer

• Make sure you have sourced the dev_setup.sh environment script by typing the following:

source /home/${USER}/gaffer-dev/dev_setup.sh

• Now we can navigate to the gaffer source directory and build it by typing the following. This will install the gaffer binaries directly into the gafferDependencies directory. (Adjust the jobs parameter to equal the number of cores you have on your machine.) Note we are using the build_gaffer alias which was declared in the above dev_setup.sh environment script.

build_gaffer build --jobs=10

• At a later time you may want to clean out the binaries from you gaffer build, in order to perform another clean build. To clean out the binaries, simply type the following.

build_gaffer -c

Running Gaffer

• Make sure you have sourced the dev_setup.sh environment script by typing the following:

source /home/${USER}/gaffer-dev/dev_setup.sh

• Navigate to the gafferDependencies bin directory and run gaffer by typing the following.

cd /home/${USER}/gaffer-dev/gafferDependencies-0.19.0.0-linux
./gaffer

• If you see the gaffer ui appear, then you have successfully built gaffer. Congrats!

Setup Eclipse

• Symlink the cortex source into the gaffer source directory, by typing the following:

ln -s /home/${USER}/gaffer-dev/cortex/ /home/${USER}/gaffer-dev/gaffer/cortex

• Start eclipse by typing the following:

eclipse

• Choose a directory for the eclipse workspace. The following is an example.

/home/${USER}/dev/eclipse_workspaces/gaffer

• Create a project with File->New->Make File Project with Existing Code.
• Choose the Linux GCC toolchain.
• Choose /home/${USER}/gaffer-dev/gaffer as the existing code location.
• Now we need to setup the include directories, so that eclipse can index the C++ code properly.
  • Navigate to the panel containing all our include settings.
    • Goto the Properties for gaffer by right clicking the top level folder and selecting Properties.
    • On the left navigate to C/C++ General/Paths and Symbols.
    • On the right panel, in the includes tab, select GNU C++.
  • Now we can setup our workspace includes.
    • Even further to the right, click on Add.... Then in the popup click on Workspace.... Then choose gaffer/include. Click OK. And Click OK again.
    • Repeat the prevous step again, but choose gaffer/cortex/include.
  • Now we can setup our filesystem includes.
    • Click on Add.. again. Then in the popup click on File System.... Then choose /home/${USER}/gaffer-dev/gafferDependencies-0.19.0.0-linux/include. Click OK. And Click OK again.
    • Repeat the previous step again, but choose /home/${USER}/gaffer-dev/gafferDependencies-0.19.0.0-linux/appleseed/include.
    • Repeat the previous step again, but choose /home/${USER}/apps/arnold-4.2.11.0/include.
    • Repeat the previous step again, but choose /home/${USER}/apps/3delight-12.0.19/Linux-x86_64/include
  • Exit the Properties for gaffer dialog by clicking the OK button.
    • Choose "yes" when it to rebuild the index for the project.
    • Note, you can rebuild the index for the project at any time by right clicking on the top level directory for the project and selecting Index->Rebuild.
• After the indexing is complete, you should be able to navigate and refactor the C++ code with ease. The internet contains a lot of information on eclipse's C++ refactoring and navigation features.

Next Steps

• You should now be able to modify and refactor the C++ code with eclipse, build it, and also execute the gaffer binary.
• At this point you'll want to get familiar with git practices. GitHub has some nice documentation on these topics.
  • How do I work with branches?
  • How can I submit a pull request?
  • How can I submit multiple pull requests properly?
  • How can I update my forked repositories?