Added new function TRIBITS_TPL_ALLOW_PACKAGE_PREFIND() (TriBITS TriBI…

…TSPub#67) See TriBITS TriBITSPub#67 for details.
bartlettroscoe · May 6, 2015 · 1931a30 · 1931a30
1 parent 65830da
commit 1931a30
Show file tree

Hide file tree

Showing 5 changed files with 296 additions and 14 deletions.
diff --git a/test/core/CMakeLists.txt b/test/core/CMakeLists.txt
@@ -49,7 +49,7 @@ TRIBITS_ADD_ADVANCED_TEST( TestingFunctionMacro_UnitTests
       -D${PROJECT_NAME}_TRIBITS_DIR=${${PROJECT_NAME}_TRIBITS_DIR}
       -P "${CMAKE_CURRENT_SOURCE_DIR}/TestingFunctionMacro_UnitTests.cmake"
     PASS_REGULAR_EXPRESSION_ALL
-      "Final UnitTests Result: num_run = 406"
+      "Final UnitTests Result: num_run = 423"
       "Final UnitTests Result: PASSED"
   )
 

diff --git a/test/core/TestingFunctionMacro_UnitTests.cmake b/test/core/TestingFunctionMacro_UnitTests.cmake
@@ -54,6 +54,7 @@ INCLUDE(TribitsAddAdvancedTest)
 INCLUDE(TribitsAddExecutableAndTest)
 INCLUDE(TribitsETISupport)
 INCLUDE(TribitsFindPythonInterp)
+INCLUDE(TribitsTplFindIncludeDirsAndLibraries)
 INCLUDE(UnitTestHelpers)
 INCLUDE(GlobalSet)
 INCLUDE(GlobalNullSet)
@@ -84,7 +85,7 @@ INCLUDE(AppendStringVar)
 #
 
 
-FUNCTION(UNIT_TEST_APPEND_STRING_VAR)
+FUNCTION(UNITTEST_APPEND_STRING_VAR)
 
   MESSAGE("\n***")
   MESSAGE("*** Testing APPEND_STRING_VAR()")
@@ -126,7 +127,7 @@ FUNCTION(UNIT_TEST_APPEND_STRING_VAR)
 ENDFUNCTION()
 
 
-FUNCTION(UNIT_TEST_TRIBITS_FIND_PYTHON_INTERP)
+FUNCTION(UNITTEST_TRIBITS_FIND_PYTHON_INTERP)
 
   MESSAGE("\n***")
   MESSAGE("*** Testing TRIBITS_FIND_PYTHON_INTERP()")
@@ -249,6 +250,142 @@ FUNCTION(UNITEST_TRIBITS_MISC)
 ENDFUNCTION()
 
 
+MACRO(UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS  TPL_NAME)
+  SET(${TPL_NAME}_INCLUDE_DIRS "")
+  SET(${TPL_NAME}_LIBRARY_NAMES "")
+  SET(${TPL_NAME}_LIBRARY_DIRS "")
+  SET(${TPL_NAME}_FORCE_PACKAGE_PREFIND FALSE)
+  SET(TPL_${TPL_NAME}_INCLUDE_DIRS "")
+  SET(TPL_${TPL_NAME}_LIBRARIES "")
+  SET(TPL_${TPL_NAME}_LIBRARY_DIRS "")
+ENDMACRO()
+
+
+FUNCTION(UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND)
+
+  MESSAGE("\n***")
+  MESSAGE("*** Testing TRIBITS_TPL_ALLOW_PACKAGE_PREFIND()")
+  MESSAGE("***\n")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): No vars set")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "TRUE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set SomeTpl_INCLUDE_DIRS")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(SomeTpl_INCLUDE_DIRS "/some/include/dir")
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "FALSE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set SomeTpl_LIBRARY_NAMES")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(SomeTpl_LIBRARY_NAMES "lib1;lib2")
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "FALSE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set SomeTpl_LIBRARY_DIRS")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(SomeTpl_LIBRARY_DIRS "/some/lib/dir")
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "FALSE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set SomeTpl_[INCLUDE_DIRS,LIBRARY_NAMES,LIBRARY_DIRS]")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(SomeTpl_INCLUDE_DIRS "/some/include/dir")
+  SET(SomeTpl_LIBRARY_NAMES "lib1;lib2")
+  SET(SomeTpl_LIBRARY_DIRS "/some/lib/dir")
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "FALSE")
+
+  #SET(TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_DEBUG TRUE)
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): No vars set (2)")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "TRUE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set SomeTpl_INCLUDE_DIRS (force prefind)")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(SomeTpl_INCLUDE_DIRS "/some/include/dir")
+  SET(SomeTpl_FORCE_PACKAGE_PREFIND TRUE)
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "TRUE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set SomeTpl_LIBRARY_NAMES (force prefind)")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(SomeTpl_LIBRARY_NAMES "lib1;lib2")
+  SET(SomeTpl_FORCE_PACKAGE_PREFIND TRUE)
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "TRUE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set SomeTpl_LIBRARY_DIRS (force prefind)")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(SomeTpl_LIBRARY_DIRS "/some/lib/dir")
+  SET(SomeTpl_FORCE_PACKAGE_PREFIND TRUE)
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "TRUE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set SomeTpl_[INCLUDE_DIRS,LIBRARY_NAMES,LIBRARY_DIRS] (force prefind)")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(SomeTpl_INCLUDE_DIRS "/some/include/dir")
+  SET(SomeTpl_LIBRARY_NAMES "lib1;lib2")
+  SET(SomeTpl_LIBRARY_DIRS "/some/lib/dir")
+  SET(SomeTpl_FORCE_PACKAGE_PREFIND TRUE)
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "TRUE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): No vars set (3)")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "TRUE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set TPL_SomeTpl_INCLUDE_DIRS")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(TPL_SomeTpl_INCLUDE_DIRS "/some/include/dir")
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "FALSE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set TPL_SomeTpl_LIBRARIES")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(TPL_SomeTpl_LIBRARIES "/some/include/dir")
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "FALSE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set TPL_SomeTpl_LIBRARY_DIRS")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(TPL_SomeTpl_LIBRARY_DIRS "/some/lib/dir")
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "FALSE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set TPL_SomeTpl_[INCLUDE_DIRS,LIBRARIES,LIBRARY_DIRS]")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(TPL_SomeTpl_INCLUDE_DIRS "/some/include/dir")
+  SET(TPL_SomeTpl_LIBRARIES "/some/include/dir")
+  SET(TPL_SomeTpl_LIBRARY_DIRS "/some/lib/dir")
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "FALSE")
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): Set SomeTpl_INCLUDE_DIRS and TPL_SomeTpl_INCLUDE_DIRS (force update)")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  SET(SomeTpl_INCLUDE_DIRS "/some/include/dir")
+  SET(TPL_SomeTpl_INCLUDE_DIRS "/some/include/dir")
+  SET(SomeTpl_FORCE_PACKAGE_PREFIND TRUE)
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "FALSE")
+
+  #SET(TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_DEBUG TRUE)
+
+  # ToDo: Test that "force prefind" does not affect TPL_${TPL_NAME}_XXX logic
+
+  MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(): No vars set (4)")
+  UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_UNSET_VARS(SomeTpl)
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND(SomeTpl  SomeTpl_ALLOW_PACKAGE_PREFIND)
+  UNITTEST_COMPARE_CONST(SomeTpl_ALLOW_PACKAGE_PREFIND  "TRUE")
+
+ENDFUNCTION()
+
+
 FUNCTION(UNITEST_TRIBITS_ADD_TEST_BASIC)
 
   MESSAGE("\n***")
