diff --git a/tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake b/tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake index 54f08d60f..722d0710a 100644 --- a/tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake +++ b/tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake @@ -141,7 +141,7 @@ endfunction() # # [REQUIRED_HEADERS ...] # [MUST_FIND_ALL_HEADERS] -# [REQUIRED_LIBS_NAMES ...] +# [REQUIRED_LIBS_NAMES " ..." ...] # [MUST_FIND_ALL_LIBS] # [NO_PRINT_ENABLE_SUCCESS_FAIL] # ) @@ -165,11 +165,36 @@ endfunction() # If set, then all of the header files listed in ``REQUIRED_HEADERS`` must # be found (unless ``TPL__INCLUDE_DIRS`` is already set). # -# ``REQUIRED_LIBS_NAMES`` +# ``REQUIRED_LIBS_NAMES " ..." ...`` # # List of libraries that are searched for when looking for the TPL's -# libraries using ``find_library()``. This list can be overridden by the -# user by setting ``_LIBRARY_NAMES`` (see below). +# libraries using ``find_library()``. A single list of library names of +# the form: +# +# `` ...`` +# +# are searched for and must all be found and will define the libraries for +# this TPL on the link line in that order. However, a library name along +# with alternate library names can be provided using outer quotes with +# inner spaces: +# +# ``" ..."`` +# +# In this case, first, ```` is looked for and used if it is +# found. If not found, then the next alternate library name +# ```` is looked for and is used if found. This continues +# with each successive alternate library name in the set until one is +# found. If none of the libraries in the set alternative names are found, +# then this is an error. Providing a set of alternate library names (in +# order of preference) allows the default find operation to look for +# different library names for different situations and implementations. +# For example, the BLAS library can be called ``blas``, ``openblas`` or +# ``atlas`` for different BLAS implementations and can be specified as: +# +# ``"blas openblas atlas"`` +# +# The list of required library names can be overridden by the user by +# setting ``_LIBRARY_NAMES`` (see below). # # ``MUST_FIND_ALL_LIBS`` # @@ -206,7 +231,8 @@ endfunction() # ``_LIBRARY_NAMES`` (type ``STRING``) # # List of library names to be looked for instead of what is specified in -# ``REQUIRED_LIBS_NAMES ...``. +# ``REQUIRED_LIBS_NAMES ...``. If set, only a +# single set of libraries can be specified of which all need to be found. # # ``_LIB_ENABLED_DEPENDENCIES`` # @@ -425,7 +451,7 @@ function(tribits_tpl_find_include_dirs_and_libraries TPL_NAME) message( "-- Searching for libs in ${TPL_NAME}_LIBRARY_DIRS='${${TPL_NAME}_LIBRARY_DIRS}'") - set(LIBRARIES_FOUND) + set(LIBRARIES_FOUND "") foreach(LIBNAME_SET ${REQUIRED_LIBS_NAMES}) @@ -438,7 +464,7 @@ function(tribits_tpl_find_include_dirs_and_libraries TPL_NAME) set(LIBNAME_LIST ${LIBNAME_SET}) separate_arguments(LIBNAME_LIST) - set(LIBNAME_SET_LIB) + set(LIBNAME_SET_LIB "") foreach(LIBNAME ${LIBNAME_LIST}) diff --git a/tribits/doc/guides/TribitsCoreDetailedReference.rst b/tribits/doc/guides/TribitsCoreDetailedReference.rst index aa443415c..1f07e959e 100644 --- a/tribits/doc/guides/TribitsCoreDetailedReference.rst +++ b/tribits/doc/guides/TribitsCoreDetailedReference.rst @@ -86,6 +86,7 @@ a given TriBITS project are: * `${PROJECT_NAME}_MAKE_INSTALL_GROUP_WRITABLE`_ * `${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE`_ * `${PROJECT_NAME}_MUST_FIND_ALL_TPL_LIBS`_ +* `${PROJECT_NAME}_Python3_FIND_VERSION`_ * `${PROJECT_NAME}_REQUIRES_PYTHON`_ * `${PROJECT_NAME}_SET_INSTALL_RPATH`_ * `${PROJECT_NAME}_SHOW_GIT_COMMIT_PARENTS`_ @@ -99,7 +100,6 @@ a given TriBITS project are: * `DART_TESTING_TIMEOUT`_ * `CMAKE_INSTALL_RPATH_USE_LINK_PATH`_ * `MPI_EXEC_MAX_NUMPROCS`_ -* `PythonInterp_FIND_VERSION`_ * `TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE`_ These options are described below. @@ -625,6 +625,23 @@ These options are described below. in the `/ProjectName.cmake`_ file. +.. _${PROJECT_NAME}_Python3_FIND_VERSION: + +**${PROJECT_NAME}_Python3_FIND_VERSION** + + Determines the version of Python that is looked for. TriBITS requires at + least version "3.6". A particular TriBITS project can require a higher + version of TriBITS and this is set using, for example: + + set(${PROJECT_NAME}_Python3_FIND_VERSION_DEFAULT "3.8") + + in the `/ProjectName.cmake`_ file (See `Python Support`_). The + user can force a more recent version of Python by configuring with, for + example:: + + -D _Python3_FIND_VERSION="3.8" + + .. _${PROJECT_NAME}_REQUIRES_PYTHON: **${PROJECT_NAME}_REQUIRES_PYTHON** @@ -877,22 +894,6 @@ These options are described below. has 64 cores, a reasonable number for ``MPI_EXEC_MAX_NUMPROCS_DEFAULT`` is 64. -.. _PythonInterp_FIND_VERSION: - -**PythonInterp_FIND_VERSION** - - Determines the version of Python that is looked for. TriBITS requires at - least version "2.7". A particular TriBITS project can require a higher - version of TriBITS and this is set using, for example: - - set(PythonInterp_FIND_VERSION_DEFAULT "3.5.2") - - in the `/ProjectName.cmake`_ file (See `Python Support`_). The - default is version "2.7". The user can force a more recent version of - Python by configuring with, for example:: - - -D PythonInterp_FIND_VERSION="3.6.2" - .. _TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE: **TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE** diff --git a/tribits/doc/guides/TribitsGuidesBody.rst b/tribits/doc/guides/TribitsGuidesBody.rst index 29a319fc6..bcd68bed1 100644 --- a/tribits/doc/guides/TribitsGuidesBody.rst +++ b/tribits/doc/guides/TribitsGuidesBody.rst @@ -2006,7 +2006,9 @@ FindTPL.cmake modules`_). The form of a simple ``FindTPL.cmake`` file that uses an internal call to ``find_package()`` which provides modern IMPORTED CMake -targets looks like:: +targets can use the +`tribits_extpkg_create_imported_all_libs_target_and_config_file()`_ function +and looks like:: find_package( REQUIRED) tribits_extpkg_create_imported_all_libs_target_and_config_file( @@ -2014,7 +2016,7 @@ targets looks like:: INNER_FIND_PACKAGE_NAME IMPORTED_TARGETS_FOR_ALL_LIBS ... ) -In this case, the purpose for the ``FindTPL.cmake`` file (as apposed +In this case, the purpose for the ``FindTPL.cmake`` file (as opposed to a direct call to ``find_package()``) is to ensure the definition of the complete target ``::all_libs`` which contains all usage requirements for the external package/TPL (i.e. all of the libraries, @@ -2023,7 +2025,8 @@ file ``Config.cmake``. The form of a simple ``FindTPL.cmake`` file that just provides a list of required header files and libraries that does **not** use an internal call -to ``find_package()`` looks like:: +to ``find_package()`` and instead uses the function +`tribits_tpl_find_include_dirs_and_libraries()`_ looks like:: tribits_tpl_find_include_dirs_and_libraries( REQUIRED_HEADERS ... @@ -5939,6 +5942,22 @@ header files and libraries that must be found. A simple MUST_FIND_ALL_LIBS ) +Note that a set of alternate names for each library can be specified using +quotes around the set of alternative library names using the syntax:: + + tribits_tpl_find_include_dirs_and_libraries( + ... + REQUIRED_LIBS_NAMES " ..." ... + ... + ) + +This is most commonly used for simple single-library TPLs like BLAS that has +different potential implementations like:: + + tribits_tpl_find_include_dirs_and_libraries( BLAS + REQUIRED_LIBS_NAMES "blas openblas atlas" + ... + ) Requirements for FindTPL.cmake modules +++++++++++++++++++++++++++++++++++++++++++++++