diff --git a/test/core/CMakeLists.txt b/test/core/CMakeLists.txt index 307fcf986..4df392791 100644 --- 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 index 48501f81a..fe69ee30e 100644 --- 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 index 6f1827067..f24b245a5 100644 --- 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 index be78498f0..016d0d338 100644 --- 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 ----------------------------------- diff --git a/tribits/doc/developers_guide/TribitsMacroFunctionDocTemplate.rst b/tribits/doc/developers_guide/TribitsMacroFunctionDocTemplate.rst index b6144c1b1..84821dafb 100644 --- a/tribits/doc/developers_guide/TribitsMacroFunctionDocTemplate.rst +++ b/tribits/doc/developers_guide/TribitsMacroFunctionDocTemplate.rst @@ -40,6 +40,7 @@ @FUNCTION: TRIBITS_SET_ST_FOR_DEV_MODE() + @MACRO: TRIBITS_SUBPACKAGE() + @MACRO: TRIBITS_SUBPACKAGE_POSTPROCESS() + +@FUNCTION: TRIBITS_TPL_ALLOW_PACKAGE_PREFIND() + @FUNCTION: TRIBITS_TPL_FIND_INCLUDE_DIRS_AND_LIBRARIES() + @FUNCTION: TRIBITS_TPL_TENTATIVELY_ENABLE() + @FUNCTION: TRIBITS_VERBOSE_PRINT_VAR() +