Adsk contrib - Add support for minimum and recommended versions for d…

…ependencies (AcademySoftwareFoundation#1777)

* Implementation of ocio_find_package and ocio_install_package macro.
Implemention of minimum, maximum and recommended version.
Refactor the FindOpenImageIO to be inline with the rest of the custom find module (OCIO_USE_OIIO_CMAKE_CONFIG is no longer needed).
Added a new option called OCIO_VERBOSE. It allow the user to tell OCIO to display more information when searching and building the dependencies.
Splitted the find and install part into two files - Find<pkg>.cmake and Install<pkg>.cmake.

Signed-off-by: Cédrik Fuoco <[email protected]>

* Removing a duplicate call to set_property in OpenImageIO find module.
Setting policy CMP0042 when building ZLIB since that project is using an old CMake version as the cmake_minimum_required and that version has no knowledge of the policy.
Fixing a potential issue in Installopenfx. Changing back the version to 1.4 as before.
Ignoring warning from OpenImageIO for imageioapphelpers. The same warning are ignored for ociodisplay, ocioconvert and ociolutimage.

Signed-off-by: Cédrik Fuoco <[email protected]>

* Fixed an issue with FindOpenImageIO that was found while testing on macOS.
Renamed FindOpenShadingLanguage to FindOSL to match the project name used the OSL's CMakefile.
Cleanup the code for FindOSL and removed duplicate warning about needed C++14.

Updated the header comments for all Find and Install modules.

Signed-off-by: Cédrik Fuoco <[email protected]>

* Fixing typo

Signed-off-by: Cédrik Fuoco <[email protected]>

* Renamed ocio_find_package to ocio_handle_dependency
Renamed ocio_install_package to ocio_install_dependency
The "Installing [...]" message from Install module is now under OCIO_VERBOSE variable. Added a message in ocio_install_dependency instead
Improve the colors usage in the logging

Signed-off-by: Cédrik Fuoco <[email protected]>

* Changed prefix for ocio_install_dependency since it was conflicting with the prefix of ocio_handle_dependency since they were the same.
Removed FindOpenEXR.cmake and FindOpenImageIO.cmake since they are not needed anymore (for differente reason).
Added PROMOTE_TARGET option for ocio_handle_dependency which promote the target to GLOBAL.

Signed-off-by: Cédrik Fuoco <[email protected]>

* Mostly comments and documentations

Signed-off-by: Cédrik Fuoco <[email protected]>

* Small update of the Existing Install Hints section

Signed-off-by: Cédrik Fuoco <[email protected]>

* Changed RECOMMENDED_MIN_VERSION to RECOMMENDED_VERSION
Re-worded some of the comments

Signed-off-by: Cédrik Fuoco <[email protected]>

* Fixing issue with ocio_handle_dependency macro where it wasn't respecting OCIO_INSTALL_EXT_PACKAGES option correctly.

Signed-off-by: Cédrik Fuoco <[email protected]>

* Adding more documentations and dropping support to look for static zlib since the user can update their cmake in order to do that.

Signed-off-by: Cédrik Fuoco <[email protected]>

* Documentations

Signed-off-by: Cédrik Fuoco <[email protected]>

* Documentations

Signed-off-by: Cédrik Fuoco <[email protected]>

* fixing typo

Signed-off-by: Cédrik Fuoco <[email protected]>

* Fix typo and fix issue when OCIO is installing ZLIB

Signed-off-by: Cédrik Fuoco <[email protected]>

* Tentative fix for Linux CI failure

Signed-off-by: Cédrik Fuoco <[email protected]>

* Ignoring specifics warnings on OpenImageIO target directly.

Signed-off-by: Cédrik Fuoco <[email protected]>

* Removing OCIO_USE_OIIO_CMAKE_CONFIG as it is not needed anymore.

Signed-off-by: Cédrik Fuoco <[email protected]>

---------

Signed-off-by: Cédrik Fuoco <[email protected]>

CMakeLists.txt

@@ -12,6 +12,7 @@ set(CMAKE_MODULE_PATH
     ${CMAKE_SOURCE_DIR}/share/cmake/utils
     ${CMAKE_SOURCE_DIR}/share/cmake/macros
     ${CMAKE_SOURCE_DIR}/share/cmake/modules
+    ${CMAKE_SOURCE_DIR}/share/cmake/modules/install
 )
 
 set(CMAKE_WARN_DEPRECATED ON)
@@ -156,6 +157,9 @@ if (WIN32)
     option(OCIO_USE_WINDOWS_UNICODE "Compile with Windows Unicode support" ON)
 endif()
 
+###############################################################################
+# Other preferences
+option(OCIO_VERBOSE "Display more information when searching or installing dependencies" OFF)
 
 ###############################################################################
 # Warnings / debugging settings
@@ -171,13 +175,13 @@ endif()
 # Optimization / internal linking preferences
 
 option(OCIO_USE_SSE "Specify whether to enable SSE CPU performance optimizations" ON)
-option(OCIO_USE_OIIO_CMAKE_CONFIG "Specify whether to look for OIIO using the generated CMake Config script instead of the custom FindOpenImageIO.cmake script" OFF)
 option(OCIO_USE_OIIO_FOR_APPS "Request OIIO to build apps (ociolutimage, ocioconvert and ociodisplay), the default uses OpenEXR." OFF)
 
 
 ###############################################################################
 # GPU configuration
-
+message(STATUS "")
+message(STATUS "Checking for GPU configuration...")
 include(CheckSupportGL)
 
 

docs/quick_start/installation.rst

@@ -187,10 +187,26 @@ Three ``OCIO_INSTALL_EXT_PACKAGES`` options are available::
 Existing Install Hints
 ++++++++++++++++++++++
 
-When using libraries already on your system, the CMake variable 
-``-D <Package Name>_ROOT=<Path>`` may be used to specify the path to the include and 
-library root directory rather than have CMake try to find it.  The package names used 
-by OCIO are as follows (note that these are case-sensitive):
+If the library is not installed in a typical location where CMake will find it, 
+you may specify the location using one of the following methods:
+
+- Set ``-D<package_name>_DIR`` to point to the directory containing the CMake configuration file for the package.
+
+- Set ``-D<package_name>_ROOT`` to point to the directory containing the lib and include directories.
+
+- Set ``-D<package_name>_LIBRARY`` and ``-D<package_name>_INCLUDE_DIR`` to point to the lib and include directories.
+
+Not all packages support all of the above options. Please refer the 
+OCIO CMake `find modules <https://github.com/AcademySoftwareFoundation/OpenColorIO/tree/main/share/cmake/modules>`_  for the package that you are having trouble with to see the options it supports.
+
+Usually CMake will use the dynamic library rather than static, if both are present. In this case, 
+you may set <package_name>_STATIC_LIBRARY to ON to request use of the static one. If only the 
+static library is present (such as when OCIO builds the dependency), then the option is not needed.
+The following packages support this option:
+``expat``, ``yaml-cpp``, ``Imath``, ``lcms2``, and ``minizip-ng``. Using CMake 3.24+, it is
+possible to prefer the static version of ``ZLIB`` with ``-DZLIB_USE_STATIC_LIBS=ON``.
+
+The package names used by OCIO are as follows (note that these are case-sensitive):
 
 Required:
 
@@ -214,21 +230,6 @@ Optional:
 - ``GLUT``
 - ``Python``
 
-There are scenarios in which some of the dependencies may not be compiled into an 
-OCIO dynamic library.  This is more likely when OCIO does not download the packages
-itself.  In these cases, it may be helpful to additionally specify the CMake variable
-``-D <Package Name>_STATIC_LIBRARY=ON``. The following package names support this hint:
-``expat``, ``yaml-cpp``, ``Imath``, ``lcms2``, ``ZLIB``, and ``minizip-ng``.
-
-Rather than using ``_ROOT``, and possibly ``_STATIC_LIBRARY``, you may instead use
-``-D <Package Name>_LIBRARY=<Path>`` and ``-D <Package Name>_INCLUDE_DIR=<Path>``.
-In this case, the library path will control whether a static or dynamic library is used.
-It may also be used to handle situations where the library and/or include files are not
-in the typical location relative to the root directory.
-
-The OCIO `CMake find modules <https://github.com/AcademySoftwareFoundation/OpenColorIO/tree/main/share/cmake/modules>`_ 
-may be consulted for more detail on the handling of a given package and the CMake
-variables it uses.
 
 Please note that if you provide your own ``minizip-ng``, rather than having OCIO's CMake
 download and build it, you will likely need to set its CMake variables the same way
@@ -384,7 +385,7 @@ Windows
 While build environments may vary between users, the recommended way to build OCIO from source on 
 Windows 7 or newer is to use the scripts provided in the Windows 
 `share <https://github.com/AcademySoftwareFoundation/OpenColorIO/tree/main/share/dev/windows>`_ 
-section of the OCIO repository. There are two scripts currently available. 
+section of the OCIO repository. There are two scripts currently available.
 
 The first script is called 
 `ocio_deps.bat <https://github.com/AcademySoftwareFoundation/OpenColorIO/tree/main/share/dev/windows/ocio_deps.bat>`_ 
@@ -396,14 +397,18 @@ and it provides some automation to install the most difficult dependencies. Thos
 - Glew
 - Python dependencies for documentation
 
-Run this command to execute the ocio_deps.bat script::
+Run this command to execute the ocio_deps.bat script:
 
+.. code-block:: bash
+    
     ocio_deps.bat --vcpkg <path to current vcpkg installation or where it should be installed>
 
 The second script is called 
 `ocio.bat <https://github.com/AcademySoftwareFoundation/OpenColorIO/tree/main/share/dev/windows/ocio.bat>`_ 
 and it provide a way to configure and build OCIO from source. Moreover, this script executes the 
-install step of ``cmake`` as well as the unit tests. The main use case is the following::
+install step of ``cmake`` as well as the unit tests. The main use case is the following:
+
+.. code-block:: bash
 
     ocio.bat --b <path to build folder> --i <path to install folder> 
     --vcpkg <path to vcpkg installation> --ocio <path to ocio repository> --type Release
@@ -422,14 +427,26 @@ Quick environment configuration
 
 The quickest way to set the required :ref:`environment-setup` is to
 source the ``share/ocio/setup_ocio.sh`` script installed with OCIO.
-On Windows, use the corresponding setup_ocio.bat file.
+On Windows, use the corresponding setup_ocio.bat file. See OCIO's install directory under 
+share/ocio.
+
+For a temporary configuration of your terminal, you can run the following script:
+
+.. code-block:: bash
+
+   # Windows - Execute setup_ocio.bat
+   [... path to OCIO install directory]/share/ocio/setup_ocio.bat
+   # Unix - Execute setup_ocio.sh
+   [... path to OCIO install directory]\share\ocio\setup_ocio.sh
 
-For a simple single-user setup, add the following to ``~/.bashrc``
+For a more permanent option, add the following to ``~/.bashrc``
 (assuming you are using bash, and the example install directory of
-``/software/ocio``)::
+``/software/ocio``):
 
