OpenVDB
6.2.1
|
CMake is a cross-platform family of tools designed to help build software. CMake doesn't actually build the project but instead generates the files required for your toolchain, for example makefiles that serve as input to GNU Make. Makefiles have historically been included in the OpenVDB distribution and until recently were the preferred means of building OpenVDB on UNIX platforms (see Building With Make below). But CMake support ensures a high level of flexibility and pre-compile verification to the build process, making it much easier to control and customize the installation process for a wider range of platforms.
CMake also makes it easier to automatically find and handle dependencies. As OpenVDB has a number of required and optional dependencies, it's recommended that new users to the software use the CMake build system over the Makefiles. If you're completely new to CMake, you may find it useful to read over the brief introduction to CMake and the CMake structure section below. However the build guide runs through the build process step by step.
CMake will configure a set of build files which represent the commands and dependencies for the OpenVDB components you wish to install. Finding and handling these dependencies on different platforms comprises the majority of the complexity involved in writing CMake. In general, software which uses CMake is expected to provide their own configuration files which dependent software will locate and use. Not all of OpenVDB's dependencies provide CMake support and therefore do not deploy with CMake configurations that OpenVDB can use. OpenVDB provides a set of FindModules
in the cmake
folder for finding these various dependencies e.g. FindBlosc.cmake
. These are designed such that they can theoretically be used by any project that needs to locate the given library and are invoked by the find_package()
call. For more information on FindModules and locating packages with CMake, see the following CMake documentation:
The other type of file provided by OpenVDB are OpenVDBSetupX.cmake
includes. These are primarily designed to configure the building of OpenVDB components against supported DCC's (Houdini/Maya) by locating their installations and setting various CMake variables for subsequent find_package()
dependency calls. They also represent packages which already provide their own CMake modules, but additionally provide the same input variable interface as OpenVDB's other Find
Modules.
Each CMake FindModule provides a description of the possible inputs which can be provided to help drive the search for OpenVDB dependencies (as well as the resulting outputs). They have been homogenized such that these variables follow a set convention, typically followed by most CMake projects. For a given FindModule e.g. FindBlosc.cmake
:
find_package( Xxx )
XXX_ROOT/include
and XXX_ROOT/lib
existUSE_SYSTEM_LIBRARY_PATHS
is enabled.There may be a situation where you use a package manager to install some dependencies, use a DCC such as Maya to provide others and manually build and install others from source. Care must be taken when providing CMake with these locations to ensure that the correct files are used. Incorrect use of the above variables can lead to difficult to diagnose build and runtime errors.
As an example, let's assume we have a manual installation of TBB (either through a Maya installation or a manual installation from source) and we want to use this with other dependencies installed through a package manager such as homebrew. As homebrew copies all headers and libraries it installs to a <homebrew>/include
<homebrew>/lib
directory structure, it can be tempting to set XXX_ROOT variables to points to the <homebrew>
folder. However you may already have an existing installation of TBB through your package manager, potentially installed by as a dependency of a completely unrelated piece of software. Whilst CMake may report to you the correct include/lib path, this can end up being hidden at compile time through these types of shared installations. You should not rely on the dependency order of the CMake build system - instead, it's important that you try to use the explicit directory paths where possible. For example homebrew will install each piece of software to <homebrew>/Cellar/<dep_name>/<dep_version>
, where the subsequent include and library directories can be passed to XXX_INCLUDEDIR and XXX_LIBRARYDIR respectively.
In summary try to stick to a single installation workflow and, if in doubt, provide direct include/lib paths to isolated software locations.
Blosc is one of the optional dependencies of all OpenVDB components. It is the only dependency which is enabled by default. The documented build steps below treat blosc as a required dependency. There are two reasons for this:
.vdb
files.vdb
files that were created using blosc compression. This includes OpenVDB files from Houdini.You can disable Blosc using -D USE_BLOSC=OFF
.
The following table lists all targets (mainly library and binary components) which can be built through the CMake build system. They can be set when using CMake from the command line with -D VAR=ON/OFF
or with a CMake gui:
Component | Description | CMake Variable | Default |
---|---|---|---|
OpenVDB Core Library | The Core OpenVDB shared/static library | OPENVDB_BUILD_CORE | ON |
OpenVDB Print | Command line binary for displaying information about OpenVDB files | OPENVDB_BUILD_BINARIES / OPENVDB_BUILD_VDB_PRINT | ON / ON |
OpenVDB LOD | Command line binary for generating volume mipmaps from an OpenVDB grid | OPENVDB_BUILD_BINARIES / OPENVDB_BUILD_VDB_LOD | ON / OFF |
OpenVDB Render | Command line binary for ray-tracing OpenVDB grids | OPENVDB_BUILD_BINARIES / OPENVDB_BUILD_VDB_RENDER | ON / OFF |
OpenVDB View | Command line binary for displaying OpenVDB grids in a GL viewport | OPENVDB_BUILD_BINARIES / OPENVDB_BUILD_VDB_VIEW | ON / OFF |
OpenVDB Python | Python module for OpenVDB C++ Python bindings | OPENVDB_BUILD_PYTHON_MODULE | ON |
OpenVDB UnitTests | OpenVDB's Unit Test suite | OPENVDB_BUILD_UNITTESTS | OFF |
OpenVDB Houdini Plugin | The OpenVDB Houdini shared library and OpenVDB Nodes | OPENVDB_BUILD_HOUDINI_PLUGIN | OFF |
OpenVDB Maya Plugin | The Maya OpenVDB Nodes | OPENVDB_BUILD_MAYA_PLUGIN | OFF |
Documentation | The OpenVDB doxygen documentation | OPENVDB_BUILD_DOCS | OFF |
The first step is to decide what type of OpenVDB build you're after. This primarily boils down to three main options:
Each option provides various benefits. Apart from the support for either the Houdini or Maya OpenVDB plugins, the latter two options can make it easier for new users to install the range of OpenVDB dependencies without having to worry about using a package manager or manually installing for source. You'll still be able to build and use all components of OpenVDB with these methods. However depending on the DCC (Digital Content Creation) software's version, you may find that some features of the Core library are restricted to ensure compatibility. For more information of building OpenVDB against a Houdini or Maya installation, see here.
Developers may wish to build a standalone version of OpenVDB to take advantage of newer dependencies and newer library features. See here for more information.
Note: Blosc is treated as a required dependency in these install instructions. See the blosc support section for more information.
Building against a DCC reduces the list of dependencies you need to provide. You should not mix between Houdini and Maya libraries and should not attempt to build the Maya plugin using Houdini libraries and vice-versa. Additionally, it's a good idea to read the above section on mixing dependency installations.
DCC | Supported Version | OpenVDB ABI |
---|---|---|
Houdini | 16.5 | 4 |
Houdini | 17.0 | 5 |
Houdini | 17.5 | 5 |
Maya | 2017 | Any |
Maya | 2018 | Any |
Maya | 2019 | Any |
Houdini ships with a number of libraries that OpenVDB requires. When downloading Houdini, take note of the file version information. The version you install will determine the compiler version you should try and use to build OpenVDB. For example, for Linux Houdini 17.5, with a file name of houdini-17.5.219-linux_x86_64_gcc6.3.tar.gz
, GCC 6.3 should be used. You will need to install some of the following dependencies depending on which OpenVDB components you wish to build.
Package | Description | OpenVDB Components |
---|---|---|
CMake | Cross-platform family of tools designed to help build software | All |
C++11 Compiler | Matching Houdini compiler and version | All |
Boost | Components: system, iostreams, python, thread | All |
CppUnit | A unit testing framework module for C++ | Unit Tests |
GLFW | Simple API for OpenGL development | OpenVDB View |
Doxygen | Documentation generation from C++ | Documentation |
Log4cplus | An optional dependency for improved OpenVDB Logging | Optional (All) |
NumPy | Scientific computing with Python | Optional (Python) |
At a minimum, boost, a matching C++11 compiler and CMake will be required. See the full dependency list for help with downloading and installing the above software. Note that as Blosc is provided as part of the Houdini installation USE_BLOSC
should be left ON
.
With the necessary dependencies installed, create and enter a directory for cmake to write to. It's generally useful to create this in the location you've extracted the OpenVDB repository. It will house CMake's generated build files.
Now you can call CMake by providing the absolute or relative path to the root of the OpenVDB source tree along with the following options:
Required:
/path/to/houdini/install
# Path to Houdini InstallON
# Force all components to build against HoudiniON
# Required for building the Houdini Plugin.Optional:
/path/to/install/dir
# The location you wish to install OpenVDB to. See the link for default values./path/to/install/dir
# The location to install the Houdini plugin to. Defaults to directories defined by Houdini:$ENV{HOME}/houdiniX.X
$ENV{HOME}/Library/Preferences/houdini/X.X
$ENV{HOMEDRIVE}$ENV{HOMEPATH}\Documents\houdiniX.X
ON
# Use the above default locations if OPENVDB_HOUDINI_INSTALL_PREFIX is not specified. If OFF
, uses the value of CMAKE_INSTALL_PREFIX./path/to/boost/install
# Path to boost. May not be required, CMake may find it automaticallyFor example on MacOS and where the build folder has been created inside the OpenVDB source root:
After the CMake build files have been successfully generated, run make within the build directory to compile the project, where the value of the j
argument is the number of CPU threads to use for a multi-threaded build.
Finally, once a successful build has completed, you can install all files.
See the troubleshooting section for help with CMake and Make errors.
Supported versions of maya only ship with TBB.
Package | Description | OpenVDB Components |
---|---|---|
CMake | Cross-platform family of tools designed to help build software | All |
C++11 Compiler | Matching Houdini compiler and version | All |
Boost | Components: system, iostreams, python, thread | All |
IlmBase | Used half precision floating points and EXR serialization support | All |
ZLIB | Compression library for disk serialization compression | All |
Blosc | Recommended dependency for improved disk compression | All* |
CppUnit | A unit testing framework module for C++ | Unit Tests |
GLFW | Simple API for OpenGL development | OpenVDB View |
Doxygen | Documentation generation from C++ | Documentation |
OpenEXR | EXR serialization support | Optional (Core) / OpenVDB Render |
Log4cplus | An optional dependency for improved OpenVDB Logging | Optional (All) |
NumPy | Scientific computing with Python | Optional (Python) |
See blosc support
At a minimum, boost, a matching C++11 compiler, IlmBase, ZLIB, blosc and CMake will be required. See the full dependency list for help with downloading and installing the above software.
With the necessary dependencies installed, create and enter a directory for cmake to write to. It's generally useful to create this in the location you've extracted the OpenVDB repository. It will house CMake's generated build files.
Now you can call CMake by providing the absolute or relative path to the root of the OpenVDB source tree along with the following options:
Required:
/path/to/maya/install
# Path to Maya InstallON
# Force all components to build against MayaOptional:
/path/to/install/dir
# The location you wish to install OpenVDB to. See the link for default values./path/to/install/dir
# The location to install the Maya plugin to. Defaults to the value of ${CMAKE_INSTALL_PREFIX}/maya${Maya_VERSION}
/path/to/boost/install
# Path to boost. May not be required, CMake may find it automatically/path/to/ilmbase/install
# Path to ilmbase.For example on MacOS and where the build folder has been created inside the OpenVDB source root:
As the Maya plugin is disabled by default, you may also want to add -D OPENVDB_BUILD_MAYA_PLUGIN=ON
to the command. The components section shows which targets are enabled by default.
After the CMake build files have been successfully generated, run make within the build directory to compile the project, where the value of the j
argument is the number of CPU threads to use for a multi-threaded build.
Finally, once a successful build has completed, you can install all files.
Note: The Maya OpenVDB Visualize Node is only compatible with Legacy OpenGL support. You can enable this in Maya by navigating to Windows->Settings/Preferences->Preferences->Display
and changing Rendering Engine
to OpenGL - Legacy.
See the troubleshooting section for help with CMake and Make errors.
It's recommended you first visit the dependency list page before attempting to run CMake on a standalone build. With the necessary dependencies installed, create and enter a directory for cmake to write to. It's generally useful to create this in the location you've extracted the OpenVDB repository. It will house CMake's generated build files.
Now you can call CMake by providing the absolute or relative path to the root of the OpenVDB source tree. Below are some common options you may want to provide:
/path/to/install/dir
# The location you wish to install OpenVDB to. See the link for default values./path/to/Xxx/
# Give CMake a path to where a package has been installed or simply to where your prefered package is installed if it cannot locate it.For example, a typical first attempt at generating the build files may look as follows:
See the components section to find which targets are available, their corresponding CMake flags and their default values.
After the CMake build files have been successfully generated, run make within the build directory to compile the project, where the value of the j
argument is the number of CPU threads to use for a multi-threaded build.
Finally, once a successful build has completed, you can install all files.
See the troubleshooting section for help with CMake and Make errors.
This section is for users wishing to use a build of OpenVDB in their own applications with CMake.
The following assumes that OpenVDB was installed with OPENVDB_BUILD_CORE=ON
and OPENVDB_INSTALL_CMAKE_MODULES=ON
. Don't worry if you didn't specify these options directly, they both default to ON
. This ensures that OpenVDB has installed the required CMake modules that your application will need to use.
Note: Typically, projects provide a Config-file rather than a Find-module for downstream use. OpenVDB currently provides a Find-module. This may change in the future. Further information here.
You can add the below CMake snippet to your main CMakeLists.txt
to bring in OpenVDB as a dependency:
myapp
in the above is a CMake target, usually created with add_library()
or add_executable()
. You can optionally provide CMAKE_MODULE_PATH
as a -D
argument to the cmake command line instead of specifying it in your CMakeLists.txt
.
Note that the FindOpenVDB.cmake
module relies on the other FindModules
provided in the OpenVDB installation to find it's own dependencies. This may require you to provide additional dependency locations for OpenVDB's dependencies. See Locating Dependencies or the below troubleshooting for more information.
Makefiles are provided for those not wishing to use the CMake build system. However, Make support is now deprecated and will be removed in a future release, so one should not expect the Makefiles to provide the same level of functionality as the CMake build system.
To build the core library, ensure that you have GNU Make version 4.1 or later, then proceed as follows:
Set values appropriate to your environment for the following variables at the top of openvdb/Makefile
:
INSTALL_DIR | the directory into which to install libraries, executables and header files (e.g., |
BOOST_INCL_DIR | the parent directory of the |
BOOST_LIB_DIR | the directory containing |
BOOST_LIB | linker flags for |
BOOST_THREAD_LIB | linker flags for |
ILMBASE_INCL_DIR | the parent directory of the |
ILMBASE_LIB_DIR | the directory containing |
ILMBASE_LIB | linker flags for |
HALF_LIB | linker flag(s) for the Half library (e.g., |
EXR_INCL_DIR | the parent directory of the Note: some OpenEXR headers incorrectly include other OpenEXR headers with, e.g., |
EXR_LIB_DIR | the directory containing |
EXR_LIB | linker flags for |
TBB_INCL_DIR | the parent directory of the |
TBB_LIB_DIR | the directory containing |
TBB_LIB | linker flag(s) for the TBB library (e.g., |
BLOSC_INCL_DIR | the parent directory of the |
BLOSC_LIB_DIR | the directory containing |
BLOSC_LIB | linker flags for |
CONCURRENT_MALLOC_LIB_DIR | a directory containing a scalable, concurrent malloc replacement library such as jemalloc or TBB malloc |
CONCURRENT_MALLOC_LIB | linker flag(s) for the malloc replacement library |
CPPUNIT_INCL_DIR | the parent directory of the |
CPPUNIT_LIB_DIR | the directory containing |
CPPUNIT_LIB | linker flag(s) for the CppUnit library (e.g., |
GLFW_INCL_DIR | the directory containing |
GLFW_LIB_DIR | the directory containing |
GLFW_LIB | linker flags for the GLFW library (e.g., |
GLFW_MAJOR_VERSION | the major version number of the GLFW library |
LOG4CPLUS_INCL_DIR | the parent directory of the |
LOG4CPLUS_LIB_DIR | directory containing |
LOG4CPLUS_LIB | linker flags for the log4cplus library (e.g., |
PYTHON_VERSION | the version of Python (e.g., 2.7) for which to build the OpenVDB module (leave blank if Python is unavailable) |
PYTHON_INCL_DIR | the directory containing the |
PYCONFIG_INCL_DIR | the directory containing the |
PYTHON_LIB_DIR | the directory containing the Python library |
PYTHON_LIB | linker flags for the Python library (e.g., |
BOOST_PYTHON_LIB_DIR | the directory containing the Boost.Python library |
BOOST_PYTHON_LIB | linker flags for the Boost.Python library (e.g., |
NUMPY_INCL_DIR | the directory containing the NumPy |
EPYDOC | the path to the Epydoc executable (leave blank if Epydoc is unavailable) |
PYTHON_WRAP_ALL_GRID_TYPES | if set to " |
DOXYGEN | the path to the Doxygen executable (leave blank if Doxygen is unavailable) |
Note that if you plan to build the Houdini OpenVDB tools, you must build the OpenVDB library and the Houdini tools against compatible versions of the Boost, OpenEXR and TBB libraries. Until Houdini 16.5, all three were included in the HDK, so by default several of the variables above reference the Houdini environment variables $HDSO
, $HFS
and $HT
(source the houdini_setup
script provided with your Houdini installation to set those environment variables). As of Houdini 16.5, you must provide your own installation of Boost.
Also note that certain new features in OpenVDB (see the Release Notes for details) necessitated changes to the ABI of the Grid class, rendering it incompatible with earlier versions of the library, such as the ones built into Houdini. Passing grids between native VDB nodes in a scene graph and nodes built against the new ABI will lead to crashes, so to use OpenVDB with Houdini 16.5 set abi=4
to compile with the incompatible features disabled.
To build the OpenVDB Python module, you will need local installations of Python, Boost.Python, and optionally NumPy. Houdini ships with Python 2 but not with the libboost_python
library or with NumPy or, as of Houdini 16.5, with the Boost.Python headers, so both Boost.Python and NumPy have to be built separately. Point the variables $(BOOST_PYTHON_LIB_DIR)
, $(BOOST_PYTHON_LIB)
and $(NUMPY_INCL_DIR)
to your local installations of those libraries.
From the top-level openvdb/
directory, type "make
" (or "make -s
" for less verbose output) to locally build the library and commands. The Makefile supports parallel builds (e.g. "make -j 8
").
A default local build generates the following libraries and executables (but see the Makefile for additional targets and build options):
openvdb/libopenvdb.so.X.Y.Z | the OpenVDB library |
openvdb/libopenvdb.so | symlink to libopenvdb.so.X.Y.Z |
openvdb/pyopenvdb.so | the OpenVDB Python module (if Python and Boost.Python are available) |
openvdb/vdb_print | command-line tool that prints info about OpenVDB .vdb files |
openvdb/vdb_render | command-line tool that ray-traces OpenVDB volumes |
openvdb/vdb_test | unit test runner for libopenvdb (if CppUnit is available) |
From the openvdb/
directory, type "make test
" to run the unit tests and verify that the library is working correctly. (Alternatively, once the library has been installed, run the unit test executable directly with "./vdb_test
", or "./vdb_test -v
" for more verbose output.) Type "make pytest
" to run the Python module unit tests.
From the openvdb/
directory, type "make doc
" (or "make -s doc
") to generate HTML library documentation, then open the file openvdb/doc/html/index.html
in a browser. Type "make pydoc
" (or "make -s pydoc
") to generate HTML Python module documentation, then open openvdb/doc/html/python/index.html
in a browser.
Optionally (if OpenGL and GLFW are available), from the top-level openvdb/
directory, type "make vdb_view
" (or "make -s vdb_view
") to locally build the OpenVDB viewer tool. Then type "./vdb_view
" for usage information.
openvdb/
directory, type "make install
" (or "make -s install
") to copy generated files into the directory tree rooted at $(INSTALL_DIR)
. To build the Houdini and Maya plugins the process is similar, but see the Makefiles in the openvdb_
houdini/
and openvdb_
maya/
directories for additional requirements
If after reading this guide you're unable to find your specific issue below, please get in touch with the OpenVDB TSC.
Note: If running into issues when changing CMake settings/dependency paths, try clearing the designated CMake build directory and running your cmake
command again.
It's fairly typical that CMake may fail to find some dependencies on first runs, especially if you've manually compiled from source your own dependencies. Analyzing any dependency errors will help with running further invocations of cmake. The Locating Dependencies section details the variable format required to point CMake to the correct locations. Alternatively, with interactive cmake systems such as ccmake
or CMake GUI, variables which are not found will be shown, allowing you to provide them directly.
As an example, earlier versions of Threading Building Blocks (TBB) do not come with CMake modules or pkg-config modules. For OpenVDB to locate TBB, you typically need to provide this location manually:
Note that this is also equivalent to:
By default, OpenVDB sets a number of minimum version requires for its dependencies. These can be found in the root CMakeList.txt or in the dependency table. These minimum versions either track the oldest supported VFX Reference Platform or are otherwise required for compatibility. Although not recommended, you can bypass these checks with -D DISABLE_DEPENDENCY_VERSION_CHECKS=ON
if necessary. Note that using older or untested dependencies may produce undesired behavior. Older versions in particular are not supported by OpenVDB.
Note: Boost will produce a version error in the format Detected version of Boost is too old.