Skip to content

Latest commit

 

History

History
342 lines (280 loc) · 13.2 KB

BUILDING.md

File metadata and controls

342 lines (280 loc) · 13.2 KB
Raw

Advanced Build Configuration

Table of Contents

Dependencies

The USD plug-in for Katana has the following dependencies:

  • Katana's Plug-ins API
  • USD
  • TBB
  • Python
  • Boost
  • GLEW**
  • OpenEXR**
  • OpenImageIO**
  • JPEG**
  • PNG**
  • TIFF**
  • Zlib**
  • OpenSubdiv**
  • PTex**

The dependencies need to match the versions that were used to build USD. The versions we use for these libraries are mentioned in the Katana Dev Guide https://learn.foundry.com/katana/dev-guide/ExternalSoftware.html

Many of the dependencies are found via CMake's config mechanism.

**Note: These dependencies are only needed if using a default pxrConfig.cmake from an external USD Build. If you are using the USE_KATANA_THIRDPARTY_LIBS or the FindUSD.cmake on Linux then you will not need these.

The additional information around these dependencies can be found in the Advanced Building With CMake under Advanced Dependencies.

Katana's Plug-ins API

Katana is shipped with a API (header and source files), used to build Katana plug-ins. KATANA_API_LOCATION must be provided, to the Katana installation prefix.

Building With CMake

In order to make building the KatanaUsdPlugins as simple as possible we have included some extra features which can be used for building the plugins if you have not made any changes to the required libraries. This has been tested to work with the KatanaUsdPlugins as we ship them. We have provided an example build script Linux using the USE_KATANA_THIRDPARTY_LIBS.

Unfortuntaly the use of dllimports in the headers of the USD libraries means that adding the same improvements on Windows is not as simple, and therefore we need to add the whole dependencies chain which is best described by the pxrConfig.cmake file generated by your USD build. For Windows see Advanced Dependencies.

Linux Example

cmake .. \
    -DKATANA_API_LOCATION=<KATANA_ROOT> \
    -DUSE_KATANA_THIRDPARTY_LIBS=ON \
    -DCMAKE_INSTALL_PREFIX="/path/to/usd_for_katana/install"

USE_KATANA_THIRDPARTY_LIBS (Linux Only)

For Linux builds only We have introduced a variable which if defined at build time takes away a lot of the requirements in setting up the thirdparty package searches within CMake. This option will define and set the USE_KATANA_PYTHON, USE_KATANA_TBB, USE_KATANA_USD, and USE_KATANA_BOOST variables to ON. By default this is set to OFF.

You must specify the KATANA_API_LOCATION for this to work, as this is the root of the Katana install and is used to find the libs and headers we ship with Katana.

The following options can also be used independently of each other, and you can default back to using more advanced CMake features for finding these libraries or using your own by simply not defining any of these.

USE_KATANA_PYTHON (Linux Only)

When defined we do not use the default CMake find_package for finding the Python libraries. Instead we define the Python::Python interface manually from the installed locations in the Katana build.

USE_KATANA_BOOST (Linux Only)

When defined we setup the findBoost CMake find_package function to correctly find the Boost which we ship with. As a reminder, our Boost libraries ship as namespaced, shared and prefixed.

USE_KATANA_TBB (Linux Only)

This option manually builds the TBB::tbb CMake interface from the libraries and headers we ship with Katana. As a reminder, our TBB libraries are namespaced, shared and prefixed.

USE_KATANA_USD (Linux Only)

This option uses our provided FindUSD.cmake, which is a much smaller subset of the main USD config file, which reduces the third-party dependency requirements substantially. This will then use the namespaced shared and prefixed libraries which we ship with Katana. More info about the FindUSD.cmake can be found below in the The FindUSD.cmake helper script section.

ENABLE_USD_EXPORT

This option allows building the project without UsdExport plugin. The default value is ON. This might be important if building against Katana version lower than 4.0.

ENABLE_USD_RENDER_INFO_PLUGIN

This option allows building the project without UsdRenderInfoPlugin. It registers the UsdPreviewSurface shaders and UsdLuxLights, and that support for viewing these in Viewer (Hydra) tab was added in Katana 4.0v1. The default value is ON.

Advanced Building With CMake

Below we provide some examples of cmake build scripts that can be used to build the plug-ins. There are options there which you may want to remove, such as USE_BOOST_NAMESPACE_ENABLED and Boost_NAMESPACE depending on your build requirements, and whether you're using a namespaced boost, or want to use our Boost libraries supplied with Katana.

