CMake/Documentation/Python/CI fixes and improvements

.github/workflows/ax.yml

@@ -69,7 +69,7 @@ jobs:
           -j ${{ matrix.config.j }}
           --build-type=${{ matrix.config.build }}
           --components=${{ matrix.config.components }}
-          --cargs="-DOPENVDB_CXX_STRICT=ON"
+          --cargs=\"-DOPENVDB_CXX_STRICT=ON -DUSE_EXPLICIT_INSTANTIATION=OFF\"
       - name: clean
         if: matrix.config.components == 'core'
         run: rm -rf build
@@ -80,7 +80,7 @@ jobs:
           -j ${{ matrix.config.j }}
           --build-type=${{ matrix.config.build }}
           --components="axcore,axbin,axtest"
-          --cargs="-DOPENVDB_CXX_STRICT=ON"
+          --cargs=\"-DOPENVDB_CXX_STRICT=ON -DUSE_EXPLICIT_INSTANTIATION=OFF\"
       - name: test
         run: cd build && ctest -V
       - name: test_doxygen_examples
@@ -114,7 +114,7 @@ jobs:
           ./ci/build.sh -v
           --build-type=${{ matrix.config.build }}
           --components="core,axcore,axbin,axtest"
-          --cargs="-DLLVM_DIR=/usr/local/opt/llvm@${{ matrix.config.llvm }}/lib/cmake/llvm"
+          --cargs=\"-DLLVM_DIR=/usr/local/opt/llvm@${{ matrix.config.llvm }}/lib/cmake/llvm -DUSE_EXPLICIT_INSTANTIATION=OFF\"
       - name: test
         run: cd build && ctest -V
       - name: test_doxygen_examples

.github/workflows/nanovdb.yml

@@ -74,6 +74,7 @@ jobs:
           --build-type=${{ matrix.config.build }}
           --components=core,nano,nanotest,nanoexam,nanobench,nanotool
           --cargs=\'
+          -DUSE_EXPLICIT_INSTANTIATION=OFF
           -DNANOVDB_USE_CUDA=ON
           -DNANOVDB_USE_OPENVDB=ON
           -DCMAKE_INSTALL_PREFIX=`pwd`
@@ -124,6 +125,7 @@ jobs:
         --config=${{ matrix.config.build }}
         --components=core,nano,nanotest,nanoexam,nanobench,nanotool
         --cargs=\'${{ matrix.config.cmake }}
+        -DUSE_EXPLICIT_INSTANTIATION=OFF
         -DNANOVDB_USE_CUDA=ON
         -DNANOVDB_USE_OPENVDB=ON
         -DVCPKG_TARGET_TRIPLET=${VCPKG_DEFAULT_TRIPLET}
@@ -158,7 +160,7 @@ jobs:
           ./ci/build.sh -v
           --build-type=${{ matrix.config.build }}
           --components=core,nano,nanotest,nanoexam,nanobench,nanotool
-          --cargs=\'-DNANOVDB_USE_CUDA=OFF -DNANOVDB_USE_OPENVDB=ON\'
+          --cargs=\'-DUSE_EXPLICIT_INSTANTIATION=OFF -DNANOVDB_USE_CUDA=OFF -DNANOVDB_USE_OPENVDB=ON\'
       - name: test
         run: cd build && ctest -V
 
@@ -179,6 +181,6 @@ jobs:
           cd nanovdb/nanovdb
           sudo mkdir .build
           cd .build
-          sudo cmake -DNANOVDB_BUILD_UNITTESTS=ON ../
+          sudo cmake -DUSE_EXPLICIT_INSTANTIATION=OFF -DNANOVDB_BUILD_UNITTESTS=ON ../
           sudo make -j2 install
           sudo ctest -V

.github/workflows/weekly.yml

@@ -274,7 +274,7 @@ jobs:
           -j ${{ matrix.config.j }}
           --build-type=${{ matrix.config.build }}
           --components=${{ matrix.config.components }}
-          --cargs="-DOPENVDB_CXX_STRICT=ON"
+          --cargs=\"-DUSE_EXPLICIT_INSTANTIATION=OFF -DOPENVDB_CXX_STRICT=ON\"
       - name: clean
         if: matrix.config.components == 'core'
         run: rm -rf build
@@ -285,7 +285,7 @@ jobs:
           -j ${{ matrix.config.j }}
           --build-type=${{ matrix.config.build }}
           --components="axcore,axbin,axtest"