-    source /software/ocio/share/ocio/setup_ocio.sh
+.. code-block:: bash
 
+   source /software/ocio/share/ocio/setup_ocio.sh
+    
 The only environment variable you must configure manually is
 :envvar:`OCIO`, which points to the configuration file you wish to
 use. For prebuilt config files, see the

share/cmake/macros/VersionUtils.cmake

@@ -6,8 +6,19 @@
 
 macro(split_version_string version_var output_prefix)
     string(REPLACE "." ";" _version_var_list ${version_var})
-    list(GET _version_var_list 0 ${output_prefix}_VERSION_MAJOR)
-    list(GET _version_var_list 1 ${output_prefix}_VERSION_MINOR)
-    list(GET _version_var_list 2 ${output_prefix}_VERSION_PATCH)
+    list(LENGTH _version_var_list _version_var_list_length)
+
+    if (_version_var_list_length GREATER_EQUAL 1)
+        list(GET _version_var_list 0 ${output_prefix}_VERSION_MAJOR)
+    endif()
+
+    if (_version_var_list_length GREATER_EQUAL 2)
+        list(GET _version_var_list 1 ${output_prefix}_VERSION_MINOR)
+    endif()
+
+    if (_version_var_list_length GREATER_EQUAL 3)
+        list(GET _version_var_list 2 ${output_prefix}_VERSION_PATCH)
+    endif()
+
     unset(_version_var_list)
 endmacro()

