Improve build system to streamline application integration

See merge request iMSTK/iMSTK!702

The application of "vtk-8.2.cmake" patch was obsoleted by commit
f796986e (REFAC: VTK 9 and greater dependence, task graph timing
chart disabled, data replacements, example updates)

Consistently using "mark_as_superbuild" along side the declaration
of the associated option or cache entry facilitates maintenance by
helping ensure value are consistently passed to the inner build.

For example, it fixes the passing of these two options:

* iMSTK_ENABLE_CUDA_BACKEND: Introduced in 5e90bbce (ENH: Enable CUDA
  in CMake configuration)

* iMSTK_SWIG_PINNED_ARRAY: Introduced in c2b5429e (ENH: add pinned array;
  add cmake option to choose between marshal array and pinned array)

Unless option have to be passed using the command line, this is the
recommended approach to pass options. It avoids "command line length issues".

This commit sets the cache variable prior configuring the outer
build (SUPERBUILD=ON) and it makes sure it is also propagated
down to the inner project.

This commit sets the cache variable prior configuring the outer
build (SUPERBUILD=ON) and it makes sure it is also propagated
down to the inner project.

The variable is currently used only in Wrappers project and was originally
introduced in 6acfa41f (COMP: Build audio only on windows).

This commit is a follow up of 35940011 (ENH: Update imstkSolveDependencies
module based on commontk/Artichoke@4176c39f9) where the variable should
have been originally removed.

Reports messages like the following when OPENHAPTICS_ROOT_DIR is not defined
and is being initialized based on the OH_SDK_BASE environment variable:

  [...]
  -- Checking if OH_SDK_BASE env. variable is defined
  -- Checking if OH_SDK_BASE env. variable is defined - TRUE
  -- Checking if OH_SDK_BASE env. variable is set to existing path
  -- Checking if OH_SDK_BASE env. variable is set to existing path - TRUE
  -- Setting OPENHAPTICS_ROOT_DIR to C:/OpenHaptics/Developer/3.4.0
  -- SuperBuild - First pass - done
  [...]

This commit works around a regression introduced in 5e3a7f46 (COMP: Support setting
custom SOURCE_DIR and BINARY_DIR vars) leading to the configuration error
copied below.

In the case of the OpenHaptics project, this led to always have the value
of the SOURCE_DIR parameter associated with the "imstk_add_external_project"
call to be ignored.

Error:

  CMake Error at C:/Program Files/CMake/share/cmake-3.20/Modules/ExternalProject.cmake:2847 (message):
    No download info given for 'OpenHaptics' and its source directory:

     E:/iMSTKProper/buildWin64/External/OpenHaptics/src

    is not an existing non-empty directory.  Please specify one of:

     * SOURCE_DIR with an existing non-empty directory
     * DOWNLOAD_COMMAND
     * URL
     * GIT_REPOSITORY
     * SVN_REPOSITORY
     * HG_REPOSITORY
     * CVS_REPOSITORY and CVS_MODULE
  Call Stack (most recent call first):
    C:/Program Files/CMake/share/cmake-3.20/Modules/ExternalProject.cmake:3681 (_ep_add_download_command)
    CMake/Utilities/imstkAddExternalProject.cmake:103 (ExternalProject_add)
    CMake/External/External_OpenHaptics.cmake:40 (imstk_add_external_project)
    CMake/Utilities/imstkSolveDependencies.cmake:868 (include)
    CMake/Utilities/imstkSolveDependencies.cmake:942 (ExternalProject_Include_Dependencies)
    CMake/External/CMakeLists.txt:70 (ExternalProject_Include_Dependencies)

Removes the use of NO_DEFAULT_PATH introduced in a709a89b (Cmake updates
for proper generation of iMSTKConfig.cmake) in favor of CONFIG and consistently
use CONFIG in both CMakeLists.txt and iMSTKConfig.

Requiring the GTest config file ensures the configuration succeeds by
preventing the FindGTest module provided by CMake from being used.

Removing the use of NO_DEFAULT_PATH allows to build iMSTK against a system
version of GTest (starting with Ubuntu 21.04 released in April 2021, the
libgtest-dev package includes GTestConfig.cmake)

Andrew Wilson authored 3 years ago and Jean-Christophe Fillion-Robin committed 3 years ago

Co-authored-by: Andrew Wilson <andrew.wilson@kitware.com>

Note that the option CMAKE_CXX_STANDARD is already passed to all
external projects.

This commit partially reverts a543c7d6 (Update C++ to 14) restoring
support for building against C++11.

