Required

• CMake version 3.14

Optional OpenSubdiv::Osd Dependencies

• OpenGL
• Metal
• CUDA
• TBB
• OpenCL
• DX11 SDK

Optional Interactive Example Dependencies

• GLFW (for OpenGL example viewers and some regression tests)
• Ptex (for Ptex example viewers)
• Zlib (for Ptex example viewers)

Optional Documentation Dependencies

• Doxygen (for C++ API documentation)
• Docutils (for reStructuredText documentation)
• Python Pygments (for reStructuredText documentation styling)

Useful Build Options

The following configuration arguments can be passed to the CMake command line.

-DCMAKE_BUILD_TYPE=[Debug|Release]

-DCMAKE_INSTALL_PREFIX=[base path to install OpenSubdiv (default: Current directory)]
-DCMAKE_LIBDIR_BASE=[library directory basename (default: lib)]
-DCMAKE_SYSTEM_NAME=[target system name for cross-compilation builds, e.g. iOS]

-DCMAKE_PREFIX_PATH=[semicolon-separated list of directories specifying installation prefixes to be searched by the find_package() command (default: empty list)]

-DCUDA_SDK_ROOT_DIR=[path to CUDA]
-DCUDA_TOOLKIT_ROOT_DIR=[path to CUDA]
-DOSD_CUDA_NVCC_FLAGS=[CUDA options, e.g. --gpu-architecture]

-DGLFW_LOCATION=[path to GLFW for OpenGL example viewers]
-DPTEX_LOCATION=[path to Ptex for Ptex example viewers]
-DICC_LOCATION=[path to Intel's C++ Studio XE]

-DNO_LIB=1        // disable the opensubdiv libs build (caveat emptor)
-DNO_EXAMPLES=1   // disable examples build
-DNO_TUTORIALS=1  // disable tutorials build
-DNO_REGRESSION=1 // disable regression tests build
-DNO_PTEX=1       // disable Ptex examples
-DNO_DOC=1        // disable documentation build
-DNO_OMP=1        // disable OpenMP
-DNO_TBB=1        // disable TBB
-DNO_CUDA=1       // disable CUDA
-DNO_OPENCL=1     // disable OpenCL
-DNO_CLEW=1       // disable OpenCL loader library
-DNO_OPENGL=1     // disable OpenGL
-DNO_METAL=1      // disable Metal

-DOSD_PATCH_SHADER_SOURCE_GLSL=1  // GLSL Patch Shader Source
-DOSD_PATCH_SHADER_SOURCE_HLSL=1  // HLSL Patch Shader Source
-DOSD_PATCH_SHADER_SOURCE_MSL=1   // MSL Patch Shader Source

Environment Variables

The paths to GLFW, Ptex, Zlib, and other dependencies can also be specified through the following environment variables:

GLFW_LOCATION, PTEX_LOCATION, ZLIB_ROOT

Automated Script

The GUI solution will probably become a burden for active developpers who tend to re-run the configuration step fairly often. A scripted solution can save a lot of time. Here is a typical workflow:

git clone https://github.com/PixarAnimationStudios/OpenSubdiv.git <folder>
cd <folder>
source cmake_setup

Where cmake_setup is a configuration script.

Here is an example CMake configuration script for a full typical windows-based build that can be run in GitShell :

echo "*** Removing build"
rm -rf buildDir instDir
echo "*** Running cmake"
cmake -B buildDir \
      -D CMAKE_INSTALL_PREFIX=instDir \
      -G "Visual Studio 16 2019" -A x64 \
      -D "GLFW_LOCATION=C:\path\to\glwf" \
      -S .

Here is a similar script for *Nix-based platforms:

echo "*** Removing build"
rm -rf buildDir instDir
echo "*** Running cmake"
cmake -B buildDir \
      -D CMAKE_INSTALL_PREFIX=instDir \
      -D "GLFW_LOCATION=/path/to/glfw" \
      -S .

Here is a similar script for macOS:

echo "*** Removing build"
rm -rf buildDir instDir
echo "*** Running cmake"
cmake -B buildDir \
      -D CMAKE_INSTALL_PREFIX=instDir \
      -G Xcode \
      -D "GLFW_LOCATION=/path/to/glfw" \
      -S .

Here is a similar script for iOS:

Use CMAKE_SYSTEM_NAME to have CMake use the appropriate cross-compilation toolchain when building for iOS.

echo "*** Removing build"
rm -rf buildDir instDir
echo "*** Running cmake"
SDKROOT=$(xcrun --sdk iphoneos --show-sdk-path)
cmake -B buildDir \
      -D CMAKE_INSTALL_PREFIX=instDir \
      -G Xcode \
      -D CMAKE_SYSTEM_NAME=iOS \
      -D NO_PTEX=1 -D NO_DOC=1 \
      -D NO_OMP=1 -D NO_TBB=1 -D NO_CUDA=1 -D NO_OPENCL=1 -D NO_CLEW=1 \
      -D NO_TUTORIALS=1 -D NO_EXAMPLES=1 -D NO_REGRESSION=1 -D NO_OPENGL=1 \
      -S .

Using Intel's C++ Studio XE

OpenSubdiv can be also be built with Intel's C++ compiler (icc). The default compiler can be overriden in CMake with the following configuration options:

-DCMAKE_CXX_COMPILER=[path to icc executable]
-DCMAKE_C_COMPILER=[path to icc executable]

The installation location of the C++ Studio XE can be overriden with:

-DICC_LOCATION=[path to Intel's C++ Studio XE]

Using Clang

CMake can also be overriden to use the clang compilers by configuring the following options:

-DCMAKE_CXX_COMPILER=clang++ \
-DCMAKE_C_COMPILER=clang \

Build Targets

Makefile-based builds allow the use of named target. Here are some of the more useful target names:

osd_<static|dynamic>_<CPU|GPU>

The core components of the OpenSubdiv libraries

<example_name>

Builds specific code examples by name (glViewer, ptexViewer...)

doc

Builds ReST and doxygen documentation

doc_html

Builds ReST documentation

doc_doxy

Builds Doxygen documentation