Merge pull request #622 from bartlettroscoe/library_names_doc

Document support for alternative libs with tribits_tpl_find_include_dirs_and_libraries() REQUIRED_LIBS_NAMES

Allow merge so we can see generated documentation and allow a post-merge reveiw.

tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake

@@ -141,7 +141,7 @@ endfunction()
 #     <tplName>
 #     [REQUIRED_HEADERS <header1> <header2> ...]
 #     [MUST_FIND_ALL_HEADERS]
-#     [REQUIRED_LIBS_NAMES <libname1> <libname2> ...]
+#     [REQUIRED_LIBS_NAMES "<libname1> <libname1alt1> ..." <libname2> ...]
 #     [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_<tplName>_INCLUDE_DIRS`` is already set).
 #
-#   ``REQUIRED_LIBS_NAMES``
+#   ``REQUIRED_LIBS_NAMES "<libname1> <libname1alt1> ..." <libname2> ...``
 #
 #     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 ``<tplName>_LIBRARY_NAMES`` (see below).
+#     libraries using ``find_library()``. A single list of library names of
+#     the form:
+#
+#       ``<libname1> <libname2> ...``
+#
+#     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:
+#
+#       ``"<libname1> <libname1alt1> <libname1alt2> ..."``
+#
+#     In this case, first, ``<libname1>`` is looked for and used if it is
+#     found.  If not found, then the next alternate library name
+#     ``<libname1alt1>`` 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 ``<tplName>_LIBRARY_NAMES`` (see below).
 #
 #   ``MUST_FIND_ALL_LIBS``
 #
@@ -206,7 +231,8 @@ endfunction()
 #   ``<tplName>_LIBRARY_NAMES`` (type ``STRING``)
 #
 #     List of library names to be looked for instead of what is specified in
-#     ``REQUIRED_LIBS_NAMES <libname1> <libname2> ...``.
+#     ``REQUIRED_LIBS_NAMES <libname1> <libname2> ...``.  If set, only a
+#     single set of libraries can be specified of which all need to be found.
 #
 #   ``<tplName>_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})
 

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 `<projectDir>/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 `<projectDir>/ProjectName.cmake`_ file (See `Python Support`_).  The
+  user can force a more recent version of Python by configuring with, for
+  example::
+
+    -D <Project>_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 `<projectDir>/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**

tribits/doc/guides/TribitsGuidesBody.rst

@@ -2006,15 +2006,17 @@ FindTPL<tplName>.cmake modules`_).
 
 The form of a simple ``FindTPL<tplName>.cmake`` file that uses an internal
 call to ``find_package(<externalPkg>)`` 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(<externalPkg> REQUIRED)
   tribits_extpkg_create_imported_all_libs_target_and_config_file(
     <tplName>
     INNER_FIND_PACKAGE_NAME <externalPkg>
     IMPORTED_TARGETS_FOR_ALL_LIBS <importedTarget0> <importedTarget1> ... )
 
-In this case, the purpose for the ``FindTPL<tplName>.cmake`` file (as apposed
+In this case, the purpose for the ``FindTPL<tplName>.cmake`` file (as opposed
 to a direct call to ``find_package(<externalPkg>)``) is to ensure the
 definition of the complete target ``<tplName>::all_libs`` which contains all
 usage requirements for the external package/TPL (i.e. all of the libraries,
@@ -2023,7 +2025,8 @@ file ``<tplName>Config.cmake``.
 
 The form of a simple ``FindTPL<tplName>.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( <tplName>
     REQUIRED_HEADERS <header0> <header1> ...
@@ -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( <tplName>
+    ...
+    REQUIRED_LIBS_NAMES "<libname0> <libname0alt0> <libname0alt1> ..." ...
+    ...
+    )
+
+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<tplName>.cmake modules
 +++++++++++++++++++++++++++++++++++++++++++++++