Implementation of std::make_unique only available with c++14 was originally
introduced in afe976dc (COMP: Clear compilation errors with gcc) and later
moved into imstkMath.h in 60570195 (BUG: Clear compilation errors on Ubuntu)

This commit fixes a regression introduced in commit (COMP: Streamline
client project integration updating TBB from 2019_U2 to 2019_U9) requiring
the TBB libraries to be organized with directories satisfying the provided
TBBConfig.cmake.

To also accommodate "gtest_discover_tests", the shared libraries are also
copied into the "bin" directory.

This commit backports changes associated with commontk/Artichoke PR-37
See https://github.com/commontk/Artichoke/pull/37

It ensures ``User Package Registry`` look up using ``find_*`` commands
is disabled.

List of changes:

$ git shortlog 4176c39f9..edfc828 --no-merges
Jean-Christophe Fillion-Robin (3):
      ExternalProjectDependency: Fix variable type of automatically propagated options
      circleci: Use dockbuild/centos7-devtoolset7-gcc7 instead of dockbuild/centos6
      ExternalProjectDependency: Ensure ``User Package Registry`` look up using ``find_*`` commands is disabled

Considering that in VegaFEM v4.0, pthreads was replaced with
Intel TBB (see [1]), this commit removes the references to "pthread" and
also removes the corresponding custom CMake module.

[1] http://barbic.usc.edu/vega/download.html

It also fixes error like the following reported when integrating iMSTK in
project (e.g Slicer-based app) already looking up threading libraries
using "FindThreads" module provided by CMake:

   -- Found PThreads: C:/path/to/SlicerCustomApp-build/PThreads-install/include/pthread
    CMake Error at C:/path/to/SlicerCustomApp-build/iMSTK/CMake/Utilities/imstkFind.cmake:214 (add_library):
      add_library cannot create imported target "Threads::Threads" because
      another target with the same name already exists.
    Call Stack (most recent call first):
      C:/path/to/SlicerCustomApp-build/iMSTK/CMake/FindPThreads.cmake:8 (imstk_find_package)
      C:/path/to/SlicerCustomApp-build/VegaFEM-install/lib/cmake/VegaFEM/VegaFEMConfig.cmake:8 (find_package)
      C:/path/to/SlicerCustomApp-build/CTK/CMake/CMakeFindDependencyMacro.cmake:90 (find_package)
      C:/path/to/SlicerCustomApp-build/imstk-build/iMSTKConfig.cmake:144 (find_dependency)
      C:/path/to/SlicerCustomApp/Modules/CLI/MyCLI/CMakeLists.txt:33 (find_package)

List of VegaFEM changes:

$ git shortlog be55ca42b..b10672cf1 --no-merges
Jean-Christophe Fillion-Robin (1):
      COMP: Remove obsolete and unused PThreads requirement

List of changes:

$ git shortlog 5be652501..be55ca42b --no-merges
Jean-Christophe Fillion-Robin (1):
      COMP: Fix gcc 5.x build error in sparseMatrix.cpp related to ambiguous isnan call

This commit does not include any functional changes.

It partially reverts 3730f119 (ENH: Model reduction fixed up, toggleable
in cmake, default off) by switching back to using the existing "VegaFEM-CMake"
project where the master branch has been updated to include all the commit
originally associated with the "build_model_reduction" from "vegafemv4.0"
project.

To avoid inflating the size of the project, the following commits
from the "build_model_reduction" available on "vegafemv4.0" have
been squashed together while "rebasing" the changes:
* ENH: Initial commit of vegaFEMv4.0 code
* REFAC: Remove all the extra files that are not code

This allows to keep the size to ~22MiB instead of the ~126MiB.

This commit adds support for passing options like the following:
* iMSTK_<project-name>_GIT_REPOSITORY
* iMSTK_<project-name>_GIT_TAG

This approach enables:

* Streamline external project maintenance by allowing to develop patches
  directly in the source checkout downloaded by external project.

* Configuring the version of each external projects when integrating
  iMSTK in custom applications (e.g Slicer-based app).

Note that iMSTKData and VTK external projects have not been updated.

After updating the CMake minimum required version to >= 3.15, package
export is disabled by default (see policy CMP0090) and explicitly setting
option CMAKE_EXPORT_NO_PACKAGE_REGISTRY will not be needed.

References:
* https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.html#variable:CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
* https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#disabling-the-package-registry

See https://github.com/oneapi-src/oneTBB/releases/tag/2019_U9

This commit has two purposes:

* update the version of TBB to latest version providing the
  "task_scheduler_init" API deprecated in newer version.

* remove the iMSTK specific logic to look up iMSTK and rely on
  TBB_DIR and associated TBBConfig file.