-          --cargs="-DOPENVDB_CXX_STRICT=ON"
+          --cargs=\"-DUSE_EXPLICIT_INSTANTIATION=OFF -DOPENVDB_CXX_STRICT=ON\"
       - name: test
         run: cd build && ctest -V
       - name: test_doxygen_examples
@@ -316,7 +316,7 @@ jobs:
           ./ci/build.sh -v
           --build-type=${{ matrix.config.build }}
           --components="core,axcore,axbin,axtest"
-          --cargs="-DLLVM_DIR=/usr/local/opt/llvm@${{ matrix.config.llvm }}/lib/cmake/llvm"
+          --cargs=\"-DUSE_EXPLICIT_INSTANTIATION=OFF -DLLVM_DIR=/usr/local/opt/llvm@${{ matrix.config.llvm }}/lib/cmake/llvm\"
       - name: test
         run: cd build && ctest -V
       - name: test_doxygen_examples

CHANGES

@@ -3,9 +3,19 @@ OpenVDB Version History
 
 Version 9.0.0 - October 29, 2021
 
+      This version introduces ABI changes relative to older major releases,
+      so to preserve ABI compatibility it might be necessary to define the
+      macro OPENVDB_ABI_VERSION_NUMBER=N, where, for example, N is 7 for
+      Houdini 18.5 and 8 for Houdini 19.0.
+
+      Official release of NanoVDB, which for the first time offers GPU support
+      for static sparse volumes in OpenVDB.
+
     New features:
-    - NanoVDB, which for the first time offers GPU support for static sparse
-      volumes in OpenVDB.
+    - Faster build times from support for explicit template instantiation,
+      which is enabled by default for most of the tools.
+    - Added support for OpenEXR 3 and TBB 2021.
+    - Added transient data to the RootNode, InternalNode, and LeafNode.
 
     Improvements:
     - Added tools::countActiveLeafVoxels(), tools::countInactiveVoxels(),

CMakeLists.txt

@@ -141,7 +141,8 @@ option(OPENVDB_USE_FUTURE_ABI_10 "Bypass future ABI check" OFF)
 option(OPENVDB_FUTURE_DEPRECATION "Generate messages for upcoming deprecation" ON)
 option(OPENVDB_ENABLE_UNINSTALL "Adds a CMake uninstall target." ON)
 option(USE_COLORED_OUTPUT "Always produce ANSI-colored output (GNU/Clang only)." OFF)