We have introduced a new option, PXR_PY_PACKAGE_NAME, to set when building the Katana USD Plug-ins. For the Foundry USD build, we have namespaced the Python libraries using this cmake variable, and continued the use of this cmake variable into our Katana USD Plug-ins. If building against the USD libraries shipped with Katana, please make sure to set this to fnpxr. If this is not set, you may experience issues using the Python libraries, most notably for the usdKatana module. This value defaults to pxr, so if you are using a default USD build, it will work without setting this value.

Advanced Dependencies

The following dependencies are required if you are not using the simple build setup. The majority of dependencies mentioned here will have options depending heavily on how you have built USD and whether the build used CMake interfaces, full paths or variables in the pxrConfig.cmake. Below we provide the options we use.

Note: You may also need more dependencies than those we have mentioned depending on how you have built USD and whether you have made changes to how it builds. Below are those required when using our FnUSD builds, but other libraries such as JPEG, PNG, TIFF, PTex, may also be needed.

USD

USD_ROOT must be provided, to the USD installation prefix. USD must be built with PXR_ENABLE_PYTHON_SUPPORT and PXR_BUILD_IMAGING.

TBB

TBB_DIR must be provided, to the cmake folder of the TBB installation.

You may also specify TBB_tbb_LIBRARY and TBB_INCLUDE_HEADERS, or TBB_ROOT_DIR to specify use of the included findTBB.cmake.

Python

Python_DIR must be provided, to the folder containing a cmake config file for the Python installation. In addition, specify:

  • Python_EXECUTABLE which is used to compile Python files on build

You may also specify the Python_ROOT_DIR to use the default CMake FindPython.cmake method.

Boost

BOOST_ROOT must be provided, to the Boost installation prefix. Dynamic Boost is used, so specifying

  • Boost_USE_STATIC_LIBS=OFF is also useful.

GLEW

GLEW_DIR must be provided, to the cmake folder of the GLEW installation.

OpenEXR

OpenEXR_DIR must be provided, to the cmake folder of the OpenEXR installation.

OpenImageIO

OpenImageIO_DIR must be provided, to the cmake folder of the OpenImageIO installation.

OpenSubdiv

OpenSubdiv_DIR must be provided, to the cmake folder of the OpenSubdiv installation.

Advanced Build Linux Example:

cd /path/to/usd_for_katana
mkdir build
cd build
cmake .. \
    -DKATANA_API_LOCATION=/opt/Foundry/Katana3.2v1/ \
    -DUSD_ROOT=/path/to/USD/ \
    -DPXR_PY_PACKAGE_NAME=fnpxr \
    -DTBB_DIR=/path/to/TBB/cmake \
    -DPython_DIR=/path/to/Python/cmake \
    -DPython_EXECUTABLE=/path/to/Python/bin/python \
    -DBOOST_ROOT=/path/to/Boost \
    -DBoost_NAMESPACE=Fnboost \
    -DUSE_BOOST_NAMESPACE_ENABLED=1 \
    -DBoost_USE_STATIC_LIBS=OFF \
    -DGLEW_DIR=/path/to/GLEW/lib/cmake/glew \
    -DOpenEXR_DIR=/path/to/OpenEXR/cmake \
    -DOpenImageIO_DIR=/path/to/OpenImageIO/cmake \
    -DZLIB_ROOT=/path/to/Zlib \
    -DOpenSubdiv_DIR=/path/to/OpenSubdiv/cmake \
    -DCMAKE_INSTALL_PREFIX=/path/to/usd_for_katana/install

cmake --build . --target install -- -j 18

Advanced Build Windows Example:

cd C:/path/to/usd_for_katana
mkdir build\
cd build
cmake .. -G "Visual Studio 14 2015 Win64"^
    -DCMAKE_BUILD_TYPE="Release"^
    -DKATANA_API_LOCATION="C:/Program Files/Foundry/Katana3.2v1"^
    -DUSD_ROOT="C:/path/to/USD/"^
    -DPXR_PY_PACKAGE_NAME=fnpxr^
    -DTBB_DIR="C:/path/to/TBB/cmake"^
    -DPython_DIR="C:/path/to/Python/cmake"^
    -DPython_EXECUTABLE="C:/path/to/Python/bin/python.exe"^
    -DBOOST_ROOT="C:/path/to/Boost"^
    -DUSE_BOOST_NAMESPACE_ENABLED=1^
    -DBoost_NAMESPACE=Fnboost^
    -DBoost_USE_STATIC_LIBS=OFF^
    -DGLEW_DIR="C:/path/to/GLEW/lib/cmake/glew"^
    -DOpenEXR_DIR="C:/path/to/OpenEXR/cmake"^
    -DOpenImageIO_DIR="C:/path/to/OpenImageIO/cmake"^
    -DZLIB_ROOT="C:/path/to/Zlib"^
    -DOpenSubdiv_DIR="C:/path/to/OpenSubdiv/cmake"^
    -DCMAKE_INSTALL_PREFIX="C:/path/to/usd_for_katana/install"