share/cmake/macros/ocio_check_dependency_version.cmake

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright Contributors to the OpenColorIO Project.
+
+###################################################################################################
+# ocio_check_dependency_version try to find the specified dependency and validate the version.
+#
+# Note that a function is used here to scoped-in any variables set by find_package. We do not want
+# those variables to be propagated to the caller of the function.
+#
+# Argument:
+#   dep_name is the name of the dependency (package). Please note that dep_name is case sensitive.
+#
+###################################################################################################
+
+function (ocio_check_dependency_version dep_name output)
+    cmake_parse_arguments(
+        # prefix - Must be different than the one used in ocio_handle_dependency.cmake.
+        ocio_cdv
+        # options
+        ""
+        # one value keywords
+        "MIN_VERSION"
+        # multi value keywords
+        ""
+        # args
+        ${ARGN})
+
+    if (dep_name)
+        find_package(${dep_name} ${ocio_cdv_UNPARSED_ARGUMENTS})
+        if (ocio_cdv_MIN_VERSION AND ${dep_name}_VERSION)
+            if (${${dep_name}_VERSION} VERSION_GREATER_EQUAL ocio_cdv_MIN_VERSION)
+                set(${output} TRUE)
+            else()
+                set(${output} FALSE)
+            endif()
+        endif()
+    endif()
+endfunction()