-option(USE_PKGCONFIG "Use pkg-config to search for dependent libraries." ON)
+cmake_dependent_option(USE_PKGCONFIG "Use pkg-config to search for dependent libraries." ON "NOT WIN32" OFF)
+
 option(USE_EXPLICIT_INSTANTIATION "Use explicit instantiation for all supported classes and methods against a
 pre-defined list of OpenVDB trees. This makes the core library larger and slower to compile, but speeds up
 the compilation of all dependent code by bypassing the expensive template instantation." ON)
@@ -208,9 +209,6 @@ if(USE_AX)
   endif()
 endif()
 
-# Top-level location for all openvdb headers
-set(OPENVDB_INSTALL_INCLUDEDIR "${CMAKE_INSTALL_INCLUDEDIR}/openvdb")
-
 ###### Deprecated options
 
 if(OPENVDB_BUILD_HOUDINI_SOPS)
@@ -245,12 +243,8 @@ mark_as_advanced(
 
 # Configure minimum version requirements - some are treated specially and fall
 # outside of the DISABLE_DEPENDENCY_VERSION_CHECKS catch
-
 set(MINIMUM_CXX_STANDARD 14)
 
-# @note  Blosc version is currently treated as exception which must be adhered
-# to. The minimum version must be at least 1.5.0. Previous versions are incompatible.
-set(MINIMUM_BLOSC_VERSION 1.5.0)
 # @note  ABI always enforced so the correct deprecation messages are available.
 # OPENVDB_USE_DEPRECATED_ABI_<VERSION> should be used to circumvent this
 set(MINIMUM_OPENVDB_ABI_VERSION 6)
@@ -270,6 +264,7 @@ if(NOT DISABLE_DEPENDENCY_VERSION_CHECKS)
   set(MINIMUM_ZLIB_VERSION 1.2.7)
   set(MINIMUM_TBB_VERSION 2019.0)
   set(MINIMUM_LLVM_VERSION 7.0.0)
+  set(MINIMUM_BLOSC_VERSION 1.5.0)
 
   set(MINIMUM_PYTHON_VERSION 2.7) # @warning should be 3.7.x, but H18.5+ can still be used with 2.7.x
   set(MINIMUM_NUMPY_VERSION 1.14.0)
@@ -291,6 +286,7 @@ set(FUTURE_MINIMUM_GCC_VERSION 9.3.1)
 set(FUTURE_MINIMUM_ICC_VERSION 19)
 # set(FUTURE_MINIMUM_MSVC_VERSION 19.10)
 
+# set(FUTURE_MINIMUM_CMAKE_VERSION 3.18)
 # set(FUTURE_MINIMUM_ILMBASE_VERSION 2.4)
 # set(FUTURE_MINIMUM_OPENEXR_VERSION 2.4)
 set(FUTURE_MINIMUM_BOOST_VERSION 1.73)
@@ -552,6 +548,7 @@ if(USE_STATIC_DEPENDENCIES)
 endif()
 
 # Configure OpenVDB Library and ABI versions
+
 set(NEEDS_OPENVDB OFF)
 
 if(OPENVDB_BUILD_AX OR

CODEOWNERS

@@ -23,6 +23,9 @@ CHANGES                                                     @kmuseth @apradhana
 # OpenVDB AX
 /openvdb_ax/                                                @idclip @richhones
 
+# NanoVDB
+/nanovdb/                                                   @kmuseth
+
 # OpenVDB Houdini - Default
 /openvdb_houdini/                                           @kmuseth
 

README.md

@@ -33,44 +33,42 @@ OpenVDB welcomes contributions to the OpenVDB project. Please refer to the [cont
 
 ### Developer Quick Start
 
-The following provides basic installation examples for the core OpenVDB library. Other components, such as the python module, OpenVDB AX and various executables, may require additional dependencies. See the [build documentation](https://academysoftwarefoundation.github.io/openvdb/build.html) for help with installations.
+The following provides basic installation examples for the core OpenVDB library. Other components, such as the python module, OpenVDB AX, NanoVDB and various executables, may require additional dependencies. See the [build documentation](https://academysoftwarefoundation.github.io/openvdb/build.html) for help with installations.
 
 #### Linux
 ##### Installing Dependencies (Boost, TBB, Blosc)
 
-```
+```bash
 apt-get install -y libboost-iostreams-dev
 apt-get install -y libboost-system-dev
 apt-get install -y libtbb-dev
 apt-get install -y libblosc-dev
 ```
 
 ##### Building OpenVDB
-```
+```bash
 git clone git@github.com:AcademySoftwareFoundation/openvdb.git
 cd openvdb
 mkdir build
 cd build
 cmake ..
-make -j4
-make install
+make -j4 && make install
 ```
 #### macOS
 ##### Installing Dependencies (Boost, TBB, Blosc)
-```
+```bash
 brew install boost
 brew install tbb
 brew install c-blosc
 ```
 ##### Building OpenVDB
-```
+```bash
 git clone git@github.com:AcademySoftwareFoundation/openvdb.git
 cd openvdb
 mkdir build
 cd build
 cmake ..
-make -j4
-make install
+make -j4 && make install
 ```
 #### Windows
 ##### Installing Dependencies (Boost, TBB, Blosc)
@@ -81,7 +79,7 @@ It is recommended to set the `VCPKG_DEFAULT_TRIPLET` environment variable to
 [Git](https://git-scm.com/downloads), [vcpkg](https://github.com/microsoft/vcpkg)
 and [CMake](https://cmake.org/download/) to be installed.
 
-```
+```bash
 vcpkg install zlib:x64-windows
 vcpkg install blosc:x64-windows
 vcpkg install tbb:x64-windows
@@ -93,7 +91,7 @@ vcpkg install boost-uuid:x64-windows
 vcpkg install boost-interprocess:x64-windows
 ```
 ##### Building OpenVDB
-```
+```bash
 git clone git@github.com:AcademySoftwareFoundation/openvdb.git
 cd openvdb
 mkdir build
@@ -102,48 +100,42 @@ cmake -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_VCPKG>\scripts\buildsystems\vcpkg.cmake -D
 cmake --build . --parallel 4 --config Release --target install
 ```
 
+#### Building OpenVDB AX
+
+OpenVDB AX depends on the core OpenVDB library. See the [build documentation](https://academysoftwarefoundation.github.io/openvdb/build.html) for all available AX component options:
+
+```bash
+git clone git@github.com:AcademySoftwareFoundation/openvdb.git
+cd openvdb
+mkdir build
+cd build
+cmake -DOPENVDB_BUILD_AX=ON ..
+make -j4 && make install
+```
+
 #### Building NanoVDB
 
-**First example: building NanoVDB and OpenVDB core**
-
-NanoVDB is now a module of the larger OpenVDB project. A user can build both libraries together. This will build the OpenVDB core library, install the NanoVDB header files, and build the NanoVDB command-line tools in the `build/nanovdb/cmd` directory. From the 'root' OpenVDB project directory (change the dependency paths to match your environment):
-  ```console
-  foo@bar:~$ mkdir build
-  foo@bar:~$ cd build
-  foo@bar:~$ cmake .. -DUSE_NANOVDB=ON -DTBB_ROOT=/path/to/tbb -DBOOST_ROOT=/path/to/boost -DBLOSC_ROOT=/path/to/blosc -DCMAKE_INSTALL_PREFIX=/install/path
-  foo@bar:~$ make -j 4 && make install
-  ```
-Note that the default value of `NANOVDB_USE_OPENVDB` is linked to `OPENVDB_BUILD_CORE` option and can be overriden by passing on `-DNANOVDB_USE_OPENVDB=OFF`. The `Boost` library is included because it is a requirement for building OpenVDB.
-
-In general, CMake will try to find every optional dependency when a user opts to add an additional dependency. Be sure to check the CMake log to see what dependencies were **not** found.
-
-**Second example: NanoVDB with no dependencies**
-
-From the 'root' OpenVDB project directory:
-  ```console
-  foo@bar:~$ mkdir build
-  foo@bar:~$ cd build
-  foo@bar:~$ cmake .. -DUSE_NANOVDB=ON -DOPENVDB_BUILD_CORE=OFF -DOPENVDB_BUILD_BINARIES=OFF -DNANOVDB_USE_TBB=OFF -DNANOVDB_USE_BLOSC=OFF -DNANOVDB_USE_ZLIB=OFF -DCMAKE_INSTALL_PREFIX=/install/path
-  foo@bar:~$ make -j 4 && make install
-  ```
-
-Another option is to build it from the NanoVDB directory itself, which is much simpler:
-  ```console
-  foo@bar:~$ cd nanovdb/nanovdb
-  foo@bar:~$ mkdir build
-  foo@bar:~$ cd build
-  foo@bar:~$ cmake .. -DCMAKE_INSTALL_PREFIX=/install/path
-  foo@bar:~$ make -j 4 && make install
-  ```
-Both options will install the NanoVDB header files to the `/install/path` as well as building `nanovdb_print` and `nanovdb_validate` executable. The path where these executables are installed will be different: in the first option they will be under `build/nanovdb/cmd` directory; whilst in the second option they will be under the `build/cmd/` directory.
-
-**Third example: build 'everything' in NanoVDB along with OpenVDB core**
-
-From the root OpenVDB directory:
-  ```console
-  foo@bar:~$ mkdir build
-  foo@bar:~$ cd build
-  foo@bar:~$ cmake .. -DUSE_NANOVDB=ON -DNANOVDB_BUILD_UNITTESTS=ON -DNANOVDB_BUILD_EXAMPLES=ON -DNANOVDB_BUILD_BENCHMARK=ON -DNANOVDB_USE_INTRINSICS=ON -DNANOVDB_USE_CUDA=ON -DNANOVDB_CUDA_KEEP_PTX=ON -DTBB_ROOT=/path/to/tbb -DBOOST_ROOT=/path/to/boost -DBLOSC_ROOT=/path/to/blosc -DGTEST_ROOT=/path/to/gtest -DCMAKE_INSTALL_PREFIX=/install/path
-  foo@bar:~$ make -j 4 && make install
-  ```
-Note that if you already have the correct version of OpenVDB pre-installed, you can configure CMake to link against that library by passing the arguments `-DOPENVDB_BUILD_CORE=OFF -DOPENVDB_BUILD_BINARIES=OFF -DOPENVDB_ROOT=/path/to/openvdb` when invoking `cmake`.
+NanoVDB can be built with and without OpenVDB support. To see full build instructions
+see the [NanoVDB build documentation](https://academysoftwarefoundation.github.io/openvdb/NanoVDB_HowToBuild.html)
+
+#### Building Without OpenVDB Support
+
+```bash
+git clone git@github.com:AcademySoftwareFoundation/openvdb.git
+cd openvdb/nanovdb/nanovdb  # Build from the subdirectory
+mkdir build
+cd build
+cmake ..
+make -j4 && make install
+```
+
+#### Building With OpenVDB Support
+
+```bash
+git clone git@github.com:AcademySoftwareFoundation/openvdb.git
+cd openvdb
+mkdir build
+cd build
+cmake -DOPENVDB_BUILD_NANOVDB=ON ..
+make -j4 && make install
+```

cmake/config/OpenVDBBuildTypes.cmake

@@ -153,7 +153,7 @@ add_compile_options("$<$<AND:$<CONFIG:ASAN>,$<COMPILE_LANG_AND_ID:CXX,GNU,Clang,
 add_compile_options("$<$<AND:$<CONFIG:ASAN>,$<COMPILE_LANG_AND_ID:CXX,GNU,Clang,AppleClang>>:-fno-omit-frame-pointer;-g;-O1>")
 add_compile_options("$<$<AND:$<CONFIG:ASAN>,$<COMPILE_LANG_AND_ID:CXX,Clang,AppleClang>>:-fsanitize-address-use-after-scope;-fno-optimize-sibling-calls>")
 # -fsanitize-address-use-after-scope added in GCC 7
-add_compile_options("$<$<AND:$<CONFIG:ASAN>,$<CXX_COMPILER_ID:GNU>,$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,7.0.0>>:-fsanitize-address-use-after-scope>")
+add_compile_options("$<$<AND:$<CONFIG:ASAN>,$<COMPILE_LANG_AND_ID:CXX,GNU>,$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,7.0.0>>:-fsanitize-address-use-after-scope>")
 add_link_options("$<$<AND:$<CONFIG:ASAN>,$<COMPILE_LANG_AND_ID:CXX,GNU,Clang,AppleClang>>:-fsanitize=address>")
 
 # LeakSanitizer

doc/build.txt

@@ -191,6 +191,10 @@ OpenVDB AX Library        | The OpenVDB AX library
 OpenVDB AX Binary         | Command line binary for running OpenVDB AX code                        | OPENVDB_BUILD_AX_BINARIES                         | OFF        |
 OpenVDB AX Grammar        | Allows for re-generation of AX grammar, typically not required         | OPENVDB_BUILD_AX_GRAMMAR                          | OFF        |
 OpenVDB AX Unit Tests     | OpenVDB AX's Unit Test suite                                           | OPENVDB_BUILD_AX_UNITTESTS                        | OFF        |
+NanoVDB                   | NanoVDB headers                                                        | OPENVDB_BUILD_NANOVDB                             | OFF        |
+NanoVDB Tools             | NanoVDB command line tools                                             | NANOVDB_BUILD_TOOLS                               | OFF        |
+NanoVDB Examples          | NanoVDB example binaries and benchmarks                                | NANOVDB_BUILD_EXAMPLES / NANOVDB_BUILD_BENCHMARK  | OFF / OFF  |
+NanoVDB Unit Tests        | NanoVDB Unit Test suite                                                | NANOVDB_BUILD_UNITTESTS                           | OFF        |
 Documentation             | The OpenVDB doxygen documentation                                      | OPENVDB_BUILD_DOCS                                | OFF        |
 
 
@@ -236,6 +240,7 @@ DCC      | Supported Version | OpenVDB ABI |
 -------- | ----------------- | ----------- |
 Houdini  | 18.0              | 6           |
 Houdini  | 18.5              | 7           |
+Houdini  | 19.0              | 8           |
 Maya     | 2017              | Any         |
 Maya     | 2018              | Any         |
 Maya     | 2019              | Any         |

doc/changes.txt

@@ -22,26 +22,12 @@ static sparse volumes in OpenVDB. See the
 for details.
 </BLOCKQUOTE>
 
-@par
-<BLOCKQUOTE>
-Faster build times from support for explicit template instantiation,
-which is enabled by default for most of the tools.
-</BLOCKQUOTE>
-
-@par
-<BLOCKQUOTE>
-Added support for OpenEXR 3. This is contributed by Cary Phillips.
-</BLOCKQUOTE>
-
-@par
-<BLOCKQUOTE>
-Added transient data to the RootNode, InternalNode, and LeafNode.
-</BLOCKQUOTE>
-
 @par
 New features:
-- NanoVDB, which for the first time offers GPU support for static sparse volumes
-  in OpenVDB.
+- Faster build times from support for explicit template instantiation,
+  which is enabled by default for most of the tools.
+- Added support for OpenEXR 3 and TBB 2021.
+- Added transient data to the RootNode, InternalNode, and LeafNode.
 
 @par
 Improvements: