TriBITS: Switch to modern cmake targets (TriBITSPub/TriBITS#299)

.gitignore

@@ -16,6 +16,7 @@ doxygen_objdb_*.tmp
 
 # Trilinos extra repos
 /TriBITS/
+/TriBITS
 /preCopyrightTrilinos/
 /DrekarBase/
 /DrekarResearch/

RELEASE_NOTES

@@ -1,3 +1,97 @@
+###############################################################################
+#                                                                             #
+# Trilinos Release 14.0 Release Notes                                         #
+#                                                                             #
+###############################################################################
+
+CMake
+
+  - A switch to modern CMake targets in IMPORTED library targets in installed
+    `<Package>Config.cmake` files has been made that **breaks backward
+    compatibility** for some downstream CMake projects by changing how include
+    directories are handled:
+
+    With the switch to modern CMake IMPORTED targets, now include directories
+    (along with critical compiler options and other modern CMake usage
+    requirements) are propagated through linking to the IMPORTED library
+    targets in downstream customer CMake projects.  This makes the usage of
+    the variables `Trilinos_INCLUDE_DIRS` and `Trilinos_TPL_INCLUDE_DIRS`
+    unnecessary in downstream CMake projects.  The variable
+    `Trilinos_INCLUDE_DIRS` is still set but the variable
+    `Trilinos_TPL_INCLUDE_DIRS` is empty in this change to modern CMake.  To
+    get include directories for Trilinos packages and TPLs, one must link
+    against the Trilinos target `Trilinos::all_libs` or
+    `Trilinos::all_selected_libs` or by linking against the individual package
+    targets `<packageName>::all_libs` and/or the TPL targets
+    `<tplName>::all_libs`.  To upgrade downstream CMake projects that are
+    showing missing include directories (i.e. header files can't be found on
+    the compile liens) just add `target_link_libraries()` calls with the
+    appropriate `<prefix>::all_libs` targets for the desired package and/or
+    TPL.  (See the section "Using the installed software in downstream CMake
+    projects" in the updated build reference guide.)  However, backward
+    compatibility is maintained for most customers which are linking all of
+    their libraries against `${Trilinos_LIBRARIES}`.  For these projects, no
+    changes will need to be made.
+
+    However, this change to modern CMake targets will also cause downstream
+    CMake projects to pull in include directories as `SYSTEM` includes
+    (e.g. using `-isystem` instead of `-I`) from IMPORTED library targets.
+    This changes how these include directories are searched and could break
+    some fragile build environments that have the same header file names in
+    multiple include directories searched by the compiler.  Also, this will
+    silence any regular compiler warnings from header files found under these
+    include directories.  This constitutes a **break in backward
+    compatibility** that will break some customer CMake project builds that
+    use Trilinos on fragile environments where the search order of the include
+    directories is important.
+
+    There are several different approaches for addressing this change from
+    `-I` to `-isystem` for the Trilinos include directories described below.
+
+    **Approach-1:** Update to CMake 3.23 and set the Trilinos configure
+    variable:
+
+      -D Trilinos_IMPORTED_NO_SYSTEM=ON
+
+    This will change back the listing of Trilinos include directories in
+    downstream customer CMake projects from `-isystem` and `-I` and will
+    therefore restore about perfect backward compatibility.
+
+    **Approach-2:** Set the cache variable
+    `CMAKE_NO_SYSTEM_FROM_IMPORTED=TRUE` in a downstream CMake project to set
+    which will restore the include directories for the IMPORTED library
+    targets for the TriBITS project as non-SYSTEM include directories
+    (i.e. `-I`) but it will also cause all include directories for all
+    IMPORTED library targets to be non-SYSTEM (i.e. `-I`) even if they were
+    being handled as SYSTEM include directories before.  Therefore, that could
+    still break the downstream project as it might change what header files
+    are found for these other IMPORTED library targets and may expose many new
+    warnings (which may have been silenced by their include directories being
+    pulled in using `-isystem`).
+
+    **Approach-3:** Clean up the list of include directories that is searched
+    by the compiler so that only the correct header files can be found
+    (regardless of the search order).
+
+    **Approach-4:** Delete some header files in the set of searched include
+    directories so that only the correct header files can be found (regardless
+    of the search order).
+
+    **Approach-5:** Use other approaches more specific to the given customer
+    project.  For example, if multiple different versions of the googletest
+    (gtest) library header files can be found in the list of include
+    directories, then a customer project can build its own version of
+    googletest and put it's include directories first on the compile line and
+    list them with `-I` to ensure that only that version will be found, no
+    matter how many other versions of gtest are installed on the system.  For
+    an example of how this was done for one customer CMake project, see
+    https://github.com/trilinos/Trilinos/issues/8001#issuecomment-1032827124.
+
+    For more details on this change in the handling of include directories
+    with the switch to modern CMake, see
+    https://github.com/TriBITSPub/TriBITS/issues/443.
+
+
 ###############################################################################
 #                                                                             #
 # Trilinos Release 12.12 Release Notes                                        #

TPLsList.cmake

@@ -71,8 +71,8 @@ TRIBITS_REPOSITORY_DEFINE_TPLS(
   ARPREC          "packages/teuchos/cmake/tpls/"    ST
   QD              "packages/teuchos/cmake/tpls/"    ST
   MPI             "${${PROJECT_NAME}_TRIBITS_DIR}/core/std_tpls/" PT
-  BLAS            "${${PROJECT_NAME}_TRIBITS_DIR}/common_tpls/"   PT
-  LAPACK          "${${PROJECT_NAME}_TRIBITS_DIR}/common_tpls/"   PT
+  BLAS            "cmake/TPLs/"   PT
+  LAPACK          "cmake/TPLs/"   PT
   Boost           "${${PROJECT_NAME}_TRIBITS_DIR}/common_tpls/"   PT
   Scotch          "cmake/TPLs/"    ST
   OVIS            "cmake/TPLs/"    ST

cmake/TPLs/FindTPLBLAS.cmake

@@ -0,0 +1,80 @@
+# @HEADER
+# ************************************************************************
+#
+#            Trilinos: An Object-Oriented Solver Framework
+#                 Copyright (2001) Sandia Corporation
+#
+#
+# Copyright (2001) Sandia Corporation. Under the terms of Contract
+# DE-AC04-94AL85000, there is a non-exclusive license for use of this
+# work by or on behalf of the U.S. Government.  Export of this program
+# may require a license from the United States Government.
+#
+# 1. Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the Corporation nor the names of the
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
+# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# NOTICE:  The United States Government is granted for itself and others
+# acting on its behalf a paid-up, nonexclusive, irrevocable worldwide
+# license in this data to reproduce, prepare derivative works, and
+# perform publicly and display publicly.  Beginning five (5) years from
+# July 25, 2001, the United States Government is granted for itself and
+# others acting on its behalf a paid-up, nonexclusive, irrevocable
+# worldwide license in this data to reproduce, prepare derivative works,
+# distribute copies to the public, perform publicly and display
+# publicly, and to permit others to do so.
+#
+# NEITHER THE UNITED STATES GOVERNMENT, NOR THE UNITED STATES DEPARTMENT
+# OF ENERGY, NOR SANDIA CORPORATION, NOR ANY OF THEIR EMPLOYEES, MAKES
+# ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LEGAL LIABILITY OR
+# RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR USEFULNESS OF ANY
+# INFORMATION, APPARATUS, PRODUCT, OR PROCESS DISCLOSED, OR REPRESENTS
+# THAT ITS USE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS.
+#
+# ************************************************************************
+# @HEADER
+
+
+if (MSVC AND NOT
+    (BLAS_LIBRARY_DIRS  OR
+     (NOT "${BLAS_LIBRARY_NAMES}" STREQUAL "blas blas_win32" AND
+      NOT "${BLAS_LIBRARY_NAMES}" STREQUAL "") OR
+     BLAS_INCLUDE_DIRS  OR
+     BLAS_INCLUDE_NAMES OR
+     (NOT "${TPL_BLAS_LIBRARIES}" STREQUAL "blas" AND
+      NOT "${TPL_BLAS_LIBRARIES}" STREQUAL "") OR
+     TPL_BLAS_INCLUDE_DIRS)
+   )
+  # Find the CLAPACK built by CMake on the machine for MSVC if found it will
+  # set the BLAS and LAPACK libraries.  NOTE: This the FindCLAPACK module must
+  # be called every configure or this does not work!
+  # If the user has specified alternate name or location of their blas that
+  # will be used instead.
+  find_package(CLAPACK 3.2.1 NO_MODULE)
+  if (CLAPACK_FOUND)
+    advanced_set(TPL_BLAS_LIBRARIES blas
+      CACHE FILEPATH "Set from MSVC CLAPACK specialization")
+  endif()
+endif()
+
+tribits_tpl_find_include_dirs_and_libraries( BLAS
+  REQUIRED_LIBS_NAMES "blas blas_win32")

cmake/TPLs/FindTPLCUBLAS.cmake

@@ -63,8 +63,9 @@ ELSE()
   IF(CUDA_cublas_LIBRARY STREQUAL "CUDA_cublas_LIBRARY-NOTFOUND") 
     MESSAGE(FATAL_ERROR "\nCUBLAS: could not find cublas library.")
   ENDIF()
-  GLOBAL_SET(TPL_CUBLAS_LIBRARY_DIRS)
-  GLOBAL_SET(TPL_CUBLAS_INCLUDE_DIRS ${TPL_CUDA_INCLUDE_DIRS})
-  GLOBAL_SET(TPL_CUBLAS_LIBRARIES ${CUDA_cublas_LIBRARY})
+  SET(TPL_CUBLAS_LIBRARIES ${CUDA_cublas_LIBRARY})
 ENDIF()
 
+tribits_tpl_find_include_dirs_and_libraries(CUBLAS  REQUIRED_LIBS_NAMES  cublas)
+
+unset(TPL_CUBLAS_LIBRARIES)

cmake/TPLs/FindTPLCUSOLVER.cmake

@@ -63,8 +63,9 @@ ELSE()
   IF(CUDA_cusolver_LIBRARY STREQUAL "CUDA_cusolver_LIBRARY-NOTFOUND") 
     MESSAGE(FATAL_ERROR "\nCUSOLVER: could not find cusolver library.")
   ENDIF()
-  GLOBAL_SET(TPL_CUSOLVER_LIBRARY_DIRS)
-  GLOBAL_SET(TPL_CUSOLVER_INCLUDE_DIRS ${TPL_CUDA_INCLUDE_DIRS})
-  GLOBAL_SET(TPL_CUSOLVER_LIBRARIES ${CUDA_cusolver_LIBRARY})
+  SET(TPL_CUSOLVER_LIBRARIES ${CUDA_cusolver_LIBRARY})
 ENDIF()
 
+tribits_tpl_find_include_dirs_and_libraries(CUSOLVER  REQUIRED_LIBS_NAMES  cusparse)
+
+unset(TPL_CUSOLVER_LIBRARIES)

cmake/TPLs/FindTPLCUSPARSE.cmake

@@ -68,8 +68,9 @@ ELSE()
       MESSAGE(FATAL_ERROR "\nCUSPARSE: could not find cuspasre library.")
     ENDIF()
   ENDIF(CMAKE_VERSION VERSION_LESS "2.8.8")
-  GLOBAL_SET(TPL_CUSPARSE_LIBRARY_DIRS)
-  GLOBAL_SET(TPL_CUSPARSE_INCLUDE_DIRS ${TPL_CUDA_INCLUDE_DIRS})
-  GLOBAL_SET(TPL_CUSPARSE_LIBRARIES    ${CUDA_cusparse_LIBRARY})
+  SET(TPL_CUSPARSE_LIBRARIES    ${CUDA_cusparse_LIBRARY})
 ENDIF()
 
+tribits_tpl_find_include_dirs_and_libraries(CUSPARSE  REQUIRED_LIBS_NAMES  cusparse)
+
+unset(TPL_CUSPARSE_LIBRARIES)

cmake/TPLs/FindTPLCUSPARSEDependencies.cmake

@@ -0,0 +1,2 @@
+tribits_extpkg_define_dependencies( CUSPARSE
+  DEPENDENCIES  CUBLAS)

cmake/TPLs/FindTPLLAPACK.cmake

@@ -0,0 +1,74 @@
+# @HEADER
+# ************************************************************************
+#
+#            Trilinos: An Object-Oriented Solver Framework
+#                 Copyright (2001) Sandia Corporation
+#
+#
+# Copyright (2001) Sandia Corporation. Under the terms of Contract
+# DE-AC04-94AL85000, there is a non-exclusive license for use of this
+# work by or on behalf of the U.S. Government.  Export of this program
+# may require a license from the United States Government.
+#
+# 1. Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the Corporation nor the names of the
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
+# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# NOTICE:  The United States Government is granted for itself and others
+# acting on its behalf a paid-up, nonexclusive, irrevocable worldwide
+# license in this data to reproduce, prepare derivative works, and
+# perform publicly and display publicly.  Beginning five (5) years from
+# July 25, 2001, the United States Government is granted for itself and
+# others acting on its behalf a paid-up, nonexclusive, irrevocable
+# worldwide license in this data to reproduce, prepare derivative works,
+# distribute copies to the public, perform publicly and display
+# publicly, and to permit others to do so.
+#
+# NEITHER THE UNITED STATES GOVERNMENT, NOR THE UNITED STATES DEPARTMENT
+# OF ENERGY, NOR SANDIA CORPORATION, NOR ANY OF THEIR EMPLOYEES, MAKES
+# ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LEGAL LIABILITY OR
+# RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR USEFULNESS OF ANY
+# INFORMATION, APPARATUS, PRODUCT, OR PROCESS DISCLOSED, OR REPRESENTS
+# THAT ITS USE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS.
+#
+# ************************************************************************
+# @HEADER
+
+
+if (MSVC AND NOT
+    (LAPACK_LIBRARY_DIRS  OR
+     (NOT "${LAPACK_LIBRARY_NAMES}" STREQUAL "lapack lapack_win32" AND
+      NOT "${LAPACK_LIBRARY_NAMES}" STREQUAL "") OR
+     LAPACK_INCLUDE_DIRS  OR
+     LAPACK_INCLUDE_NAMES OR
+     (NOT "${TPL_LAPACK_LIBRARIES}" STREQUAL "lapack" AND
+      NOT "${TPL_LAPACK_LIBRARIES}" STREQUAL "") OR
+     TPL_LAPACK_INCLUDE_DIRS)
+   )
+  if(CLAPACK_FOUND)
+    advanced_set(TPL_LAPACK_LIBRARIES lapack
+        CACHE FILEPATH "Set from MSVC CLAPACK specialization")
+  endif()
+endif()
+
+tribits_tpl_find_include_dirs_and_libraries( LAPACK
+  REQUIRED_LIBS_NAMES "lapack lapack_win32")

cmake/TPLs/FindTPLLAPACKDependencies.cmake

@@ -0,0 +1,2 @@
+tribits_extpkg_define_dependencies( LAPACK
+  DEPENDENCIES  BLAS)

cmake/TPLs/FindTPLParMETIS.cmake

@@ -82,9 +82,7 @@ FUNCTION(CHECK_PARMETIS_HAS_VERSION_4_0_3  VARNAME)
 
   "
   )
-  SET(CMAKE_REQUIRED_INCLUDES ${TPL_ParMETIS_INCLUDE_DIRS})
-  SET(CMAKE_REQUIRED_LIBRARIES ${TPL_ParMETIS_LIBRARIES})
-  SET(CMAKE_REQUIRED_FLAGS ${CMAKE_EXE_LINKER_FLAGS})
+  SET(CMAKE_REQUIRED_LIBRARIES ParMETIS::all_libs)
   CHECK_C_SOURCE_COMPILES("${SOURCE}" ${VARNAME})
 ENDFUNCTION()
 

cmake/TPLs/FindTPLParMETISDependencies.cmake

@@ -0,0 +1,2 @@
+tribits_extpkg_define_dependencies( ParMETIS
+  DEPENDENCIES  METIS)

cmake/TPLs/FindTPLPthread.cmake

@@ -54,29 +54,33 @@
 # @HEADER
 
 
-SET(USE_THREADS FALSE)
+set(USE_THREADS FALSE)
 
-IF(NOT TPL_Pthread_INCLUDE_DIRS AND NOT TPL_Pthread_LIBRARY_DIRS AND NOT TPL_Pthread_LIBRARIES)
+if (NOT TPL_Pthread_INCLUDE_DIRS AND NOT TPL_Pthread_LIBRARY_DIRS
+    AND NOT TPL_Pthread_LIBRARIES
+  )
   # Use CMake's Thread finder since it is a bit smarter in determining
   # whether pthreads is already built into the compiler and doesn't need
   # a library to link.
-  FIND_PACKAGE(Threads)
+  find_package(Threads)
   #If Threads found a copy of pthreads make sure it is one of the cases the tribits
   #tpl system cannot handle.
-  IF(Threads_FOUND AND CMAKE_USE_PTHREADS_INIT)
-    IF(CMAKE_THREAD_LIBS_INIT STREQUAL "" OR CMAKE_THREAD_LIBS_INIT STREQUAL "-pthread")
-      SET(USE_THREADS TRUE)
-    ENDIF()
-  ENDIF()
-ENDIF()
+  if (Threads_FOUND  AND  CMAKE_USE_PTHREADS_INIT)
+    if(CMAKE_THREAD_LIBS_INIT STREQUAL "" OR  CMAKE_THREAD_LIBS_INIT  STREQUAL "-pthread")
+      set(USE_THREADS TRUE)
+      set(TPL_Pthread_INCLUDE_DIRS "")
+      set(TPL_Pthread_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
+      set(TPL_Pthread_LIBRARY_DIRS "")
+    endif()
+  endif()
+endif()
 
-IF(USE_THREADS)
-  SET(TPL_Pthread_INCLUDE_DIRS "")
-  SET(TPL_Pthread_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
-  SET(TPL_Pthread_LIBRARY_DIRS "")
-ELSE()
-  TRIBITS_TPL_FIND_INCLUDE_DIRS_AND_LIBRARIES( Pthread
+if (USE_THREADS  AND  CMAKE_THREAD_LIBS_INIT  STREQUAL "")
+  # Produce dummy Pthread::all_libs target and PthreadConfig.cmake file
+  tribits_tpl_find_include_dirs_and_libraries(Pthread)
+else()
+  tribits_tpl_find_include_dirs_and_libraries( Pthread
     REQUIRED_HEADERS pthread.h
     REQUIRED_LIBS_NAMES pthread
-      )
-ENDIF()
+    )
+endif()

cmake/TPLs/FindTPLScotch.cmake

@@ -94,9 +94,7 @@ FUNCTION(CHECK_SCOTCH_VERSION_6_0_3  VARNAME)
   }
   "
   )
-  SET(CMAKE_REQUIRED_INCLUDES ${TPL_Scotch_INCLUDE_DIRS})
-  SET(CMAKE_REQUIRED_LIBRARIES ${TPL_Scotch_LIBRARIES})
-  SET(CMAKE_REQUIRED_FLAGS ${CMAKE_EXE_LINKER_FLAGS})
+  SET(CMAKE_REQUIRED_LIBRARIES Scotch::all_libs)
   CHECK_C_SOURCE_COMPILES("${SOURCE}" ${VARNAME})
 ENDFUNCTION()