HYDRA-776 : Update build doc & script (#37)

* HYDRA-776 : Automatically determine Python version to use based on Maya version * HYDRA-776 : Remove Jinja * HYDRA-776 : Remove MarkupSafe * HYDRA-776 : Update MAYA_MODULE_PATH section, Ninja section and tool versions prerequisites * HYDRA-776 : Add mentions to some possible CMake variables * HYDRA-776 : List MaterialX variable * HYDRA-776 : Adjust UFE versions * HYDRA-776 : Update USD versions and Python versions * HYDRA-776 : Add instruction for troubleshooting Python errors * HYDRA-776 : Mention PR as supported
Autodesk · Jan 16, 2024 · d8116ed · d8116ed
1 parent bb8c8fa
commit d8116ed
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 81 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -26,7 +26,6 @@ option(BUILD_SHARED_LIBS "Build libraries as shared or static." ON)
 if(APPLE)
     option(BUILD_UB2 "Build Universal Binary 2 (UB2) Intel64+arm64" OFF)
 endif()
-set(BUILD_WITH_PYTHON_3_VERSION 3.10 CACHE STRING "The version of Python 3 to build with")
 option(CMAKE_WANT_MATERIALX_BUILD "Enable building with MaterialX (experimental)." OFF)
 
 set(PXR_OVERRIDE_PLUGINPATH_NAME PXR_PLUGINPATH_NAME
@@ -89,6 +88,13 @@ set(MAYAHYDRA_VERSION "${MAYAHYDRA_MAJOR_VERSION}.${MAYAHYDRA_MINOR_VERSION}.${M
 include(cmake/flowViewport_version.info)
 set(FLOWVIEWPORT_VERSION "${FLOWVIEWPORT_MAJOR_VERSION}.${FLOWVIEWPORT_MINOR_VERSION}.${FLOWVIEWPORT_PATCH_LEVEL}")
 
+set(DEFAULT_PYTHON_3_VERSION 3.10)
+if (MAYA_APP_VERSION VERSION_GREATER 2024)
+    set(DEFAULT_PYTHON_3_VERSION 3.11)
+endif()
+if (NOT BUILD_WITH_PYTHON_3_VERSION)
+    set(BUILD_WITH_PYTHON_3_VERSION ${DEFAULT_PYTHON_3_VERSION})
+endif()
 if (DEFINED PYTHON_INCLUDE_DIR AND DEFINED PYTHON_LIBRARIES AND DEFINED Python_EXECUTABLE)
     SET(PYTHON_INCLUDE_DIRS "${PYTHON_INCLUDE_DIR}")
     SET(PYTHONLIBS_FOUND TRUE)
@@ -106,8 +112,6 @@ message(STATUS "   PYTHON_INCLUDE_DIRS = ${PYTHON_INCLUDE_DIRS}")
 message(STATUS "   PYTHON_LIBRARIES    = ${PYTHON_LIBRARIES}")
 message(STATUS "   Python_EXECUTABLE   = ${Python_EXECUTABLE}")
 
-include(cmake/jinja.cmake)
-
 find_package(USD 0.22.11 REQUIRED)
 if (CMAKE_WANT_MATERIALX_BUILD)
     # Requires at least USD 22.11 for hdMtlx module and USD must have been built with MaterialX:

diff --git a/cmake/jinja.cmake b/cmake/jinja.cmake
diff --git a/doc/build.md b/doc/build.md
@@ -12,30 +12,27 @@ Before building the project, consult the following table to ensure you use the r
 |:---------------------:|:-------------------------:|:------------------------------------------------------------:|:---------------------------:|
 |    Operating System   |         Windows 10 <br> Windows 11 | High Sierra (10.13)<br>Mojave (10.14)<br>Catalina (10.15)<br>Big Sur (11.2.x)    |      Rocky Linux 8.6 / Linux® Red Hat® Enterprise 8.6 WS             |
 |   Compiler Requirement| Maya 2024 (VS 2022) | Maya 2024 (Xcode 13.4 or higher) | Maya 2024 (gcc 11.2.1) |
-| CMake Version (min/max) |        3.13...3.17      |                              3.13...3.17                     |           3.13...3.17       |
-|         Python        | 3.10.8  |                       3.10.8               |  3.10.8   |
-|    Python Packages    | PyYAML, PySide, PyOpenGL, Jinja2        | PyYAML, PySide2, PyOpenGL, Jinja2              | PyYAML, PySide, PyOpenGL, Jinja2 |
+| CMake Version (min/max) |        3.13...3.20      |                              3.13...3.20                     |           3.13...3.20       |
+|         Python        | 3.10.8, 3.11.4  |                       3.10.8, 3.11.4               |  3.10.8, 3.11.4   |
+|    Python Packages    | PyYAML, PySide, PyOpenGL        | PyYAML, PySide2, PyOpenGL              | PyYAML, PySide, PyOpenGL |
 |    Build generator    | Visual Studio, Ninja (Recommended)    |  XCode, Ninja (Recommended)                      |    Ninja (Recommended)      |
-|    Command processor  | Visual Studio X64 2019 command prompt  |                     bash                |             bash            |
-| Supported Maya Version|  2024   |                   2024                    |   2024    |
+|    Command processor  | Visual Studio x64 2022 command prompt  |                     bash                |             bash            |
+| Supported Maya Version|  2024, PR   |                   2024, PR                    |   2024, PR    |
 
 |        Optional       | ![](images/windows.png)   |                            ![](images/mac.png)               |   ![](images/linux.png)     |
 
 ***NOTE:*** Visit the online Maya developer help document under ***Setting up your build environment*** for additional compiler requirements on different platforms.
 
 #### 2. Download and Build Pixar USD 
 
-See Pixar's official github page for instructions on how to build USD: https://github.com/PixarAnimationStudios/USD. Pixar has recently removed support for building Maya USD libraries/plug-ins in their github repository and ```build_usd.py```.
+See Pixar's official github page for instructions on how to build USD: https://github.com/PixarAnimationStudios/USD. Pixar has removed support for building Maya USD libraries/plug-ins in their github repository and ```build_usd.py```.
 
-|               |      ![](images/pxr.png)          |        
-|:------------: |:---------------:                  |
-|  CommitID/Tags | Recommended : [v23.08](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v23.08) |
-|  CommitID/Tags | For older maya-hydra plugin: [v22.11](https://github.com/PixarAnimationStudios/USD/releases/tag/v22.11) |
+|               |      ![](images/pxr.png)          |USD version used in Maya        
+|:------------: |:---------------:                  |:---------------:
+|  CommitID/Tags | [v22.11](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v22.11) or [v23.08](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v23.08) or [v23.11](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v23.11) |Maya 2024 = v22.11<br>Maya PR = v23.11
 
 For additional information on building Pixar USD, see the ***Additional Build Instruction*** section below.
 
-***NOTE:*** Recommended version of USD for building the latest version of MayaHydra plugin is USD23.08  [v23.08](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v23.08). If older version of USD needs to be used then maya-hydra v0.1.x is to be used for build and feature compatibility.
-
 ***NOTE:*** Make sure that you don't have an older USD locations in your ```PATH``` and ```PYTHONPATH``` environment settings. ```PATH``` and ```PYTHONPATH``` are automatically adjusted inside the project to point to the correct USD location. See ```cmake/usd.cmake```.
 
 #### 3. Universal Front End (UFE)
@@ -44,8 +41,7 @@ The Universal Front End (UFE) is a DCC-agnostic component that allows Maya to br
 
 | Ufe Version                | Maya Version                                           | Ufe Docs (external) |
 |----------------------------|--------------------------------------------------------|:-------------------:|
-| v4.0.0                      | Maya 2024                                                | https://help.autodesk.com/view/MAYAUL/2024/ENU/?guid=MAYA_API_REF_ufe_ref_index_html |
-| v4.0.1                      | Maya 2024.1                                               | |
+| v4.0.0<br>v4.1.0<br>v4.2.0            | Maya 2024<br>Maya 2024.1<br>Maya 2024.2                                                | https://help.autodesk.com/view/MAYAUL/2024/ENU/?guid=MAYA_API_REF_ufe_ref_index_html |
 
 To build the project with UFE support, you will need to use the headers and libraries included in the ***Maya Devkit***:
 
@@ -71,7 +67,7 @@ cd maya-hydra
 
 ##### Arguments
 
-There are four arguments that must be passed to the script: 
+There are at least four arguments that must be passed to the script: 
 
 | Flags                 | Description                                                                           |
 |--------------------   |-------------------------------------------------------------------------------------- |
@@ -88,7 +84,29 @@ MacOSX:
 ➜ maya-hydra python build.py --maya-location /Applications/Autodesk/maya2024 --pxrusd-location /opt/local/USD-Release --devkit-location /opt/local/devkitBase /opt/local/workspace
 
 Windows:
-c:\maya-hydra> python build.py --maya-location "C:\Program Files\Autodesk\Maya2024" --pxrusd-location C:\USD-Release --devkit-location C:\devkitBase C:\workspace
+C:\maya-hydra> python build.py --maya-location "C:\Program Files\Autodesk\Maya2024" --pxrusd-location C:\USD-Release --devkit-location C:\devkitBase C:\workspace
+```
+
+**Notes:** 
+- For OSX builds, you might need to toggle on the `BUILD_UB2` CMake option to build Universal Binary 2 binaries (see below).
+- If you get an error saying that the correct Python version could not be found, or an error such as "Imported target <xyz> includes non-existent path" pointing to a Python path, you might need to specify the `Python_EXECUTABLE`, `PYTHON_INCLUDE_DIR` and `PYTHON_LIBRARIES` CMake variables to point to directories of the bundled Maya Python. Here is what to set them to for each platform :
+```
+Linux:
+Python_EXECUTABLE=<maya-location>/bin/mayapy
+PYTHON_INCLUDE_DIR=<maya-location>/include/Python<python-version>/Python (e.g. <maya-location>/include/Python311/Python)
+PYTHON_LIBRARIES=<maya-location>/lib/libpython<python-version>.so (e.g. : <maya-location>/lib/libpython3.11.so)
+
+OSX:
+Python_EXECUTABLE=<maya-location>/Maya.app/Contents/bin/mayapy
+PYTHON_INCLUDE_DIR=<maya-location>/Maya.app/Contents/Frameworks/Python.framework/Versions/<python-version>/include/python<python-version>
+(e.g. <maya-location>/Maya.app/Contents/Frameworks/Python.framework/Versions/3.11/include/python3.11)
+PYTHON_LIBRARIES=<maya-location>/Maya.app/Contents/Frameworks/Python.framework/Versions/<python-version>/lib/libpython<python-version>.dylib
+(e.g. : <maya-location>/Maya.app/Contents/Frameworks/Python.framework/Versions/3.11/lib/libpython3.11.dylib)
+
+Windows:
+Python_EXECUTABLE=<maya-location>\bin\mayapy.exe
+PYTHON_INCLUDE_DIR=<maya-location>\include\Python<python-version>\Python (e.g. <maya-location>\include\Python311\Python)
+PYTHON_LIBRARIES=<maya-location>\lib\python<python-version>.lib (e.g. : <maya-location>\lib\python311.lib)
 ```
 
 ##### Build Arguments
@@ -101,13 +119,19 @@ c:\maya-hydra> python build.py --maya-location "C:\Program Files\Autodesk\Maya20
 --build-args="-DBUILD_TESTS=OFF"
 ```
 
-##### CMake Options
+##### CMake Options and Variables
 
 Name                        | Description                                                | Default
 ---                         | ---                                                        | ---
 BUILD_TESTS                 | builds all unit tests.                                     | ON
 BUILD_STRICT_MODE           | enforces all warnings as errors.                           | ON
 BUILD_SHARED_LIBS			| build libraries as shared or static.						 | ON
+BUILD_UB2			        | build as Universal Binary 2 (OSX)                          | OFF
+BUILD_WITH_PYTHON_3_VERSION | specify which Python 3 version to build with               | Determined based on Maya version
+Python_EXECUTABLE           | path to the Python executable to build with                | Determined automatically by CMake
+PYTHON_INCLUDE_DIR          | directory containing the Python header files               | Determined using the DPython_EXECUTABLE
+PYTHON_LIBRARIES            | path to the Python library to link with                    | Determined using the DPython_EXECUTABLE
+CMAKE_WANT_MATERIALX_BUILD  | enable building with MaterialX (experimental)              | OFF
 
 ##### Stages
 
@@ -135,9 +159,9 @@ Examples:
 
 It is up to the user to select the CMake Generator of choice, but we encourage the use of the Ninja generator. To use the Ninja Generator, you need to first install the Ninja binary from https://ninja-build.org/
 
-You then need to set the generator to ```Ninja``` and the ```CMAKE_MAKE_PROGRAM``` variable to the Ninja binary you downloaded.
+You then need to set the generator to ```Ninja```.
 ```
-python build.py --generator Ninja --build-args=-DCMAKE_MAKE_PROGRAM='path to ninja binary'
+python build.py --generator Ninja
 ```
 ##### Build and Install locations
 
@@ -183,8 +207,6 @@ e.g
 ➜ pip list
 Package    Version
 ---------- --------
-Jinja2     3.1.2
-MarkupSafe 2.1.1
 pip        22.2.1
 PyOpenGL   3.1.6
 PySide2    5.15.2.1
@@ -207,10 +229,11 @@ There is a related ADDITIONAL_PXR_PLUGINPATH_NAME cmake var which can be used if
 
 # How to Load Plug-ins in Maya 
 
-The provided module files (*.mod) facilitates setting various environment variables for plugins and libraries. After the project is successfully built, ```mayaHydra.mod``` are installed inside the install directory. In order for Maya to discover these mod files, ```MAYA_MODULE_PATH``` environment variable needs to be set to point to the location where the mod files are installed.
+The provided module files (*.mod) facilitates setting various environment variables for plugins and libraries. After the project is successfully built, ```mayaHydra.mod``` is installed inside the install directory. In order for Maya to discover this mod file, the ```MAYA_MODULE_PATH``` environment variable needs to be set to point to the location where the mod file is installed.
 Examples:
 ```
 set MAYA_MODULE_PATH=C:\workspace\install\RelWithDebInfo
 export MAYA_MODULE_PATH=/usr/local/workspace/install/RelWithDebInfo
 ```
+The MAYA_MODULE_PATH environment variable can also be set through the Maya.env file.
 Once MAYA_MODULE_PATH is set, run maya and go to ```Windows -> Setting/Preferences -> Plug-in Manager``` to load the plugins.