Break out tribits_add_test() modules to core/test_support/ (#368, #582)

This breaks some test support related modules for the function
tribits_add_test() into their own subdirectory:

  tribits/core/test_support/

and include them with explicit relative and absolute includes and not relying
on CMAKE_MODULE_PATH.  (By using explicit includes we can better see and
manage the dependencies between modules on these separate subdirs and better
partition TriBITS.)

To cleanly break out these test_support modules, I created a new subidr:

  tribits/core/common/

and put the modules TribitsCMakePolicies.cmake and TribitsConstants.cmake into
them.  And I also did not add this new subdir to CMAKE_MODULE_PATH for the
same reason as above for test_support.  This allows some non-test-related
modules in tribits/core/package_arch/ to depend on tribits/core/common/ but
not tribits/core/test_support/.

Technically, this commit is the start of the componitization of TriBITS Core
as per #368.

test/core/TestingFunctionMacro_UnitTests.cmake

@@ -49,9 +49,10 @@ set( CMAKE_MODULE_PATH
 
 set(TRIBITS_ADD_EXECUTABLE_UNIT_TESTING ON)
 
+include("${${PROJECT_NAME}_TRIBITS_DIR}/core/test_support/TribitsTestCategories.cmake")
+include("${${PROJECT_NAME}_TRIBITS_DIR}/core/test_support/TribitsAddTest.cmake")
+
 include(MessageWrapper)
-include(TribitsTestCategories)
-include(TribitsAddTest)
 include(TribitsAddAdvancedTest)
 include(TribitsAddExecutableAndTest)
 include(TribitsETISupport)

test/core/TribitsProcessExtraRepositoriesList_UnitTests.cmake

@@ -42,12 +42,14 @@ cmake_minimum_required(VERSION 3.23.0 FATAL_ERROR)
 message("PROJECT_NAME = ${PROJECT_NAME}")
 message("${PROJECT_NAME}_TRIBITS_DIR = ${${PROJECT_NAME}_TRIBITS_DIR}")
 
+include("${${PROJECT_NAME}_TRIBITS_DIR}/core/common/TribitsCMakePolicies.cmake"
+  NO_POLICY_SCOPE)
+
 set( CMAKE_MODULE_PATH
   "${${PROJECT_NAME}_TRIBITS_DIR}/core/utils"
   "${${PROJECT_NAME}_TRIBITS_DIR}/core/package_arch"
   )
 
-include(TribitsCMakePolicies  NO_POLICY_SCOPE)
 include(TribitsProcessExtraRepositoriesList)
 include(UnitTestHelpers)
 include(GlobalSet)

tribits/README.DIRECTORY_CONTENTS.rst

@@ -22,9 +22,10 @@ TriBITS refactorings of TriBITS.
 
 .. _TriBITS Core:
 
-**core/**: Core TriBITS package-based architecture for CMake projects. This
-only depends on raw CMake and contains just the minimal support for building,
-testing, installing, and deployment.  Only depends on CMake and nothing else.
+**core/**: Core TriBITS test support and package-based architecture for CMake
+projects. This only depends on raw CMake and contains just the minimal support
+for building, testing, installing, and deployment.  This CMake code depends
+only on CMake and nothing else.
 
 **python_utils/**: Some basic Python utilities that are not specific to
 TriBITS but are used in TriBITS CI and testing support software.  There are
@@ -86,3 +87,49 @@ subdirectory. It supports the argument ``--components`` with values ``core``,
 * ``examples`` => (external tribits installation)
 * ``doc`` => ``core``, ``ci_support``, ``examples``
 * ``devtools_install`` => ``python_utils``
+
+
+TriBITS Core Directory Contents
+...............................
+
+The TriBITS ``core/`` directory is broken down into several subdirectories of
+its own:
+
+**core/utils**: General CMake utilities that are not specific to the TriBITS
+system and can be reused in any CMake project.
+
+**core/common**: As small set of common modules that the different TriBITS
+Core module files in different directories depend on.  These include things
+like common TriBITS constants and TriBITS CMake policies.
+
+**core/test_support**: Modules that help define CTest tests using functions
+like `tribits_add_test()`_ and `tribits_add_advanced_test()`_.  These can be
+used in CMake projects that are not full-blown TriBITS projects.
+
+**core/config_tests**: Some basic configure-time tests used by the TriBITS
+package architecture framework.
+
+**core/std_tpls**: Some ``Find<tplName>.cmake`` files for key external
+dependencies handled as TriBITS TPLs but are more central to the TriBITS
+system.  (Examples include CUDA and MPI support.)
+
+**core/installation**: A collection of ``*.cmake.in`` and related Cmake code
+supporting installations.
+
+**core/package_arch**: Modules for the full-blown TriBITS package architecture
+framework including package dependency management, multi-repository support,
+installations (including the generation of ``<Package>Config.cmake`` files),
+etc.
+
+The dependencies between these different TriBITS `core` subdirectories are:
+
+* ``core/utils`` => (external CMake)
+* ``core/common`` => ``core/utils``
+* ``core/test_support`` =>   ``core/utils``, ``core/common``
+* ``core/config_tests`` => (external CMake)
+* ``core/std_tpls`` => (external CMake)
+* ``core/installation`` <=> ``core/package_arch`` (bidirectional)
+* ``core/package_arch`` => ``core/utils``, ``core/common``,
+  ``core/test_support``, ``core/config_tests``, ``core/std_tpls``,
+  ``core/installation``
+

tribits/ci_support/TribitsDumpDepsXmlScript.cmake

@@ -100,16 +100,16 @@ endif()
 get_filename_component( ${PROJECT_NAME}_TRIBITS_DIR  "${CMAKE_CURRENT_LIST_DIR}/.."  ABSOLUTE )
 message("-- Setting ${PROJECT_NAME}_TRIBITS_DIR=${${PROJECT_NAME}_TRIBITS_DIR}")
 
+include("${CMAKE_CURRENT_LIST_DIR}/../core/common/TribitsConstants.cmake")
+tribits_asesrt_minimum_cmake_version()
+include("${CMAKE_CURRENT_LIST_DIR}/../core/common/TribitsCMakePolicies.cmake"  NO_POLICY_SCOPE)
+
 set( CMAKE_MODULE_PATH
   "${${PROJECT_NAME}_TRIBITS_DIR}/core/utils"
   "${${PROJECT_NAME}_TRIBITS_DIR}/core/package_arch"
   "${${PROJECT_NAME}_TRIBITS_DIR}/ci_support"
   )
 
-include(TribitsConstants)
-tribits_asesrt_minimum_cmake_version()
-include(TribitsCMakePolicies  NO_POLICY_SCOPE)
-
 include(TribitsGlobalMacros)
 include(TribitsPrintDependencyInfo)
 include(TribitsWriteXmlDependenciesFiles)

tribits/ci_support/TribitsGetExtraReposForCheckinTest.cmake

@@ -82,11 +82,12 @@ set(${PROJECT_NAME}_CHECK_EXTRAREPOS_EXIST  ${CHECK_EXTRAREPOS_EXIST})
 # B) Include files from TriBITS
 #
 
+include("${CMAKE_CURRENT_LIST_DIR}/../core/common/TribitsCMakePolicies.cmake"  NO_POLICY_SCOPE)
+
 set( CMAKE_MODULE_PATH
   "${${PROJECT_NAME}_TRIBITS_DIR}/core/utils"
   "${${PROJECT_NAME}_TRIBITS_DIR}/core/package_arch"
   )
-include(TribitsCMakePolicies  NO_POLICY_SCOPE)
 include(Split)
 include(AppendStringVar)
 include(SetDefaultAndFromEnv) # Used in ExtraRepositoriesList.cmake file?

tribits/core/package_arch/TribitsAddAdvancedTest.cmake

@@ -37,10 +37,10 @@
 # ************************************************************************
 # @HEADER
 
-include(TribitsCMakePolicies  NO_POLICY_SCOPE)
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsCMakePolicies.cmake"  NO_POLICY_SCOPE)
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsConstants.cmake")
 
 include(TribitsAddAdvancedTestHelpers)
-include(TribitsConstants)
 
 include(TribitsPrintList)
 include(AppendStringVar)

tribits/core/package_arch/TribitsAddAdvancedTestHelpers.cmake

@@ -38,7 +38,7 @@
 # @HEADER
 
 
-include(TribitsAddTestHelpers)
+include("${CMAKE_CURRENT_LIST_DIR}/../test_support/TribitsAddTestHelpers.cmake")
 
 
 # Set default ax number of TEST_<idx> blocks in tribits_add_advanced_test()

tribits/core/package_arch/TribitsAddExecutable.cmake

@@ -38,9 +38,9 @@
 # @HEADER
 
 
-include(TribitsAddExecutableTestHelpers)
+include("${CMAKE_CURRENT_LIST_DIR}/../test_support/TribitsAddExecutableTestHelpers.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/../test_support/TribitsAddTestHelpers.cmake")
 include(TribitsCommonArgsHelpers)
-include(TribitsAddTestHelpers)
 include(TribitsGeneralMacros)
 include(TribitsLibIsTestOnly)
 include(TribitsReportInvalidTribitsUsage)

tribits/core/package_arch/TribitsAddExecutableAndTest.cmake

@@ -38,8 +38,9 @@
 # @HEADER
 
 
+include("${CMAKE_CURRENT_LIST_DIR}/../test_support/TribitsAddTest.cmake")
+
 include(TribitsAddExecutable)
-include(TribitsAddTest)
 include(TribitsDeprecatedHelpers)
 
 

tribits/core/package_arch/TribitsCopyFilesToBinaryDir.cmake

@@ -38,7 +38,6 @@
 # @HEADER
 
 
-include(TribitsAddTestHelpers)
 include(CMakeParseArguments)
 
 

tribits/core/package_arch/TribitsGlobalMacros.cmake

@@ -38,11 +38,14 @@
 # @HEADER
 
 # Standard TriBITS system includes
-include(TribitsConstants)
+
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsConstants.cmake")
+
+include("${CMAKE_CURRENT_LIST_DIR}/../test_support/TribitsTestCategories.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/../test_support/TribitsAddTestHelpers.cmake")
+
 include(TribitsSetupMPI)
-include(TribitsTestCategories)
 include(TribitsGeneralMacros)
-include(TribitsAddTestHelpers)
 include(TribitsVerbosePrintVar)
 include(TribitsProcessEnabledTpls)
 include(TribitsInstallHeaders)

tribits/core/package_arch/TribitsPackageDependencies.cmake

@@ -50,7 +50,8 @@
 
 include_guard()
 
-include(TribitsCMakePolicies  NO_POLICY_SCOPE)
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsCMakePolicies.cmake"
+  NO_POLICY_SCOPE)
 
 include(TribitsParseArgumentsHelpers)
 include(MessageWrapper)

tribits/core/package_arch/TribitsPackageMacros.cmake

@@ -51,12 +51,13 @@ include(PrependGlobalSet)
 include(RemoveGlobalDuplicates)
 include(TribitsGatherBuildTargets)
 
+include("${CMAKE_CURRENT_LIST_DIR}/../test_support/TribitsAddTest.cmake")
+
 include(TribitsAddOptionAndDefine)
 include(TribitsPkgExportCacheVars)
 include(TribitsLibraryMacros)
 include(TribitsAddExecutable)
 include(TribitsAddExecutableAndTest)
-include(TribitsAddTest)
 include(TribitsAddAdvancedTest)
 include(TribitsCopyFilesToBinaryDir)
 include(TribitsReportInvalidTribitsUsage)

tribits/core/package_arch/TribitsProcessTplsLists.cmake

@@ -38,7 +38,7 @@
 # @HEADER
 
 
-include(TribitsConstants)
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsConstants.cmake")
 include(TribitsListHelpers)
 
 include(PrintVar)

tribits/core/package_arch/TribitsProject.cmake

@@ -66,7 +66,7 @@ if (${PROJECT_NAME}_VERBOSE_CONFIGURE)
 endif()
 
 # Overrides that we have for CMake functions
-include(TribitsCMakePolicies  NO_POLICY_SCOPE)
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsCMakePolicies.cmake"  NO_POLICY_SCOPE)
 include(TribitsProjectImpl)
 
 

tribits/core/package_arch/TribitsProjectImpl.cmake

@@ -47,6 +47,8 @@ set(CMAKE_MODULE_PATH
    ${CMAKE_CURRENT_SOURCE_DIR}
    ${CMAKE_CURRENT_SOURCE_DIR}/cmake
    ${${PROJECT_NAME}_TRIBITS_DIR}/core/utils
+   ${${PROJECT_NAME}_TRIBITS_DIR}/core/common
+   ${${PROJECT_NAME}_TRIBITS_DIR}/core/test_support
    ${${PROJECT_NAME}_TRIBITS_DIR}/core/package_arch
    ${${PROJECT_NAME}_TRIBITS_DIR}/core/config_tests
    ${${PROJECT_NAME}_TRIBITS_DIR}/core/modules
@@ -57,9 +59,9 @@ if (${PROJECT_NAME}_VERBOSE_CONFIGURE)
   message("CMAKE_MODULE_PATH='${CMAKE_MODULE_PATH}'")
 endif()
 
-include(TribitsConstants)
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsConstants.cmake")
 tribits_asesrt_minimum_cmake_version()
-include(TribitsCMakePolicies  NO_POLICY_SCOPE)
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsCMakePolicies.cmake"  NO_POLICY_SCOPE)
 
 # TriBITS package_arch includes
 include(TribitsIncludeDirectories)

tribits/core/package_arch/TribitsReadAllProjectDepsFilesCreateDepsGraph.cmake

@@ -39,7 +39,7 @@
 
 
 # Standard TriBITS system includes
-include(TribitsConstants)
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsConstants.cmake")
 include(TribitsProcessExtraRepositoriesList)
 include(TribitsProcessPackagesAndDirsLists)
 include(TribitsProcessTplsLists)

tribits/core/package_arch/TribitsAddExecutableTestHelpers.cmake → tribits/core/test_support/TribitsAddExecutableTestHelpers.cmake

@@ -39,7 +39,7 @@
 
 include_guard()
 
-include("${CMAKE_CURRENT_LIST_DIR}/TribitsCMakePolicies.cmake"  NO_POLICY_SCOPE)
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsCMakePolicies.cmake"  NO_POLICY_SCOPE)
 
 include("${CMAKE_CURRENT_LIST_DIR}/../utils/AdvancedSet.cmake")
 include("${CMAKE_CURRENT_LIST_DIR}/../utils/MessageWrapper.cmake")

tribits/core/package_arch/TribitsAddTest.cmake → tribits/core/test_support/TribitsAddTest.cmake

@@ -38,7 +38,7 @@
 # @HEADER
 
 
-include("${CMAKE_CURRENT_LIST_DIR}/TribitsCMakePolicies.cmake"  NO_POLICY_SCOPE)
+include("${CMAKE_CURRENT_LIST_DIR}/../common/TribitsCMakePolicies.cmake"  NO_POLICY_SCOPE)
 include("${CMAKE_CURRENT_LIST_DIR}/TribitsAddTestHelpers.cmake")
 
 

tribits/ctest_driver/TribitsCTestDriverCore.cmake

@@ -137,22 +137,24 @@ if ("${CTEST_BINARY_DIRECTORY}" STREQUAL "")
   set(CTEST_BINARY_DIRECTORY $ENV{PWD}/BUILD)
 endif()
 
+include("${CMAKE_CURRENT_LIST_DIR}/../core/common/TribitsConstants.cmake")
+tribits_asesrt_minimum_cmake_version()
+include("${CMAKE_CURRENT_LIST_DIR}/../core/common/TribitsCMakePolicies.cmake"  NO_POLICY_SCOPE)
+
 #
 # Set CMAKE_MODULE_PATH
 #
 set( CMAKE_MODULE_PATH
   "${TRIBITS_PROJECT_ROOT}"
   "${TRIBITS_PROJECT_ROOT}/cmake"
   "${${PROJECT_NAME}_TRIBITS_DIR}/core/utils"
+  "${${PROJECT_NAME}_TRIBITS_DIR}/core/common"
+  "${${PROJECT_NAME}_TRIBITS_DIR}/core/test_support"
   "${${PROJECT_NAME}_TRIBITS_DIR}/core/package_arch"
   "${${PROJECT_NAME}_TRIBITS_DIR}/ci_support"
   "${${PROJECT_NAME}_TRIBITS_DIR}/ctest_driver"
   )
 
-include(TribitsConstants)
-tribits_asesrt_minimum_cmake_version()
-include(TribitsCMakePolicies  NO_POLICY_SCOPE)
-
 include(Split)
 include(PrintVar)
 include(MultilineSet)

tribits/doc/guides/generate-guide.sh

@@ -112,7 +112,7 @@ function tribits_extract_rst_cmake_doc {
     echo "Extracting TriBITS documentation from *.cmake files ..."
     echo
     ../../../python_utils/extract_rst_cmake_doc.py \
-      --extract-from=../../../core/package_arch/,../../../ci_support/,../../../core/utils/,../../../ctest_driver/ \
+      --extract-from=../../../ctest_driver/,../../../ci_support/,../../../core/package_arch/,../../../core/test_support/,../../../core/utils/ \
       --rst-file-pairs=../TribitsMacroFunctionDocTemplate.rst:TribitsMacroFunctionDoc.rst.tmp,../UtilsMacroFunctionDocTemplate.rst:UtilsMacroFunctionDoc.rst.tmp,../TribitsSystemMacroFunctionDocTemplate.rst:TribitsSystemMacroFunctionDoc.rst.tmp \
       ${extra_args} \
       --file-name-path-base-dir=../../.. \

tribits/examples/TribitsExampleProject2/packages/package1/CMakeLists.txt

@@ -31,7 +31,7 @@ else()
     include(CTest)
     if (Package1_USE_TRIBITS_TEST_FUNCTIONS AND Package1_TRIBITS_DIR)
       set(Package1_ENABLE_TESTS ON)
-      include("${Package1_TRIBITS_DIR}/core/package_arch/TribitsAddTest.cmake")
+      include("${Package1_TRIBITS_DIR}/core/test_support/TribitsAddTest.cmake")
     endif()
     add_subdirectory(test)
   endif()