@@ -1748,7 +1885,7 @@ FUNCTION(UNITEST_TRIBITS_ADD_ADVANCED_TEST_CATEGORIES)
 
   # NOTE: The above tests ensure that the CATEGORIES argument is accepted and
   # processed correctly.  The unit tests in
-  # UNIT_TEST_TRIBITS_ADD_TEST_CATEGORIES() test the behavior of the logic for
+  # UNITTEST_TRIBITS_ADD_TEST_CATEGORIES() test the behavior of the logic for
   # selecting tests based on CATEGORIES.
 
 ENDFUNCTION()
@@ -2717,9 +2854,10 @@ MESSAGE("\n***")
 MESSAGE("*** Running little bits of tests")
 MESSAGE("***\n")
 
-UNIT_TEST_APPEND_STRING_VAR()
-UNIT_TEST_TRIBITS_FIND_PYTHON_INTERP()
+UNITTEST_APPEND_STRING_VAR()
+UNITTEST_TRIBITS_FIND_PYTHON_INTERP()
 UNITEST_TRIBITS_MISC()
+UNITTEST_TRIBITS_TPL_ALLOW_PACKAGE_PREFIND()
 
 # Set the default test categories
 SET(${PROJECT_NAME}_TEST_CATEGORIES NIGHTLY)