cmake --build . --target install --config Release --parallel 18

It is possible to change the installation directory by setting the variable CMAKE_INSTALL_PREFIX before invoking CMake. By default, the plug-in will be installed in /usr/local/ on Linux, or in C:/Program Files/ on Windows, under the third_party/katana/ subdirectory. It is encouraged to set the variable to a more sensible destination other than the default location.

In the provided examples, the plug-in will be effectively installed in /path/to/usd_for_katana/third_party/katana/ in Linux, or C:/path/to/usd_for_katana/third_party/katana/ in Windows.

The FindUSD.cmake helper script (Linux Only)

Due to the way the USD pxrConfig.cmake file works, it adds all the libraries which were built in that USD package. This has the adverse affect of requiring all the dependent libraries to be included in the build time scripts. To help in this regard, we have created a simplified findUSD.cmake script to reduce this to only the libraries required to build the Katana USD Plug-ins.

To enable the use of this FindUSD.cmake file, define the CMake variable USE_FOUNDRY_FIND_USD. This means a considerably shorter build script! You will also need to specify the PXR_LIB_PREFIX you used when building the USD libraries initially, as this is used to find the libraries. On Linux if defining this value, remember to add lib to the start, for example when using our USD libraries it would be libFn, on Windows just Fn.

If you have installed USD in a non-standard way (as we have in Katana), you can also specify the USD_INCLUDE_DIR and USD_LIBRARY_DIR separately. Otherwise it is assumed that these paths are ${USD_ROOT}/include and ${USD_ROOT}/lib respectively. If specifying both of these you do not have to specify USD_ROOT. As we do not support Katana on Apple, the findUSD cmake script will fail to find libraries on Apple systems.

Below we have included examples of using this for Linux and Windows.

Example Linux CMake:

cmake .. \
    -DKATANA_API_LOCATION=<KATANA_ROOT> \
    -DUSD_ROOT=/path/to/USD/ \
    -DPXR_PY_PACKAGE_NAME=fnpxr \
    -DUSD_LIBRARY_DIR=<KATANA_ROOT>/bin \
    -DUSD_INCLUDE_DIR=<KATANA_ROOT>/external/FnUSD/include \
    -DUSE_FOUNDRY_FIND_USD=1 \
    -DPXR_LIB_PREFIX=libFn \
    -DTBB_DIR=/path/to/TBB/cmake \
    -DPython_DIR=/path/to/Python/cmake \
    -DPython_EXECUTABLE=/path/to/Python/bin/python \
    -DBOOST_ROOT=/path/to/Boost \
    -DBoost_NAMESPACE=Fnboost \
    -DUSE_BOOST_NAMESPACE_ENABLED=1 \
    -DBoost_USE_STATIC_LIBS=OFF \
    -DCMAKE_INSTALL_PREFIX="/path/to/usd_for_katana/install"

Setting Up Katana

To enable the USD plug-in for Katana, append the path to the plugin/ directory into the KATANA_RESOURCES environment variable. For instance, on

Linux:

export KATANA_RESOURCES=$KATANA_RESOURCES:/path/to/usd_for_katana/third_party/katana/plugin/
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/usd_for_katana/third_party/katana/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/usd_for_katana/third_party/katana/plugin/Libs

Windows:

set KATANA_RESOURCES=%KATANA_RESOURCES%;C:/path/to/usd_for_katana/third_party/katana/plugin/
set PATH=%PATH%;C:/path/to/usd_for_katana/third_party/katana/lib
set PATH=%PATH%;C:/path/to/usd_for_katana/third_party/katana/plugin/Libs

Dependant Library setup

If USD is not already set up, also adjust the following environment variables:

Linux

export PATH=$PATH:/path/to/usd/bin/
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/usd/lib/
export PYTHONPATH=$PYTHONPATH:/path/to/usd/lib/python/

Windows:

set "PATH=%PATH%;C:/path/to/usd/bin/"
set "PATH=%PATH%;C:/path/to/usd/lib/"
set "PATH=%PATH%;C:/path/to/usd_for_katana/third_party/katana/lib/"
set "PYTHONPATH=%PYTHONPATH%;C:/path/to/usd/lib/python/"

You may also need to setup where to find the other dependant libraries Boost, TBB and GLEW. These can be done in the same way as above, append the lib directory paths for each dependant library to the PATH or LD_LIBRARY_PATH dependant on your system. This only applies if using shared libraries.