* rename the external project from "tbb" to "TBB" to be consistent
  with the current naming convention.

If iMSTK_AUDIO_ENABLED is ON:
* include SFML external project
* define iMSTK_AUDIO_ENABLED macro and require SFML package
* require SFML package in iMSTKConfig

On windows, if option iMSTK_ENABLE_AUDIO is NOT specified,
audio support is enabled  and the following message is displayed:

  -- iMSTK Audio support - ON (default initialization)

On windows, if option iMSTK_ENABLE_AUDIO is specified,
message like the following is displayed:

  -- iMSTK Audio support - OFF (iMSTK_ENABLE_AUDIO is SET)

And on other platform, the audio support is always disabled
and the following message is displated:

  -- iMSTK Audio support - OFF (not supported)

This will facilitate the maintenance of external projects added
to the SlicerIMSTK extension by avoiding the "proj" variable from
bring overriden when recursively including external projects.

This ensures external project like the one in the SlicerIMSTK extension
will have their project variable value restored after the call to
"ExternalProject_Include_Dependencies" returns.

This commit supports settings custom value for <proj>_SOURCE_DIR
and <proj>_BINARY_DIR.

This commit ensures the iMSTKConfig file configured in an iMSTK build
tree includes PThreads and LIBFTD2XX variables.

This commit fixes a regression introduced in (COMP: Add relevant vars to
iMSTKConfig to streamline config against a build-tree),

Note that variable for "regular" project are specified. iMSTK specific
variables likes <proj>_ROOT_DIR and <proj>_LIB_DIR are not set because
the location of the corresponding project is automatically inferred by
Find<proj> CMake module provided by iSMTK.

Add variables OpenVR_INCLUDE_DIR and OpenVR_LIBRARY to the CACHE to
workaround issue related to use of mark_as_advanced command in
FindOpenVR and described in CMP0102.

Indeed, this is required because CMP0102 is not automatically set to
NEW and addressing this issue would required to update the FindOpenVR
modules shipped in the different VTK version iMSTK can be built against.

See https://cmake.org/cmake/help/latest/policy/CMP0102.html

This commit fixes the following error reported when attempting to
configure a project like iMSTKProject (see [1]) against an iMSTK
build tree:

    CMake Error at /path/to/cmake-3.21.4-linux-x86_64/share/cmake-3.21/Modules/FindPackageHandleStandardArgs.cmake:230 (message):
    Could NOT find OpenVR (missing: OpenVR_LIBRARY OpenVR_INCLUDE_DIR)
  Call Stack (most recent call first):
    /path/to/cmake-3.21.4-linux-x86_64/share/cmake-3.21/Modules/FindPackageHandleStandardArgs.cmake:594 (_FPHSA_FAILURE_MESSAGE)
    /path/to/iMSTK-build/install/lib/cmake/vtk-9.0/FindOpenVR.cmake:45 (find_package_handle_standard_args)
    /path/to/iMSTK-build/install/lib/cmake/vtk-9.0/VTK-vtk-module-find-packages.cmake:162 (find_package)
    /path/to/iMSTK-build/install/lib/cmake/vtk-9.0/vtk-config.cmake:131 (include)
    /path/to/cmake-3.21.4-linux-x86_64/share/cmake-3.21/Modules/CMakeFindDependencyMacro.cmake:47 (find_package)
    /path/to/iMSTK-build/Innerbuild/iMSTKConfig.cmake:150 (find_dependency)
    CMakeLists.txt:8 (find_package)

[1] https://gitlab.kitware.com/iMSTK/imstkexternalprojecttemplate/-/tree/master/iMSTKProject

This commit fixes the following error:

  $ ctest -R CodeFormatTest -V
  [...]
  test 1
      Start 1: CodeFormatTest

  1: Test command: /home/jcfr/Projects/iMSTK-build/install/bin/uncrustify "-c" "/home/jcfr/Projects/iMSTK/CMake/Utilities/../../Utilities/Uncrustify/iMSTKUncrustify.cfg" "-F" "/home/jcfr/Projects/iMSTK-build/Innerbuild/Uncrustify.list" "--check"
  1: Test timeout computed to be: 1500
  1: process_source_list: fopen(/home/jcfr/Projects/iMSTK-build/Innerbuild/Uncrustify.list) failed: No such file or directory (2)
  1/1 Test #1: CodeFormatTest ...................***Failed    0.00 sec

This commit fixes a regression introduced in 0ffa63e9 (COMP: Add relevant
vars to iMSTKConfig to streamline config against a build-tree) by ensuring
REQUIRED parameter passed when finding iMSTK is not passed when looking up
vtkRenderingExternal and vtkRenderingOpenVR projects.