@@ -2770,4 +2908,4 @@ MESSAGE("*** Determine final result of all unit tests")
 MESSAGE("***\n")
 
 # Pass in the number of expected tests that must pass!
-UNITTEST_FINAL_RESULT(406)
+UNITTEST_FINAL_RESULT(423)
diff --git a/tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake b/tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake
@@ -53,6 +53,97 @@ INCLUDE(MultilineSet)
 INCLUDE(ParseVariableArguments)
 INCLUDE(SetNotFound)
 
+#
+# @FUNCTION: TRIBITS_TPL_ALLOW_PACKAGE_PREFIND()
+#
+# Function that determines if a TriBITS find module file
+# ``FindTPL<tplName>.cmake`` is allowed to call ``FIND_PACKAGE(<tplName>
+# ...)`` before calling `TRIBITS_TPL_FIND_INCLUDE_DIRS_AND_LIBRARIES()`_.
+#
+# Usage::
+#
+#   TRIBITS_TPL_ALLOW_PACKAGE_PREFIND( <tplName>
+#     <allowPackagePrefindOut> )
+#
+# The required arguments are:
+#
+#   ``<tplName>`` : The input name of the TriBITS TPL (e.g. ``HDF5``).
+#
+#   ``<allowPackagePrefindOut>`` : Name of a variable which will be set to
+#   ``TRUE`` on output if ``FIND_PACKAGE(<tplName> ...)`` should be called to
+#   find the TPL ``<tplName>`` or ``FALSE`` if it should not be called.
+#
+# This function will set ``<allowPackagePrefindOut>`` to ``FALSE`` if any of
+# the variables ``TPL_<tplName>_INCLUDE_DIRS``, ``${TPL_<tplName>_LIBRARIES``,
+# or ``TPL_<tplName>_LIBRARY_DIRS`` are set.  This allows the user to override
+# the search for the library components and just specify the absolute
+# locations.  The function will also set ``<allowPackagePrefindOut>`` to
+# ``FALSE`` if ``<tplName>_INCLUDE_DIRS``, ``<tplName>_LIBRARY_NAMES``, or
+# ``<tplName>_LIBRARY_DIRS`` is set and ``<tplName>_FORCE_PACKAGE_PREFIND`` is
+# set to ``FALSE``.  Otherwise, if ``<tplName>_FORCE_PACKAGE_PREFIND`` is set
+# to ``TRUE``, the function will not return ``FALSE`` for
+# ``<allowPackagePrefindOut>`` no matter what the values of
+# ``<tplName>_INCLUDE_DIRS``, ``<tplName>_LIBRARY_NAMES``, or
+# ``<tplName>_LIBRARY_DIRS``.
+#
+# The variable ``<tplName>_FORCE_PACKAGE_PREFIND`` is needed to allow users
+# (or the ``FindTPL<tplName>.cmake`` module itself) to avoid name clashes with
+# the variables ``<tplName>_INCLUDE_DIRS`` or ``<tplName>_LIBRARY_DIRS`` in
+# the usage of ``FIND_PACKAGE(<tplName> ...)`` because a lot of default
+# ``Find<tplName>.cmake`` modules also use these variables.  This function
+# sets ``<tplName>_FORCE_PACKAGE_PREFIND`` as a cache variable with default
+# value ``FALSE`` to maintain backward compatibility with existing
+# ``FindTPL<tplName>.cmake`` modules.
+#
+# See `How to Add use FIND_PACKAGE() for a TriBITS TPL`_ for details in how to
+# use this function to create a ``FindTPL<tplName>.cmake`` module file.
+#
+FUNCTION(TRIBITS_TPL_ALLOW_PACKAGE_PREFIND  TPL_NAME  ALLOW_PACAKGE_PREFIND_OUT)
+
+  IF (TRIBITS_TPL_ALLOW_PACKAGE_PREFIND_DEBUG)
+    MESSAGE("TRIBITS_TPL_ALLOW_PACKAGE_PREFIND: '${TPL_NAME}'  '${ALLOW_PACAKGE_PREFIND_OUT}'")
+    PRINT_VAR(${TPL_NAME}_INCLUDE_DIRS)
+    PRINT_VAR(${TPL_NAME}_LIBRARY_NAMES)
+    PRINT_VAR(${TPL_NAME}_LIBRARY_DIRS)
+    PRINT_VAR(${TPL_NAME}_FORCE_PACKAGE_PREFIND)
+  ENDIF()
+
+  ADVANCED_SET(${TPL_NAME}_FORCE_PACKAGE_PREFIND  FALSE
+    CACHE BOOL
+    "Determines if the variables ${TPL_NAME}_[INCLUDE_DIRS,LIBRARY_NAMES,LIBRARY_DIRS] should be ignored and the pre-find FIND_PACKAGE(${TPL_NAME} should be performed anyway.  But this will *not* do the pre-find if any of the TPL_${TPL_NAME}_[INCLUDE_DIRS,LIBRARY_NAMES,LIBRARY_DIRS] vars are set." )
+
+  # Start out with TRUE and set to FALSE in logic below
+  SET(ALLOW_PACAKGE_PREFIND TRUE)
+
+  IF (
+    (NOT "${TPL_${TPL_NAME}_INCLUDE_DIRS}" STREQUAL "")
+    OR (NOT "${TPL_${TPL_NAME}_LIBRARIES}" STREQUAL "")
+    OR (NOT "${TPL_${TPL_NAME}_LIBRARY_DIRS}" STREQUAL "")
+    )
+    # The user has selected one or more of the final vars so skip calling
+    # FIND_PACKAGE(${TPL_NAME} ...) ...
+    SET(ALLOW_PACAKGE_PREFIND FALSE)
+  ELSEIF (
+    (NOT "${${TPL_NAME}_INCLUDE_DIRS}" STREQUAL "")
+    OR (NOT "${${TPL_NAME}_LIBRARY_NAMES}" STREQUAL "")
+    OR (NOT "${${TPL_NAME}_LIBRARY_DIRS}" STREQUAL "")
+    )
+    # One ore more of the ${TPL_NAME}_XXX variables are set
+    IF (${TPL_NAME}_FORCE_PACKAGE_PREFIND)
+      # Even with one or more of the ${TPL_NAME}_XXX vars set, we still want
+      # to do the FIND_PACKAGE(${TPL_NAME} ...) search and ignore this
+      # override.
+    ELSE()
+      # We will not ignore the override of these variables and will instead go
+      # ahead and skip the pre-find.
+      SET(ALLOW_PACAKGE_PREFIND FALSE)
+    ENDIF()
+  ENDIF()
+
+  SET(${ALLOW_PACAKGE_PREFIND_OUT} ${ALLOW_PACAKGE_PREFIND} PARENT_SCOPE)
+
+ENDFUNCTION()
+
 
 #
 # @FUNCTION: TRIBITS_TPL_FIND_INCLUDE_DIRS_AND_LIBRARIES()

