Add support for FindTPL<tplName>Dependencies.cmake files, update docs (…

…TriBITSPub#63, TriBITSPub#299, TriBITSPub#494)

This commit primarily adds support for FindTPL<tplName>Dependencies.cmake
files so you don't need to call tribits_external_package_define_dependencies()
from the TPLsList.cmake file (which was a terrible hack).

As part of this, I also updated the documentation related to external
packages/TPLs.

More specifically I did the following:

* Added support for FindTPL<tplName>Dependencies.cmake files which including
  adding a new TPL var <tplName>_DEPENDENCIES_FILE.  That included adding a
  new macro tribits_read_external_package_deps_files_add_to_graph() that gets
  run for each TPL during the generation of the project package dependencies
  (and added to teh call-graph for
  tribits_read_all_project_deps_files_create_deps_graph()).

* Expanded documentation on TriBITS External Packages/TPLs:

  - Properly listed out FindTPL<tplName>.cmake and
    FindTPL<tplName>Dependencies.cmake in the section 'TriBITS External
    Package/TPL Core Files'

  - Added linked documentation entries for FindTPL<tplName>.cmake and
    FindTPL<tplName>Dependencies.cmake

  - Updated list of step to add a new TPL

  - Added a section 'Creating FindTPL<tplName>.cmake file' with mini-toc to
    the subsections to make easy to navigate

  - Added MUST_FIND_ALL_LIBS to example calls of
    tribits_tpl_find_include_dirs_and_libraries()

* Refactored TribitsExampleProject2:

  - Added FindTPL<tplName>Depenencies.cmake files for Tpl2, Tpl3, and Tpl4.

  - Remove hacked calls to tribits_external_package_define_dependencies() in
    TPLsList.cmake

* Other users and maintainers guides updates:

  - Sorted items in TribitsSystemMacroFunctionDocTemplate.rst

  - Changed from 'FindTPL*.cmake' to 'FindTPL<tplName>.cmake' in the
    documentation (which I think looks better).

  - Other small documentation fixups I noticed while looking at this stuff.

* Changed over to foreach ( ... IN LISTS ... ) for a few loops.

tribits/core/package_arch/TribitsExternalPackageFindTplHelpers.cmake

@@ -64,8 +64,8 @@
 # ``find_dependency(<externalPkg>)`` (with no other argument) and then, again,
 # defines the correct imported library dependency.
 #
-# For more details, see `Creating FindTPL*.cmake using find_package() with
-# IMPORTED targets`_.
+# For more details, see `Creating FindTPL<tplName>.cmake using find_package()
+# with IMPORTED targets`_.
 #
 function(tribits_external_package_create_imported_all_libs_target_and_config_file
     tplName

tribits/core/package_arch/TribitsPackageDependencies.cmake

@@ -59,7 +59,7 @@ cmake_policy(SET CMP0057 NEW) # Support if ( ... IN_LIST ... )
 
 # @MACRO: tribits_external_package_define_dependencies()
 #
-# Macro called from inside of a ``FindTPL<tplName>Dependencies.cmake`` file to
+# Macro called from inside of a `FindTPL<tplName>Dependencies.cmake`_ file to
 # define the direct upstream dependencies an external package/TPL.
 #
 # Usage::

tribits/core/package_arch/TribitsProcessTplsLists.cmake

@@ -74,13 +74,13 @@ include(Split)
 #    ``SOMETPL``).
 #
 # 1. **FINDMOD** (``<tpli_findmod>``): The relative path for the find module,
-#    usually with the name ``FindTPL<tplName>.cmake``.  This path is relative
-#    to the repository base directory.  If just the base path for the find
-#    module is given, ending with ``"/"`` (e.g. ``"cmake/tpls/"``), then the
-#    find module will be assumed to be under that this directory with the
-#    standard name (e.g. ``cmake/tpls/FindTPL<tplName>.cmake``).  A standard
-#    way to write a ``FindTPL<tplName>.cmake`` module is to use the function
-#    `tribits_tpl_find_include_dirs_and_libraries()`_.
+#    usually with the name `FindTPL<tplName>.cmake`_.  This path is relative
+#    to the repository base directory ``<repoDir>``.  If just the base path
+#    for the find module is given, ending with ``"/"``
+#    (e.g. ``"cmake/tpls/"``), then the find module will be assumed to be
+#    under that this directory with the standard name
+#    ``FindTPL<tplName>.cmake``.  (See `Creating the FindTPL<tplName>.cmake
+#    file`_.)
 #
 # 2. **CLASSIFICATION** (``<pkgi_classif>``): Gives the `SE Package Test
 #    Group`_ `PT`_, `ST`_, or `EX`_ and the maturity level ``EP``, ``RS``,
@@ -130,13 +130,15 @@ endmacro()
 # and updates the project-level variables::
 #
 #   ${PROJECT_NAME}_TPLS
-#   ${PROJECT_NAME}_NUM_TPLS,
+#   ${PROJECT_NAME}_NUM_TPLS
 #   ${PROJECT_NAME}_REVERSE_TPLS
 #
 # For each TPL, it also sets the variables::
 #
 #   ${TPL_NAME}_FINDMOD
 #   ${TPL_NAME}_TESTGROUP
+#   ${TPL_NAME}_DEPENDENCIES_FILE
+#   ${TPL_NAME}_TPLS_LIST_FILE
 #
 # See `Function call tree for constructing package dependency graph`_
 #
@@ -258,16 +260,31 @@ macro(tribits_process_tpls_lists  REPOSITORY_NAME  REPOSITORY_DIR)
         set(${TPL_NAME}_FINDMOD ${TPL_FINDMOD_STD_NAME})
       endif()
 
+      # Set ${TPL_NAME}_DEPENDENCIES_FILE
+
+      # Breakdown ${${TPL_NAME}_FINDMOD} into parts <dir>/<base>.<ext>
+      get_filename_component(tpl_findmod_dir ${${TPL_NAME}_FINDMOD} DIRECTORY)
+      get_filename_component(tpl_findmod_base ${${TPL_NAME}_FINDMOD} NAME_WLE)
+      get_filename_component(tpl_findmod_ext ${${TPL_NAME}_FINDMOD} LAST_EXT)
+
+      set(${TPL_NAME}_DEPENDENCIES_FILE
+        "${tpl_findmod_dir}/${tpl_findmod_base}Dependencies${tpl_findmod_ext}")
+
+      # Set ${TPL_NAME}_TPLS_LIST_FILE
+
       assert_defined(${REPOSITORY_NAME}_TPLS_FILE)
       set(${TPL_NAME}_TPLS_LIST_FILE ${${REPOSITORY_NAME}_TPLS_FILE})
 
-      if (${PROJECT_NAME}_VERBOSE_CONFIGURE)
-        print_var(${TPL_NAME}_FINDMOD)
+      # Print variables/properties for the TPL
+
+      if (${PROJECT_NAME}_VERBOSE_CONFIGURE  OR  TRIBITS_PROCESS_TPLS_LISTS_VERBOSE)
         print_var(${TPL_NAME}_TESTGROUP)
+        print_var(${TPL_NAME}_FINDMOD)
+        print_var(${TPL_NAME}_DEPENDENCIES_FILE)
         print_var(${TPL_NAME}_TPLS_LIST_FILE)
       endif()
 
-      # Set the enable cache variable for ${TPL_NAME}
+      # Set cache var TPL_ENABLE_${TPL_NAME} with default ""
 
       multiline_set(DOCSTR
         "Enable support for the TPL ${TPL_NAME} in all supported ${PROJECT_NAME} packages."
@@ -277,8 +294,9 @@ macro(tribits_process_tpls_lists  REPOSITORY_NAME  REPOSITORY_DIR)
 
       # 2008/11/25: rabartl: Above, we use the prefix TPL_ instead of
       # ${PROJECT_NAME}_ in order to make it clear that external TPLs are
-      # different from packages so users don't get confused and
-      # think that the project actually includes some TPL when it does not!
+      # different from packages so users don't get confused and think that the
+      # project actually includes the source code and internal build for some
+      # TPL when it does not!
 
     endforeach()
 

tribits/core/package_arch/TribitsReadDepsFilesCreateDepsGraph.cmake

@@ -179,17 +179,21 @@ endmacro()
 #
 macro(tribits_read_all_package_deps_files_create_deps_graph)
 
+  foreach(tribitsExternalPkg  IN  LISTS  ${PROJECT_NAME}_DEFINED_TPLS)
+    tribits_read_external_package_deps_files_add_to_graph(${tribitsExternalPkg})
+  endforeach()
+
   set(${PROJECT_NAME}_SE_PACKAGES "") # Packages and subpackages
 
-  foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_PACKAGES})
+  foreach(TRIBITS_PACKAGE  IN  LISTS ${PROJECT_NAME}_PACKAGES)
     tribits_read_toplevel_package_deps_files_add_to_graph(${TRIBITS_PACKAGE}
       ${${TRIBITS_PACKAGE}_REL_SOURCE_DIR})
   endforeach()
 
   # Create a reverse SE packages list for later use
-  set(${PROJECT_NAME}_REVERSE_SE_PACKAGES ${${PROJECT_NAME}_SE_PACKAGES})
+  set(${PROJECT_NAME}_REVERSE_SE_PACKAGES  ${${PROJECT_NAME}_SE_PACKAGES})
   if (${PROJECT_NAME}_REVERSE_SE_PACKAGES)
-    list(REVERSE ${PROJECT_NAME}_REVERSE_SE_PACKAGES)
+    list(REVERSE  ${PROJECT_NAME}_REVERSE_SE_PACKAGES)
   endif()
 
   list(LENGTH ${PROJECT_NAME}_SE_PACKAGES ${PROJECT_NAME}_NUM_SE_PACKAGES)
@@ -198,11 +202,36 @@ macro(tribits_read_all_package_deps_files_create_deps_graph)
 endmacro()
 
 
+# @MACRO: tribits_read_external_package_deps_files_add_to_graph()
+#
+# Reads in dependencies for the external packages/TPL ``<tplName>`` and
+# creates the package dependency graph entries for it.
+#
+# Usage::
+#
+#   tribits_read_external_package_deps_files_add_to_graph(<tplName>)
+#
+# This reads in the file ``${<tplName>_DEPENDENCIES_FILE}`` and sets the
+# varaible::
+#
+#   <tplName>_LIB_ALL_DEPENDENCIES
+#
+# See `Function call tree for constructing package dependency graph`_
+#
+macro(tribits_read_external_package_deps_files_add_to_graph  tplName)
+  set(absTplDepsFile "${${PROJECT_NAME}_SOURCE_DIR}/${${tplName}_DEPENDENCIES_FILE}")
+  if (EXISTS "${absTplDepsFile}")
+    tribits_trace_file_processing(TPL  INCLUDE  "${absTplDepsFile}")
+    include(${absTplDepsFile})
+  endif()
+endmacro()
+
+
 # @MACRO: tribits_read_toplevel_package_deps_files_add_to_graph()
 #
 # Usage::
 #
-#  tribits_read_toplevel_package_deps_files_add_to_graph(<packageName>)
+#   tribits_read_toplevel_package_deps_files_add_to_graph(<packageName>)
 #
 # Macro that reads in package dependencies for a top-level package from the
 # file `<packageDir>/cmake/Dependencies.cmake`_ and appends the forward

tribits/core/package_arch/TribitsSystemDataStructuresMacrosFunctions.rst

@@ -495,7 +495,9 @@ lists and dependency data-structures described above.
 |     `tribits_process_project_dependency_setup_file()`_
 |       ``include(``  `<projectDir>/cmake/ProjectDependenciesSetup.cmake`_ ``)``
 |     `tribits_read_all_package_deps_files_create_deps_graph()`_
-|       Foreach ``TOPLEVEL_PACKAGE``:
+|       Foreach  ``EXTERNAL_PACKAGE`` in ``${PROJECT_NAME}_DEFINED_TPLS``:
+|         `tribits_read_external_package_deps_files_add_to_graph()`_
+|       Foreach ``TOPLEVEL_PACKAGE`` in ``${PACKAGE_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES``:
 |         `tribits_read_toplevel_package_deps_files_add_to_graph()`_
 |           `tribits_prep_to_read_dependencies()`_
 |           ``include(`` `<packageDir>/cmake/Dependencies.cmake`_ ``)``

tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake

@@ -99,8 +99,8 @@ include(Split)
 # to disable the prefind call to ``find_package()`` even if it would be
 # allowed otherwise.
 #
-# See `Creating FindTPL*.cmake using find_package() without IMPORTED targets`_
-# for details in how to use this function to create a
+# See `Creating FindTPL<tplName>.cmake using find_package() without IMPORTED
+# targets`_ for details in how to use this function to create a
 # ``FindTPL<tplName>.cmake`` module file.
 #
 function(tribits_tpl_allow_pre_find_package  TPL_NAME  ALLOW_PACKAGE_PREFIND_OUT)

tribits/doc/guides/ReducedMockTrilinosOutput/ExpectedDependencies.txt

@@ -27,7 +27,21 @@ Printing package dependencies ...
 -- Thyra_LIB_REQUIRED_DEP_PACKAGES: ThyraCoreLibs
 -- Thyra_LIB_OPTIONAL_DEP_PACKAGES: ThyraGoodStuff ThyraCrazyStuff ThyraEpetra ThyraEpetraExt
 
-Dumping direct dependencies for each SE package ...
+Dumping direct dependencies for each package ...
+
+-- MPI_LIB_ALL_DEPENDENCIES:
+
+-- BLAS_LIB_ALL_DEPENDENCIES:
+
+-- LAPACK_LIB_ALL_DEPENDENCIES:
+
+-- Boost_LIB_ALL_DEPENDENCIES:
+
+-- UMFPACK_LIB_ALL_DEPENDENCIES:
+
+-- AMD_LIB_ALL_DEPENDENCIES:
+
+-- PETSC_LIB_ALL_DEPENDENCIES:
 
 -- Teuchos_LIB_ENABLED_DEPENDENCIES: BLAS LAPACK
 -- Teuchos_LIB_ALL_DEPENDENCIES: BLAS LAPACK Boost MPI