diff --git a/tribits/doc/developers_guide/TribitsDevelopersGuide.rst b/tribits/doc/developers_guide/TribitsDevelopersGuide.rst
@@ -2083,11 +2083,11 @@ packages that depend on that TPL will be automatically disabled as well (see
 For each TPL referenced in a `<repoDir>/TPLsList.cmake`_ file using the macro
 `TRIBITS_REPOSITORY_DEFINE_TPLS()`_, there must exist a file, typically called
 ``FindTPL${TPL_NAME}.cmake``, that once processed, produces the variables
-``${TPL_NAME}_LIBRARIES`` and ``${TPL_NAME}_INCLUDE_DIRS``.  Most
+``TPL_${TPL_NAME}_LIBRARIES`` and ``TPL_${TPL_NAME}_INCLUDE_DIRS``.  Most
 ``FindTPL${TPL_NAME}.cmake`` files just use the function
-`TRIBITS_TPL_FIND_INCLUDE_DIRS_AND_LIBRARIES()`_ the define the TriBITS TPL.  A simple
-example of such a file is the common TriBITS ``FindTPLPETSC.cmake`` module
-which is currently:
+`TRIBITS_TPL_FIND_INCLUDE_DIRS_AND_LIBRARIES()`_ the define the TriBITS TPL.
+A simple example of such a file is the common TriBITS ``FindTPLPETSC.cmake``
+module which is currently:
 
 .. include:: ../../common_tpls/FindTPLPETSC.cmake
    :literal:
@@ -2097,6 +2097,9 @@ Some concrete ``FindTPL${TPL_NAME}.cmake`` files actually do use
 guts of finding at TPL which is perfectly fine.  In this case, the purpose for
 the wrapping ``FindTPL${TPL_NAME}.cmake`` is to standardize the output
 variables ``TPL_${TPL_NAME}_INCLUDE_DIRS`` and ``TPL_${TPL_NAME}_LIBRARIES``.
+For more details on properly using ``FIND_PACKAGE()`` to define a
+``FindTPL${TPL_NAME}.cmake`` file, see `How to Add use FIND_PACKAGE() for a
+TriBITS TPL`_.
 
 Once the `<repoDir>/TPLsList.cmake`_ files are all processed, then each
 defined TPL ``TPL_NAME`` is assigned the following global non-cache variables:
@@ -5244,9 +5247,11 @@ To add a new TriBITS TPL, do the following:
    dependency.
 
 2) Create the TPL find module, e.g. ``<repoDir>/tpls/FindTPL<tplName>.cmake``
-   (see `TriBITS TPL`_ and `TRIBITS_TPL_FIND_INCLUDE_DIRS_AND_LIBRARIES()`_ for details).
-   List the default required header files and/or libraries that must be
-   provided by the TPL.
+   (see `TriBITS TPL`_ and `TRIBITS_TPL_FIND_INCLUDE_DIRS_AND_LIBRARIES()`_
+   for details).  List the default required header files and/or libraries that
+   must be provided by the TPL.  NOTE: This find module can also (optionally)
+   use ``FIND_PACKAGE(<tplName> ...)`` for the default find operation.  For
+   details, see `How to Add use FIND_PACKAGE() for a TriBITS TPL`_.
 
 3) Add a row for the new TPL to the `<repoDir>/TPLsList.cmake`_ file after any
    TPLs that this new TPL may depend on.
@@ -5276,6 +5281,53 @@ To add a new TriBITS TPL, do the following:
 .. package and refer to it here.
 
 
+How to Add use FIND_PACKAGE() for a TriBITS TPL
+-----------------------------------------------
+
+When defining a ``FindTPL<tplName>.cmake`` file, it is possible (and
+encouraged) to utilize ``FIND_PACKAGE(<tplName> ...)`` to provide the default
+find operation.  In order for the resulting ``FindTPL<tplName>.cmake`` to
+behave consistently between all the various TriBITS TPLs (and allow the
+standard TriBITS TPL find overrides) one must use the TriBITS function
+`TRIBITS_TPL_ALLOW_PACKAGE_PREFIND()`_ in combination with the function
+`TRIBITS_TPL_FIND_INCLUDE_DIRS_AND_LIBRARIES()`_.  The basic form of the
+resulting ``FindTPL<tplName>.cmake`` looks like::
+
+  TRIBITS_TPL_ALLOW_PACKAGE_PREFIND( <tplName>  <tplName>_ALLOW_PREFIND )
+  IF (<tplName>_ALLOW_PREFIND)
+    FIND_PACKAGE(<tplName> ...)
+    IF(<tplName>_FOUND)
+      SET(TPL_<tplName>_INCLUDE_DIRS ${<tplName>_INCLUDE_DIRS} CACHE PATH "...")
+      SET(TPL_<tplName>_LIBRARIES ${<tplName>_LIBRARIES} CACHE FILEPATH "...")
+      SET(TPL_<tplName>_LIBRARY_DIRS ${<tplName>_LIBRARY_DIRS} CACHE PATH "...")
+      ENDIF()
+  ENDIF()
+
+  TRIBITS_TPL_FIND_INCLUDE_DIRS_AND_LIBRARIES( <tplName>
+    REQUIRED_HEADERS ...
+    REQUIRED_LIBS_NAMES ...
+    )
+
+With this approach, we the ``FindTPL<tplName>.cmake`` module preserves all of
+the user behavior described in `Enabling support for an optional Third-Party
+Library (TPL)`_.
+
+If one wants to skip the overrides ``<tplName>_INCLUDE_DIRS``,
+``<tplName>_LIBRARY_NAMES``, or ``<tplName>_LIBRARY_DIRS``, then one can
+set::
+
+  SET(<tplName>_FORCE_PACKAGE_PREFIND TRUE CACHE BOOL "Always use
+    FIND_PACKAGE(<tplName> ...) unless using an explicit override")
+
+This avoid name classes with the variables ``<tplName>_INCLUDE_DIRS`` and
+``<tplName>_LIBRARY_DIRS`` which are often used in concrete
+``Find<tplName>.cmake`` modules.
+
+For a slightly more complex example, see ``FindTPLHDF5.cmake``:
+
+.. include:: ../../common_tpls/FindTPLHDF5.cmake
+   :literal:
+
 How to Add a new TriBITS Repository
 -----------------------------------