From 082ee037e281ee84e6303fdac4b8901ac51e75e5 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Mon, 3 Oct 2022 10:09:04 -0600 Subject: [PATCH] Automatic snapshot commit from tribits at 23dc20b9 Origin repo remote tracking branch: 'github/master' Origin repo remote repo URL: 'github = git@github.com:TriBITSPub/TriBITS.git' Git describe: Vera4.0-RC1-start-1292-g6d3bb5b3 At commit: commit 23dc20b901ab55943b71e51f5e64a244ad186b5a Author: Roscoe A. Bartlett Date: Thu Sep 29 11:46:47 2022 -0600 Summary: Change to use find_package(CUDAToolkit) (trilinos/Trilinos#10954) --- cmake/tribits/CHANGELOG.md | 28 + .../TribitsWriteXmlDependenciesFiles.cmake | 2 +- .../get-tribits-packages-from-files-list.py | 2 +- .../ci_support/get-tribits-packages.py | 2 +- .../package_arch/TribitsAddAdvancedTest.cmake | 2 +- .../package_arch/TribitsAddExecutable.cmake | 30 +- .../core/package_arch/TribitsAddLibrary.cmake | 20 +- .../TribitsAddOptionAndDefine.cmake | 4 +- .../core/package_arch/TribitsAddTest.cmake | 2 +- .../TribitsAdjustPackageEnables.cmake | 199 ++-- .../TribitsCopyFilesToBinaryDir.cmake | 2 +- ...TribitsExternalPackageFindTplHelpers.cmake | 14 +- .../TribitsFindMostRecentFileTimestamp.cmake | 28 +- .../package_arch/TribitsGeneralMacros.cmake | 45 +- .../package_arch/TribitsGlobalMacros.cmake | 45 +- .../package_arch/TribitsListHelpers.cmake | 2 +- .../TribitsPackageDefineDependencies.cmake | 88 +- .../TribitsPackageDependencies.cmake | 12 +- .../package_arch/TribitsPackageMacros.cmake | 10 +- .../TribitsPrintDependencyInfo.cmake | 33 +- .../TribitsPrintEnabledPackagesLists.cmake | 126 +- .../TribitsProcessEnabledTpl.cmake | 2 +- .../TribitsProcessExtraRepositoriesList.cmake | 2 +- .../TribitsProcessPackagesAndDirsLists.cmake | 66 +- .../TribitsProcessTplsLists.cmake | 48 +- .../package_arch/TribitsProjectImpl.cmake | 2 +- ...adAllProjectDepsFilesCreateDepsGraph.cmake | 71 +- .../TribitsReadDepsFilesCreateDepsGraph.cmake | 135 ++- ...itsSystemDataStructuresMacrosFunctions.rst | 764 ++++++------ ...ribitsTplFindIncludeDirsAndLibraries.cmake | 4 +- .../TribitsWriteClientExportFiles.cmake | 10 +- cmake/tribits/core/std_tpls/FindTPLCUDA.cmake | 20 +- .../utils/PrintNonemptyVarWithSpaces.cmake | 24 +- .../TribitsAddDashboardTarget.cmake | 4 +- .../ctest_driver/TribitsCTestDriverCore.cmake | 14 +- .../TribitsCTestDriverCoreHelpers.cmake | 4 +- .../build_ref/TribitsBuildReferenceBody.rst | 150 ++- .../EnableAllPackages.txt | 28 +- ...EnableEpetra_EnableRTOp_DisableTeuchos.txt | 8 +- ...leTeuchos_DisableEnabledFwdDepPackages.txt | 12 +- .../EnableThyraCoreLibs_EnableTests.txt | 20 +- .../EnableThyraEpetra_EnableTests.txt | 22 +- .../EnableThyra_DisableEpetra_EnableTests.txt | 22 +- .../EnableThyra_EnableTests.txt | 42 +- ...EnableThyra_EnableTests_EnableBoost_ST.txt | 48 +- ...nableTests_EnableBoost_ST_RequiredOnly.txt | 46 +- .../ExpectedDependencies.txt | 53 +- .../ReducedMockTrilinosOutput/NoEnables.txt | 20 +- .../guides/TribitsCoreDetailedReference.rst | 8 +- .../guides/TribitsDesignConsiderations.rst | 6 +- .../tribits/doc/guides/TribitsGuidesBody.rst | 1059 +++++++++-------- .../TribitsSystemMacroFunctionDocTemplate.rst | 2 +- .../TribitsMaintainersGuide.rst | 4 +- .../guides/users_guide/TribitsUsersGuide.rst | 2 +- .../b/tests/testlib/ShowLibErrors.cmake | 4 +- 55 files changed, 1837 insertions(+), 1585 deletions(-) diff --git a/cmake/tribits/CHANGELOG.md b/cmake/tribits/CHANGELOG.md index 558c787b124e..144bb070dce2 100644 --- a/cmake/tribits/CHANGELOG.md +++ b/cmake/tribits/CHANGELOG.md @@ -2,6 +2,34 @@ ChangeLog for TriBITS ---------------------------------------- +## 2022-10-02: + +* **Changed:** The TriBITS FindTPLCUDA.cmake module changed + `find_package(CUDA)` to `find_package(CUDAToolkit)` (the former is + deprecated as of CMake 3.17). This avoids imported target namespace + conflicts with downstream CMake projects that call + `find_package(CUDAToolkit)` (see [Trilinos + #10954](https://github.com/trilinos/Trilinos/issues/10954)). + + +## 2022-09-16: + +* **Changed:** Changed nomenclature for packages and TPLs (see updated + "Maintainers Guide" section "TriBITS System Data Structures"): "TPLs" => + "External Packages/TPLs"; "Packages" => "Internal Top-Level Packages"; "SE + Packages" => "Internal Packages". This impacted many internal variables as + well as printed qualities. Behavior should otherwise be identical + w.r.t. input state. The only observable change that users should see is the + text used to describe the different sets of packages and TPLs. (This is + working towards a uniform handling of packages and TPLs (see [TriBITS + #63](https://github.com/TriBITSPub/TriBITS/issues/63)). + +* **Deprecated:** The rarely used input var + `_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_SE_PACKAGES` is deprecated + and the new var name + `_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_PACKAGES` should be used + instead. + ## 2022-08-22: * **Added:** Added support for exporting cache variables for packages in their diff --git a/cmake/tribits/ci_support/TribitsWriteXmlDependenciesFiles.cmake b/cmake/tribits/ci_support/TribitsWriteXmlDependenciesFiles.cmake index 9d9df8e5f2d5..4050ba3e5060 100644 --- a/cmake/tribits/ci_support/TribitsWriteXmlDependenciesFiles.cmake +++ b/cmake/tribits/ci_support/TribitsWriteXmlDependenciesFiles.cmake @@ -103,7 +103,7 @@ function(tribits_dump_deps_xml_file) "\n" ) - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) #message("") #print_var(TRIBITS_PACKAGE) diff --git a/cmake/tribits/ci_support/get-tribits-packages-from-files-list.py b/cmake/tribits/ci_support/get-tribits-packages-from-files-list.py index 9ebbd91fb915..2e799867a277 100755 --- a/cmake/tribits/ci_support/get-tribits-packages-from-files-list.py +++ b/cmake/tribits/ci_support/get-tribits-packages-from-files-list.py @@ -51,7 +51,7 @@ r"""get-tribits-packages-from-files-list.py --deps-xml-file= \ --files-list-file= [--project-dir=] -This script returns a comma-seprated list of all of the project's TriBITS SE +This script returns a comma-seprated list of all of the project's TriBITS packages that must be directly tested for changes in the input list of files. This may also include the special package name 'ALL_PACKAGES' which means that at least one changed file (e.g. /CMakeLists.txt) should result in diff --git a/cmake/tribits/ci_support/get-tribits-packages.py b/cmake/tribits/ci_support/get-tribits-packages.py index 0c3c77fd57aa..6408c1be48cf 100755 --- a/cmake/tribits/ci_support/get-tribits-packages.py +++ b/cmake/tribits/ci_support/get-tribits-packages.py @@ -53,7 +53,7 @@ --only-top-level-packages=[on|off] This script returns a comma-separated list of all of the project's top-level -or packages or the full set of SE packages (i.e. parent and subpackages). +or packages or the full set of packages (i.e. parent and subpackages). """ from optparse import OptionParser diff --git a/cmake/tribits/core/package_arch/TribitsAddAdvancedTest.cmake b/cmake/tribits/core/package_arch/TribitsAddAdvancedTest.cmake index 2f4928c8f0b8..b7627d603882 100644 --- a/cmake/tribits/core/package_arch/TribitsAddAdvancedTest.cmake +++ b/cmake/tribits/core/package_arch/TribitsAddAdvancedTest.cmake @@ -156,7 +156,7 @@ include(PrintVar) # defined in `Test case Pass/Fail (tribits_add_advanced_test())`_) in order # for the overall test to pass. # -# Finally, the test is only added if tests are enabled for the SE package +# Finally, the test is only added if tests are enabled for the package # (i.e. `${PACKAGE_NAME}_ENABLE_TESTS`_ ``= ON``) or the parent package (if # this is a subpackage) (i.e. ``${PARENT_PACKAGE_NAME}_ENABLE_TESTS=ON``) or # if other criteria are met (see some of the arguments in `Overall Arguments diff --git a/cmake/tribits/core/package_arch/TribitsAddExecutable.cmake b/cmake/tribits/core/package_arch/TribitsAddExecutable.cmake index 285afc90825d..f08e7b78bca0 100644 --- a/cmake/tribits/core/package_arch/TribitsAddExecutable.cmake +++ b/cmake/tribits/core/package_arch/TribitsAddExecutable.cmake @@ -170,9 +170,9 @@ include(CMakeParseArguments) # ``TESTONLYLIBS ...`` # # Specifies extra test-only libraries defined in this CMake project that -# will be linked to the executable using ``target_link_libraries()``. Note -# that regular libraries (i.e. not ``TESTONLY``) defined in the current SE -# package or any upstream SE packages can *NOT* be listed! TriBITS +# will be linked to the executable using ``target_link_libraries()``. +# Note that regular libraries (i.e. not ``TESTONLY``) defined in the +# current package or any upstream packages can *NOT* be listed! TriBITS # automatically links non ``TESTONLY`` libraries in this package and # upstream packages to the executable. The only libraries that should be # listed in this argument are either ``TESTONLY`` libraries. @@ -587,10 +587,10 @@ function(tribits_add_executable_assert_testonlylibs) tribits_lib_is_testonly(${prefixedTestOnlyLib} libIsTestOnlyLib) if (NOT libIsTestOnlyLib) message(FATAL_ERROR "ERROR: '${testOnlyLib}' in TESTONLYLIBS not a TESTONLY lib!" - " If this a regular library in this SE package or in an dependent upstream SE" + " If this a regular library in this package or in an dependent upstream" " package then TriBITS will link automatically to it. If you remove this and it" - " does not link, then you need to add a new SE package dependency to" - " this SE package's dependencies file" + " does not link, then you need to add a new package dependency to" + " this package's dependencies file" " ${${PACKAGE_NAME}_SOURCE_DIR}/cmake/Dependencies.cmake") elseif(PARSE_INSTALLABLE) message(FATAL_ERROR "ERROR: TESTONLY lib '${testOnlyLib}' not allowed with" @@ -626,18 +626,18 @@ function(tribits_add_executable_assert_importedlibs) if (NOT foundPrefixedImportedLibInPkgLibs_idx EQUAL -1) message(FATAL_ERROR "ERROR: Lib '${importedLib}' in IMPORTEDLIBS is in" - " this SE package and is *not* an external lib!" + " this package and is *not* an external lib!" " TriBITS takes care of linking against libs the current" - " SE package automatically. Please remove '${importedLib}' from IMPORTEDLIBS!") + " package automatically. Please remove '${importedLib}' from IMPORTEDLIBS!") elseif (TARGET ${prefixedImportedLib}) message(FATAL_ERROR "ERROR: Lib '${importedLib}' being passed through" " IMPORTEDLIBS is *not* an external library but instead is a library" " defined in this CMake project!" " TriBITS takes care of linking against libraries in dependent upstream" - " SE packages. If you want to link to a library in an upstream SE" - " package then add the SE package name for that library to the appropriate" - " list in this SE package's dependencies file" + " packages. If you want to link to a library in an upstream" + " package then add the package name for that library to the appropriate" + " list in this package's dependencies file" " ${${PACKAGE_NAME}_SOURCE_DIR}/cmake/Dependencies.cmake") endif() endforeach() @@ -666,10 +666,10 @@ macro(tribits_add_executable_convert_from_deplibs) " is deprecated! The library '${depLib}' appears to be a" " library defined in this CMake project." " TriBITS takes care of linking against libraries in dependent upstream" - " SE packages. Therefore, please remove '${depLib}' from this list." - " If you want to link to a library from an upstream SE" - " package, then add the SE package name to the appropriate category" - " in this SE package's dependencies file: " + " packages. Therefore, please remove '${depLib}' from this list." + " If you want to link to a library from an upstream" + " package, then add the package name to the appropriate category" + " in this package's dependencies file: " " ${${PACKAGE_NAME}_SOURCE_DIR}/cmake/Dependencies.cmake") # ToDo: Convert the above 'WARNING' to 'SEND_ERROR' else() diff --git a/cmake/tribits/core/package_arch/TribitsAddLibrary.cmake b/cmake/tribits/core/package_arch/TribitsAddLibrary.cmake index bb32b1c3ae8e..4bac9f943c0b 100644 --- a/cmake/tribits/core/package_arch/TribitsAddLibrary.cmake +++ b/cmake/tribits/core/package_arch/TribitsAddLibrary.cmake @@ -138,16 +138,16 @@ include(SetAndIncDirs) # # ``DEPLIBS ...`` # -# List of dependent libraries that are built in the current SE package -# that this library is dependent on. These libraries are passed into +# List of dependent libraries that are built in the current package that +# this library is dependent on. These libraries are passed into # ``target_link_libraries( ...)`` so that CMake knows about -# the dependency structure of the libraries within this SE package. -# **NOTE:** One must **not** list libraries in other upstream `TriBITS SE +# the dependency structure of the libraries within this package. +# **NOTE:** One must **not** list libraries in other upstream `TriBITS # Packages`_ or libraries built externally from this TriBITS CMake project # in ``DEPLIBS``. The TriBITS system automatically handles linking to -# libraries in upstream TriBITS SE packages. External libraries need to -# be listed in the ``IMPORTEDLIBS`` argument instead if they are not -# already specified automatically using a `TriBITS TPL`_. +# libraries in upstream TriBITS packages. External libraries need to be +# listed in the ``IMPORTEDLIBS`` argument instead if they are not already +# specified automatically using a `TriBITS TPL`_. # # ``IMPORTEDLIBS ...`` # @@ -172,8 +172,8 @@ include(SetAndIncDirs) # will be created. If both ``STATIC`` and ``SHARED`` are passed in (which # is obviously a mistake), then a shared library will be created. # WARNING: Once you mark a library with ``STATIC``, then all of the -# downstream libraries in the current SE package and all downstream SE -# packages must also be also be marked with ``STATIC``. That is because, +# downstream libraries in the current package and all downstream packages +# must also be also be marked with ``STATIC``. That is because, # generally, one can not link a link a static lib against a downstream # shared lib since that is not portable (but can be done on some platforms # if, for example, ``-fPIC`` is specified). So be careful to use @@ -202,7 +202,7 @@ include(SetAndIncDirs) # ``add_library()`` where ``cuda_add_library()`` is assumed to be defined # by the standard ``FindCUDA.cmake`` module as processed using the # standard TriBITS ``FindTPLCUDA.cmake`` file (see `Standard TriBITS -# TPLs`_). For this option to work, this SE package must have an enabled +# TPLs`_). For this option to work, this package must have an enabled # direct or indirect dependency on the TriBITS CUDA TPL or a # configure-time error may occur about not knowing about # ``cuda_all_library()``. diff --git a/cmake/tribits/core/package_arch/TribitsAddOptionAndDefine.cmake b/cmake/tribits/core/package_arch/TribitsAddOptionAndDefine.cmake index ea812e51cded..6f6e2945d794 100644 --- a/cmake/tribits/core/package_arch/TribitsAddOptionAndDefine.cmake +++ b/cmake/tribits/core/package_arch/TribitsAddOptionAndDefine.cmake @@ -76,7 +76,7 @@ macro(tribits_add_option_and_define USER_OPTION_NAME MACRO_DEFINE_NAME ) #message("TRIBITS_ADD_OPTION_AND_DEFINE: '${USER_OPTION_NAME}' '${MACRO_DEFINE_NAME}' '${DEFAULT_VALUE}'") set( ${USER_OPTION_NAME} "${DEFAULT_VALUE}" CACHE BOOL "${DOCSTRING}" ) - if(NOT ${MACRO_DEFINE_NAME} STREQUAL "") + if(NOT "${MACRO_DEFINE_NAME}" STREQUAL "") if(${USER_OPTION_NAME}) global_set(${MACRO_DEFINE_NAME} ON) else() @@ -84,7 +84,7 @@ macro(tribits_add_option_and_define USER_OPTION_NAME MACRO_DEFINE_NAME endif() endif() tribits_pkg_export_cache_var(${USER_OPTION_NAME}) - if(NOT ${MACRO_DEFINE_NAME} STREQUAL "") + if(NOT "${MACRO_DEFINE_NAME}" STREQUAL "") tribits_pkg_export_cache_var(${MACRO_DEFINE_NAME}) endif() endmacro() diff --git a/cmake/tribits/core/package_arch/TribitsAddTest.cmake b/cmake/tribits/core/package_arch/TribitsAddTest.cmake index 5853d99a08f6..d9dfa911133a 100644 --- a/cmake/tribits/core/package_arch/TribitsAddTest.cmake +++ b/cmake/tribits/core/package_arch/TribitsAddTest.cmake @@ -77,7 +77,7 @@ include(TribitsAddTestHelpers) # [ADDED_TESTS_NAMES_OUT ] # ) # -# The tests are only added if tests are enabled for the SE package +# The tests are only added if tests are enabled for the package # (i.e. `${PACKAGE_NAME}_ENABLE_TESTS`_) or the parent package (if this is a # subpackage) (i.e. ``${PARENT_PACKAGE_NAME}_ENABLE_TESTS``). (NOTE: A more # efficient way to optionally enable tests is to put them in a ``test/`` diff --git a/cmake/tribits/core/package_arch/TribitsAdjustPackageEnables.cmake b/cmake/tribits/core/package_arch/TribitsAdjustPackageEnables.cmake index 5b26b5549781..d7ecc93b3dbd 100644 --- a/cmake/tribits/core/package_arch/TribitsAdjustPackageEnables.cmake +++ b/cmake/tribits/core/package_arch/TribitsAdjustPackageEnables.cmake @@ -565,7 +565,7 @@ endmacro() # # NOTES: # -# * ${packageName}_LIB_ALL_DEPENDENCIES will be set regardless if +# * ${packageName}_LIB_DEFINED_DEPENDENCIES will be set regardless if # ${packageName} is enabled or not. # # * ${packageName}_LIB_ENABLED_DEPENDENCIES is only set if ${packageName} is @@ -573,7 +573,7 @@ endmacro() # internal and external packages ${depPkg} that are required or are # optional and ${packageName}_ENABLE_${depPkg} is set to ON. # -# * ${packageName}_TEST_ALL_DEPENDENCIES will be set regardless if +# * ${packageName}_TEST_DEFINED_DEPENDENCIES will be set regardless if # ${packageName} is enabled or not. # # * ${packageName}_TEST_ENABLED_DEPENDENCIES is only set if ${packageName} is @@ -583,7 +583,7 @@ endmacro() # # * Sets ${packageName}_ENABLE_${depPkg}=ON for every required dep package # for LIB dependencies (but not TEST dependencies). This allows looping -# over just ${packageName}_LIB_ALL_DEPENDENCIES looking at +# over just ${packageName}_LIB_DEFINED_DEPENDENCIES looking at # ${packageName}_ENABLE_${depPkg} to see if the package is enable or not. # This also includes special logic for required subpackages for parent # packages where only the shell of the parent package is enabled and not @@ -595,11 +595,11 @@ macro(tribits_setup_direct_package_dependencies_lists_and_lib_required_enable_va # LIB dependencies - set(${packageName}_LIB_ALL_DEPENDENCIES "") + set(${packageName}_LIB_DEFINED_DEPENDENCIES "") set(${packageName}_LIB_ENABLED_DEPENDENCIES "") foreach(depPkg ${${packageName}_LIB_REQUIRED_DEP_PACKAGES}) - list(APPEND ${packageName}_LIB_ALL_DEPENDENCIES ${depPkg}) + list(APPEND ${packageName}_LIB_DEFINED_DEPENDENCIES ${depPkg}) if (${PROJECT_NAME}_ENABLE_${packageName} AND ${PROJECT_NAME}_ENABLE_${depPkg}) set(${packageName}_ENABLE_${depPkg} ON) list(APPEND ${packageName}_LIB_ENABLED_DEPENDENCIES ${depPkg}) @@ -609,14 +609,14 @@ macro(tribits_setup_direct_package_dependencies_lists_and_lib_required_enable_va # some cases! foreach(depPkg ${${packageName}_LIB_OPTIONAL_DEP_PACKAGES}) - list(APPEND ${packageName}_LIB_ALL_DEPENDENCIES ${depPkg}) + list(APPEND ${packageName}_LIB_DEFINED_DEPENDENCIES ${depPkg}) if (${PROJECT_NAME}_ENABLE_${packageName} AND ${packageName}_ENABLE_${depPkg}) list(APPEND ${packageName}_LIB_ENABLED_DEPENDENCIES ${depPkg}) endif() endforeach() foreach(depPkg ${${packageName}_LIB_REQUIRED_DEP_TPLS}) - list(APPEND ${packageName}_LIB_ALL_DEPENDENCIES ${depPkg}) + list(APPEND ${packageName}_LIB_DEFINED_DEPENDENCIES ${depPkg}) if (${PROJECT_NAME}_ENABLE_${packageName}) set(${packageName}_ENABLE_${depPkg} ON) list(APPEND ${packageName}_LIB_ENABLED_DEPENDENCIES ${depPkg}) @@ -624,7 +624,7 @@ macro(tribits_setup_direct_package_dependencies_lists_and_lib_required_enable_va endforeach() foreach(depPkg ${${packageName}_LIB_OPTIONAL_DEP_TPLS}) - list(APPEND ${packageName}_LIB_ALL_DEPENDENCIES ${depPkg}) + list(APPEND ${packageName}_LIB_DEFINED_DEPENDENCIES ${depPkg}) if (${PROJECT_NAME}_ENABLE_${packageName} AND ${packageName}_ENABLE_${depPkg}) list(APPEND ${packageName}_LIB_ENABLED_DEPENDENCIES ${depPkg}) endif() @@ -632,7 +632,7 @@ macro(tribits_setup_direct_package_dependencies_lists_and_lib_required_enable_va # TEST dependencies - set(${packageName}_TEST_ALL_DEPENDENCIES "") + set(${packageName}_TEST_DEFINED_DEPENDENCIES "") set(${packageName}_TEST_ENABLED_DEPENDENCIES "") if (${PROJECT_NAME}_ENABLE_${packageName} @@ -645,28 +645,28 @@ macro(tribits_setup_direct_package_dependencies_lists_and_lib_required_enable_va endif() foreach(depPkg ${${packageName}_TEST_REQUIRED_DEP_PACKAGES}) - list(APPEND ${packageName}_TEST_ALL_DEPENDENCIES ${depPkg}) + list(APPEND ${packageName}_TEST_DEFINED_DEPENDENCIES ${depPkg}) if (enablePkgAndTestsOrExamples) list(APPEND ${packageName}_TEST_ENABLED_DEPENDENCIES ${depPkg}) endif() endforeach() foreach(depPkg ${${packageName}_TEST_OPTIONAL_DEP_PACKAGES}) - list(APPEND ${packageName}_TEST_ALL_DEPENDENCIES ${depPkg}) + list(APPEND ${packageName}_TEST_DEFINED_DEPENDENCIES ${depPkg}) if (enablePkgAndTestsOrExamples AND ${packageName}_ENABLE_${depPkg}) list(APPEND ${packageName}_TEST_ENABLED_DEPENDENCIES ${depPkg}) endif() endforeach() foreach(depPkg ${${packageName}_TEST_REQUIRED_DEP_TPLS}) - list(APPEND ${packageName}_TEST_ALL_DEPENDENCIES ${depPkg}) + list(APPEND ${packageName}_TEST_DEFINED_DEPENDENCIES ${depPkg}) if (enablePkgAndTestsOrExamples) list(APPEND ${packageName}_TEST_ENABLED_DEPENDENCIES ${depPkg}) endif() endforeach() foreach(depPkg ${${packageName}_TEST_OPTIONAL_DEP_TPLS}) - list(APPEND ${packageName}_TEST_ALL_DEPENDENCIES ${depPkg}) + list(APPEND ${packageName}_TEST_DEFINED_DEPENDENCIES ${depPkg}) if (enablePkgAndTestsOrExamples AND ${packageName}_ENABLE_${depPkg}) list(APPEND ${packageName}_TEST_ENABLED_DEPENDENCIES ${depPkg}) endif() @@ -686,9 +686,9 @@ function(tribits_print_direct_package_dependencies_lists packageName) set(PRINTED_VAR "") message("") print_nonempty_var_with_spaces(${packageName}_LIB_ENABLED_DEPENDENCIES PRINTED_VAR) - print_var_with_spaces(${packageName}_LIB_ALL_DEPENDENCIES PRINTED_VAR) + print_var_with_spaces(${packageName}_LIB_DEFINED_DEPENDENCIES PRINTED_VAR) print_nonempty_var_with_spaces(${packageName}_TEST_ENABLED_DEPENDENCIES PRINTED_VAR) - print_nonempty_var_with_spaces(${packageName}_TEST_ALL_DEPENDENCIES PRINTED_VAR) + print_nonempty_var_with_spaces(${packageName}_TEST_DEFINED_DEPENDENCIES PRINTED_VAR) endfunction() @@ -1270,15 +1270,14 @@ macro(tribits_enable_optional_tpls PACKAGE_NAME) endmacro() -# Macro that enables upstream (required and optional) SE packages given SE -# package +# Macro that enables upstream (required and optional) packages given package # # Here I have to enable the required packages too or the logic just does no # work as expected. # -macro(tribits_enable_upstream_se_packages PACKAGE_NAME) +macro(tribits_enable_upstream_packages PACKAGE_NAME) - #message("TRIBITS_ENABLE_UPSTREAM_SE_PACKAGES: ${PACKAGE_NAME}") + #message("TRIBITS_ENABLE_UPSTREAM_PACKAGES: ${PACKAGE_NAME}") #message("-- " "${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}=${${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}}") assert_defined(${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}) @@ -1345,7 +1344,7 @@ macro(tribits_adjust_package_enables) message("") message("Setting to empty '' all enabled packages on request ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) if (${PROJECT_NAME}_ENABLE_${TRIBITS_PACKAGE}) set_cache_on_off_empty(${PROJECT_NAME}_ENABLE_${TRIBITS_PACKAGE} "" "Forced to empty '' by ${PROJECT_NAME}_UNENABLE_ENABLED_PACKAGES=ON" FORCE) @@ -1363,14 +1362,14 @@ macro(tribits_adjust_package_enables) # A) Sweep forward through and apply all disables first! # - tribits_get_nondisabled_list( ${PROJECT_NAME}_SE_PACKAGES ${PROJECT_NAME} - ${PROJECT_NAME}_NOTDISABLED_SE_PACKAGES "") + tribits_get_nondisabled_list( ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES ${PROJECT_NAME} + ${PROJECT_NAME}_NOTDISABLED_PACKAGES "") message("") message("Disabling all packages that have a required dependency" " on disabled TPLs and optional package TPL support based on TPL_ENABLE_=OFF ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_NOTDISABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_NOTDISABLED_PACKAGES}) tribits_disable_package_if_tpl_disabled(${TRIBITS_PACKAGE}) endforeach() @@ -1378,25 +1377,25 @@ macro(tribits_adjust_package_enables) message("Disabling subpackages for hard disables of parent packages" " due to ${PROJECT_NAME}_ENABLE_=OFF ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) tribits_disable_parents_subpackages(${TRIBITS_PACKAGE}) endforeach() message("") - message("Disabling forward required SE packages and optional intra-package" - " support that have a dependency on disabled SE packages" + message("Disabling forward required packages and optional intra-package" + " support that have a dependency on disabled packages" " ${PROJECT_NAME}_ENABLE_=OFF ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) tribits_disable_forward_required_dep_packages(${TRIBITS_PACKAGE}) endforeach() - tribits_get_nondisabled_list( ${PROJECT_NAME}_NOTDISABLED_SE_PACKAGES ${PROJECT_NAME} - ${PROJECT_NAME}_NOTDISABLED_SE_PACKAGES "") + tribits_get_nondisabled_list( ${PROJECT_NAME}_NOTDISABLED_PACKAGES ${PROJECT_NAME} + ${PROJECT_NAME}_NOTDISABLED_PACKAGES "") - set(${PROJECT_NAME}_REVERSE_NOTDISABLED_SE_PACKAGES - "${${PROJECT_NAME}_NOTDISABLED_SE_PACKAGES}") - list(REVERSE ${PROJECT_NAME}_REVERSE_NOTDISABLED_SE_PACKAGES) + set(${PROJECT_NAME}_REVERSE_NOTDISABLED_PACKAGES + "${${PROJECT_NAME}_NOTDISABLED_PACKAGES}") + list(REVERSE ${PROJECT_NAME}_REVERSE_NOTDISABLED_PACKAGES) # # B) Apply all forward enables @@ -1406,18 +1405,18 @@ macro(tribits_adjust_package_enables) message("Enabling subpackages for hard enables of parent packages" " due to ${PROJECT_NAME}_ENABLE_=ON ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_NOTDISABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_NOTDISABLED_PACKAGES}) tribits_enable_parents_subpackages(${TRIBITS_PACKAGE}) endforeach() if (${PROJECT_NAME}_ENABLE_ALL_PACKAGES) message("") - message("Enabling all SE packages that are not currently disabled because of" + message("Enabling all packages that are not currently disabled because of" " ${PROJECT_NAME}_ENABLE_ALL_PACKAGES=ON" " (${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE=${${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE})" " ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_NOTDISABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_NOTDISABLED_PACKAGES}) tribits_apply_all_package_enables(${TRIBITS_PACKAGE}) endforeach() endif() @@ -1427,14 +1426,14 @@ macro(tribits_adjust_package_enables) message("Sweep forward enabling all forward library dependent packages because" " ${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES=ON ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_NOTDISABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_NOTDISABLED_PACKAGES}) tribits_enable_forward_lib_package_enables(${TRIBITS_PACKAGE}) endforeach() message("") message("Sweep backward enabling all forward test dependent packages because" " ${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES=ON ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_REVERSE_NOTDISABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_REVERSE_NOTDISABLED_PACKAGES}) tribits_enable_forward_test_package_enables(${TRIBITS_PACKAGE}) endforeach() # NOTE: Above, we want to sweep backward to enable test-dependent packages @@ -1444,17 +1443,17 @@ macro(tribits_adjust_package_enables) set(${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES ON) endif() - tribits_get_enabled_list( ${PROJECT_NAME}_NOTDISABLED_SE_PACKAGES ${PROJECT_NAME} - ${PROJECT_NAME}_ENABLED_SE_PACKAGES "") + tribits_get_enabled_list( ${PROJECT_NAME}_NOTDISABLED_PACKAGES ${PROJECT_NAME} + ${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES "") # - # C) Disable and enable tests for currently enabled SE packages + # C) Disable and enable tests for currently enabled packages # message("") message("Disabling subpackage tests/examples based on parent package tests/examples disables ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) tribits_apply_package_examples_disable(${TRIBITS_PACKAGE} TESTS) tribits_apply_subpackage_tests_or_examples_disables(${TRIBITS_PACKAGE} TESTS) tribits_apply_subpackage_tests_or_examples_disables(${TRIBITS_PACKAGE} EXAMPLES) @@ -1465,7 +1464,7 @@ macro(tribits_adjust_package_enables) message("Enabling all tests and/or examples that have not been" " explicitly disabled because ${PROJECT_NAME}_ENABLE_[TESTS,EXAMPLES]=ON ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}) tribits_apply_test_example_enables(${TRIBITS_PACKAGE}) endforeach() endif() @@ -1476,7 +1475,7 @@ macro(tribits_adjust_package_enables) message("") message("Enabling subpackage tests/examples based on parent package tests/examples enables ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) tribits_apply_subpackage_tests_examples_enables(${TRIBITS_PACKAGE}) endforeach() # NOTE: We want to apply this logic here instead of later after the backward @@ -1486,7 +1485,7 @@ macro(tribits_adjust_package_enables) # sweep of downstream packages. # - # D) Sweep backwards and enable upstream required and optional SE packages + # D) Sweep backwards and enable upstream required and optional packages # if (${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES) @@ -1496,28 +1495,27 @@ macro(tribits_adjust_package_enables) endif() message("") - message("Enabling all required${EXTRA_MSG_STR} upstream SE packages for current set of" + message("Enabling all required${EXTRA_MSG_STR} upstream packages for current set of" " enabled packages" " (${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE=${${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE})" " ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_REVERSE_NOTDISABLED_SE_PACKAGES}) - tribits_enable_upstream_se_packages(${TRIBITS_PACKAGE}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_REVERSE_NOTDISABLED_PACKAGES}) + tribits_enable_upstream_packages(${TRIBITS_PACKAGE}) endforeach() # NOTE: Above, we have to loop through the packages backward to enable all # the packages that feed into these packages. This has to include *all* - # upstream SE package enables including required SE packages, optional SE - # packages (when ${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES), and SE - # packages + # upstream package enables including required packages, optional packages + # (when ${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES), and packages - tribits_get_enabled_list( ${PROJECT_NAME}_NOTDISABLED_SE_PACKAGES ${PROJECT_NAME} - ${PROJECT_NAME}_ENABLED_SE_PACKAGES "") + tribits_get_enabled_list( ${PROJECT_NAME}_NOTDISABLED_PACKAGES ${PROJECT_NAME} + ${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES "") message("") message("Enabling all optional intra-package enables _ENABLE_" " that are not currently disabled if both sets of packages are enabled ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}) tribits_postprocess_optional_package_enables(${TRIBITS_PACKAGE}) endforeach() @@ -1529,7 +1527,7 @@ macro(tribits_adjust_package_enables) message("Enabling all remaining required TPLs for current set of" " enabled packages ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}) tribits_enable_required_tpls(${TRIBITS_PACKAGE}) endforeach() @@ -1538,14 +1536,14 @@ macro(tribits_adjust_package_enables) " _ENABLE_ not currently disabled for" " enabled TPLs ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}) tribits_postprocess_optional_tpl_enables(${TRIBITS_PACKAGE}) endforeach() message("") message("Enabling TPLs based on _ENABLE_=ON if TPL is not explicitly disabled ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}) tribits_enable_optional_tpls(${TRIBITS_PACKAGE}) endforeach() # NOTE: We need to do this after the above optional package TPL support @@ -1553,13 +1551,13 @@ macro(tribits_adjust_package_enables) # in bug 4298. # - # F) Set user cache variables for current set of enabled SE packages + # F) Set user cache variables for current set of enabled packages # message("") message("Set cache entries for optional packages/TPLs and tests/examples for packages actually enabled ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}) tribits_set_up_optional_package_enables_and_cache_vars(${TRIBITS_PACKAGE}) endforeach() @@ -1570,14 +1568,14 @@ macro(tribits_adjust_package_enables) message("") message("Enabling the shell of non-enabled parent packages (mostly for show) that have at least one subpackage enabled ...") message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) tribits_postprocess_package_with_subpackages_enables(${TRIBITS_PACKAGE}) endforeach() # NOTE: The above ensures that loops involving the parent package will # process the parent package but doing this last ensures that no downstream # dependencies will be enabled. - tribits_set_up_enabled_lists_and_se_pkg_idx() + tribits_set_up_enabled_lists_and_pkg_idx() # # H) Set up flat list of direct external and inner package dependencies (even @@ -1585,21 +1583,23 @@ macro(tribits_adjust_package_enables) # packages # - foreach(externalPkgName ${${PROJECT_NAME}_TPLS}) + foreach(externalPkgName ${${PROJECT_NAME}_DEFINED_TPLS}) tribits_extpkg_setup_enabled_dependencies(${externalPkgName}) # ToDo: Assert that all of the listed dependencies in # ${externalPkgName}_LIB_ENABLED_DEPENDENCIES exist and are upstream from # ${externalPkgName} endforeach() - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) tribits_setup_direct_package_dependencies_lists_and_lib_required_enable_vars( ${TRIBITS_PACKAGE}) endforeach() if (${PROJECT_NAME}_DUMP_PACKAGE_DEPENDENCIES) message("\nDumping direct dependencies for each package ...") - foreach(tribitsPkg IN LISTS ${PROJECT_NAME}_DEFINED_TPLS ${PROJECT_NAME}_SE_PACKAGES) + foreach(tribitsPkg IN LISTS ${PROJECT_NAME}_DEFINED_TPLS + ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES + ) tribits_print_direct_package_dependencies_lists(${tribitsPkg}) endforeach() endif() @@ -1646,16 +1646,16 @@ function(tribits_package_set_full_enabled_dep_packages PACKAGE_NAME) foreach(DEP_PACKAGE ${PACKAGE_FULL_DEPS_LIST}) - #print_var(${DEP_PACKAGE}_SE_PKG_IDX) - set(DEP_PACKAGE_VALUE ${${DEP_PACKAGE}_SE_PKG_IDX}) + #print_var(${DEP_PACKAGE}_PKG_IDX) + set(DEP_PACKAGE_VALUE ${${DEP_PACKAGE}_PKG_IDX}) set(SORTED_INDEX 0) set(INSERTED_DEP_PACKAGE FALSE) foreach(SORTED_PACKAGE ${ORDERED_PACKAGE_FULL_DEPS_LIST}) - #print_var(${SORTED_PACKAGE}_SE_PKG_IDX) - set(SORTED_PACKAGE_VALUE ${${SORTED_PACKAGE}_SE_PKG_IDX}) + #print_var(${SORTED_PACKAGE}_PKG_IDX) + set(SORTED_PACKAGE_VALUE ${${SORTED_PACKAGE}_PKG_IDX}) if (${DEP_PACKAGE_VALUE} GREATER ${SORTED_PACKAGE_VALUE}) list(INSERT ORDERED_PACKAGE_FULL_DEPS_LIST ${SORTED_INDEX} ${DEP_PACKAGE}) @@ -1691,31 +1691,46 @@ endfunction() function(tribits_set_up_enabled_only_dependencies) set(GENERATE_EXPORT_DEPENDENCIES ${${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES}) - set(LAST_EXPORT_SE_PACKAGE) + set(lastExportTribitsPackage) + + if ("${${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_PACKAGES}" STREQUAL "" + AND NOT + "${${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_SE_PACKAGES}" STREQUAL "" + ) + message(DEPRECATION + "WARNING! The cache var" + " ${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_SE_PACKAGES" + "='${${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_SE_PACKAGES}'" + " is deprecated! Please instead set" + " ${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_PACKAGES" + "='${${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_SE_PACKAGES}'") + set(${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_PACKAGES + ${${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_SE_PACKAGES} ) + endif() if (GENERATE_EXPORT_DEPENDENCIES - AND ${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_SE_PACKAGES + AND ${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_PACKAGES ) - # Find the last enabled SE package for which an export file is requested. - set(LAST_SE_PKG_IDX -1) - set(LAST_SE_PKG) - foreach(SE_PKG ${${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_SE_PACKAGES}) - #print_var(SE_PKG) - set(SE_PKG_IDX ${${SE_PKG}_SE_PKG_IDX}) - #print_var(SE_PKG_IDX) - if (SE_PKG_IDX) + # Find the last enabled package for which an export file is requested. + set(LAST_PKG_IDX -1) + set(LAST_PKG) + foreach(tribitsPkg ${${PROJECT_NAME}_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_PACKAGES}) + #print_var(tribitsPkg) + set(PKG_IDX ${${tribitsPkg}_PKG_IDX}) + #print_var(PKG_IDX) + if (PKG_IDX) # The listed package is enabled so we will consider it - if (SE_PKG_IDX GREATER ${LAST_SE_PKG_IDX}) - set(LAST_SE_PKG_IDX ${SE_PKG_IDX}) - set(LAST_SE_PKG ${SE_PKG}) - #print_var(LAST_SE_PKG_IDX) - #print_var(LAST_SE_PKG) + if (PKG_IDX GREATER ${LAST_PKG_IDX}) + set(LAST_PKG_IDX ${PKG_IDX}) + set(LAST_PKG ${tribitsPkg}) + #print_var(LAST_PKG_IDX) + #print_var(LAST_PKG) endif() endif() endforeach() - if (LAST_SE_PKG) + if (LAST_PKG) # At least one listed package was enabled - set(LAST_EXPORT_SE_PACKAGE ${LAST_SE_PKG}) + set(lastExportTribitsPackage ${LAST_PKG}) else() # None of the listed packages were enabled so don't bother generating # any export dependencies @@ -1726,23 +1741,23 @@ function(tribits_set_up_enabled_only_dependencies) if (GENERATE_EXPORT_DEPENDENCIES) - if (LAST_EXPORT_SE_PACKAGE) - message("\nSetting up export dependencies up through ${LAST_EXPORT_SE_PACKAGE} ...\n") + if (lastExportTribitsPackage) + message("\nSetting up export dependencies up through ${lastExportTribitsPackage} ...\n") else() - message("\nSetting up export dependencies for all enabled SE packages ...\n") + message("\nSetting up export dependencies for all enabled packages ...\n") endif() - foreach(TRIBITS_SE_PACKAGE ${${PROJECT_NAME}_ENABLED_SE_PACKAGES}) - tribits_package_set_full_enabled_dep_packages(${TRIBITS_SE_PACKAGE}) + foreach(tribitsPackage ${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}) + tribits_package_set_full_enabled_dep_packages(${tribitsPackage}) if (${PROJECT_NAME}_DUMP_PACKAGE_DEPENDENCIES) set(PRINTED_VAR FALSE) - print_nonempty_var_with_spaces(${TRIBITS_SE_PACKAGE}_FULL_ENABLED_DEP_PACKAGES + print_nonempty_var_with_spaces(${tribitsPackage}_FULL_ENABLED_DEP_PACKAGES PRINTED_VAR) if (NOT PRINTED_VAR) - message("-- ${TRIBITS_SE_PACKAGE}: No library dependencies!") + message("-- ${tribitsPackage}: No library dependencies!") endif() endif() - if ("${LAST_EXPORT_SE_PACKAGE}" STREQUAL ${TRIBITS_SE_PACKAGE}) + if ("${lastExportTribitsPackage}" STREQUAL ${tribitsPackage}) break() endif() endforeach() diff --git a/cmake/tribits/core/package_arch/TribitsCopyFilesToBinaryDir.cmake b/cmake/tribits/core/package_arch/TribitsCopyFilesToBinaryDir.cmake index 514092c19af3..f4e1e3bc759c 100644 --- a/cmake/tribits/core/package_arch/TribitsCopyFilesToBinaryDir.cmake +++ b/cmake/tribits/core/package_arch/TribitsCopyFilesToBinaryDir.cmake @@ -67,7 +67,7 @@ include(CMakeParseArguments) # the ``ALL`` target. # # **NOTE:** The target name ```` must be unique from all other -# targets in the same TriBITS SE Package. Otherwise, one will get a configure +# targets in the same TriBITS Package. Otherwise, one will get a configure # failure complaining that a target name has already been defined. Therefore, # be sure to pick long and unique target names! # diff --git a/cmake/tribits/core/package_arch/TribitsExternalPackageFindTplHelpers.cmake b/cmake/tribits/core/package_arch/TribitsExternalPackageFindTplHelpers.cmake index 019911a89a63..1873267bd047 100644 --- a/cmake/tribits/core/package_arch/TribitsExternalPackageFindTplHelpers.cmake +++ b/cmake/tribits/core/package_arch/TribitsExternalPackageFindTplHelpers.cmake @@ -114,8 +114,12 @@ function(tribits_extpkg_create_package_config_file_with_imported_targets # Create Config.cmake file set(configFileStr "") string(APPEND configFileStr - "include(CMakeFindDependencyMacro)\n" - "set(${externalPkg}_DIR \"${${externalPkg}_DIR}\")\n" + "include(CMakeFindDependencyMacro)\n" ) + if (${externalPkg}_DIR) + string(APPEND configFileStr + "set(${externalPkg}_DIR \"${${externalPkg}_DIR}\")\n" ) + endif() + string(APPEND configFileStr "find_dependency(${externalPkg})\n" "add_library(${tplName}::all_libs INTERFACE IMPORTED GLOBAL)\n" ) @@ -130,3 +134,9 @@ function(tribits_extpkg_create_package_config_file_with_imported_targets file(WRITE "${tplConfigFile}" "${configFileStr}") endfunction() +# +# NOTE: Above, ${externalPkg}_DIR is only set when +# find_package(${externalPkg}) finds a package configure file +# ${externalPkg}Config.cmake and **not** when it uses a +# Find${externalPkg}.cmake module. Therefore, there is no reason to set +# ${externalPkg}_DIR in this file if it will not be used. diff --git a/cmake/tribits/core/package_arch/TribitsFindMostRecentFileTimestamp.cmake b/cmake/tribits/core/package_arch/TribitsFindMostRecentFileTimestamp.cmake index c6f70cef0664..a136e8f34135 100644 --- a/cmake/tribits/core/package_arch/TribitsFindMostRecentFileTimestamp.cmake +++ b/cmake/tribits/core/package_arch/TribitsFindMostRecentFileTimestamp.cmake @@ -492,10 +492,10 @@ endfunction() # ``SHOW_OVERALL_MOST_RECENT_FILE`` # # If specified, then only the most recent modified file over all of the -# individual directories for each category (i.e. one for upstream SE -# package source dirs, one for upstream SE package binary dirs, one for -# the package's source dir, and one for the package's own binary dir) is -# printed to STDOUT. +# individual directories for each category (i.e. one for upstream package +# source dirs, one for upstream package binary dirs, one for the package's +# source dir, and one for the package's own binary dir) is printed to +# STDOUT. # # ``CURRENT_PACKAGE_OUT_OF_DATE_OUT `` # @@ -513,7 +513,7 @@ endfunction() # * `tribits_find_most_recent_source_file_timestamp()`_ # * `tribits_find_most_recent_binary_file_timestamp()`_ # -# to determine the most recent modified files in the upstream TriBITS SE +# to determine the most recent modified files in the upstream TriBITS # packages' source and binary directories as well as the most recent source # file for the current package. It then compares these timestamps to the most # recent binary file timestamp in this package's binary directory. If any of @@ -572,11 +572,11 @@ function(tribits_determine_if_current_package_needs_rebuilt) # Only search parent packages to cut down on dirs searched set(ENABLED_UPSTREAM_PACKAGES) set(CURRENT_PARENT_PACKAGE) - foreach(UPSTREAM_SE_PACKAGE ${${PACKAGE_NAME}_FULL_ENABLED_DEP_PACKAGES}) + foreach(upstreamPackage ${${PACKAGE_NAME}_FULL_ENABLED_DEP_PACKAGES}) # Assume we will append - set(APPEND_PACKAGE ${UPSTREAM_SE_PACKAGE}) + set(APPEND_PACKAGE ${upstreamPackage}) # If is a subpackage we only append the parent packages - set(PARENT_PACKAGE ${${UPSTREAM_SE_PACKAGE}_PARENT_PACKAGE}) + set(PARENT_PACKAGE ${${upstreamPackage}_PARENT_PACKAGE}) if (PARENT_PACKAGE) set(APPEND_PACKAGE ${PARENT_PACKAGE}) endif() @@ -587,11 +587,11 @@ function(tribits_determine_if_current_package_needs_rebuilt) #print_var(ENABLED_UPSTREAM_PACKAGES) # - # C) Determine the most recent files on the upstream SE packages + # C) Determine the most recent files on the upstream packages # if (PARSE_SHOW_OVERALL_MOST_RECENT_FILES) - message("\nDetermining most recent source file in upstream SE packages" + message("\nDetermining most recent source file in upstream packages" " from ${PACKAGE_NAME}:") endif() set(UPSTREAM_SOURCE_BASE_DIRS) @@ -608,7 +608,7 @@ function(tribits_determine_if_current_package_needs_rebuilt) #print_var(MOST_RECENT_UPSTREAM_SOURCE_FILEPATH) if (PARSE_SHOW_OVERALL_MOST_RECENT_FILES) - message("\nDetermining most recent binary file in upstream SE packages" + message("\nDetermining most recent binary file in upstream packages" " from ${PACKAGE_NAME}:") endif() set(UPSTREAM_BINARY_BASE_DIRS) @@ -663,13 +663,13 @@ function(tribits_determine_if_current_package_needs_rebuilt) if (MOST_RECENT_THIS_BINARY_FILEPATH) tribits_update_package_out_of_date( - "upstream SE package source" ${MOST_RECENT_UPSTREAM_SOURCE_TIMESTAMP} + "upstream package source" ${MOST_RECENT_UPSTREAM_SOURCE_TIMESTAMP} "${MOST_RECENT_UPSTREAM_SOURCE_FILEPATH}" ${MOST_RECENT_THIS_PACKAGE_BINARY_TIMESTAMP} "${MOST_RECENT_THIS_BINARY_FILEPATH}" CURRENT_PACKAGE_OUT_OF_DATE_OUT ) tribits_update_package_out_of_date( - "upstream SE package binary" ${MOST_RECENT_UPSTREAM_BINARY_TIMESTAMP} + "upstream package binary" ${MOST_RECENT_UPSTREAM_BINARY_TIMESTAMP} "${MOST_RECENT_UPSTREAM_BINARY_FILEPATH}" ${MOST_RECENT_THIS_PACKAGE_BINARY_TIMESTAMP} "${MOST_RECENT_THIS_BINARY_FILEPATH}" CURRENT_PACKAGE_OUT_OF_DATE_OUT ) @@ -683,7 +683,7 @@ function(tribits_determine_if_current_package_needs_rebuilt) if (NOT CURRENT_PACKAGE_OUT_OF_DATE_OUT) message("-- This package's most recent binary file" " ${MOST_RECENT_THIS_BINARY_FILEPATH}" - " is more recent than its upstream SE package source or binary files" + " is more recent than its upstream package source or binary files" " or this package's source files!") endif() diff --git a/cmake/tribits/core/package_arch/TribitsGeneralMacros.cmake b/cmake/tribits/core/package_arch/TribitsGeneralMacros.cmake index cf2a680cb2b5..9fc85539061e 100644 --- a/cmake/tribits/core/package_arch/TribitsGeneralMacros.cmake +++ b/cmake/tribits/core/package_arch/TribitsGeneralMacros.cmake @@ -141,6 +141,8 @@ function(tribits_set_base_repo_dir BASE_DIR REPO_DIR BASE_REPO_DIR_OUT) endif() set(${BASE_REPO_DIR_OUT} "${BASE_DIR}${REPO_DIR_STR}" PARENT_SCOPE) endfunction() + + # Get the list of explicitly enabled entries # # These is the list of entries in ${LISTVAR} for which: @@ -261,32 +263,35 @@ function(tribits_get_nonenabled_list LISTVAR ENABLED_PREFIX endfunction() -# Macro that sets up the basic lists of enabled packages and SE packages. +# Macro that sets up the basic lists of enabled packages and packages. # -macro(tribits_set_up_enabled_lists_and_se_pkg_idx) +macro(tribits_set_up_enabled_lists_and_pkg_idx) # ${PROJECT_NAME}_ENABLED_PACKAGES - tribits_get_enabled_list( ${PROJECT_NAME}_PACKAGES ${PROJECT_NAME} - ${PROJECT_NAME}_ENABLED_PACKAGES ${PROJECT_NAME}_NUM_ENABLED_PACKAGES) - - # ${PROJECT_NAME}_ENABLED_SE_PACKAGES - tribits_get_enabled_list( ${PROJECT_NAME}_SE_PACKAGES ${PROJECT_NAME} - ${PROJECT_NAME}_ENABLED_SE_PACKAGES ${PROJECT_NAME}_NUM_ENABLED_SE_PACKAGES) - - # ${PROJECT_NAME}_REVERSE_ENABLED_SE_PACKAGES - set(${PROJECT_NAME}_REVERSE_ENABLED_SE_PACKAGES - "${${PROJECT_NAME}_ENABLED_SE_PACKAGES}") - list(REVERSE ${PROJECT_NAME}_REVERSE_ENABLED_SE_PACKAGES) - - # ${PACKAGE_NAME}_SE_PKG_IDX - set(SE_PKG_IDX 0) - foreach(TRIBITS_SE_PACKAGE ${${PROJECT_NAME}_ENABLED_SE_PACKAGES}) - set(${TRIBITS_SE_PACKAGE}_SE_PKG_IDX ${SE_PKG_IDX}) - math(EXPR SE_PKG_IDX "${SE_PKG_IDX} + 1") + tribits_get_enabled_list( + ${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES ${PROJECT_NAME} + ${PROJECT_NAME}_ENABLED_INTERNAL_TOPLEVEL_PACKAGES + ${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES) + + # ${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES + tribits_get_enabled_list( ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES ${PROJECT_NAME} + ${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES + ${PROJECT_NAME}_NUM_ENABLED_INTERNAL_PACKAGES) + + # ${PROJECT_NAME}_REVERSE_ENABLED_INTERNAL_PACKAGES + set(${PROJECT_NAME}_REVERSE_ENABLED_INTERNAL_PACKAGES + "${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}") + list(REVERSE ${PROJECT_NAME}_REVERSE_ENABLED_INTERNAL_PACKAGES) + + # ${PACKAGE_NAME}_PKG_IDX + set(PKG_IDX 0) + foreach(tribitsPackage ${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}) + set(${tribitsPackage}_PKG_IDX ${PKG_IDX}) + math(EXPR PKG_IDX "${PKG_IDX} + 1") endforeach() # ${PROJECT_NAME}_ENABLED_TPLS - tribits_get_enabled_list( ${PROJECT_NAME}_TPLS TPL + tribits_get_enabled_list( ${PROJECT_NAME}_DEFINED_TPLS TPL ${PROJECT_NAME}_ENABLED_TPLS ${PROJECT_NAME}_NUM_ENABLED_TPLS) # ${PROJECT_NAME}_REVERSE_ENABLED_TPLS diff --git a/cmake/tribits/core/package_arch/TribitsGlobalMacros.cmake b/cmake/tribits/core/package_arch/TribitsGlobalMacros.cmake index c269cf63b9ae..ac994b29a2e9 100644 --- a/cmake/tribits/core/package_arch/TribitsGlobalMacros.cmake +++ b/cmake/tribits/core/package_arch/TribitsGlobalMacros.cmake @@ -629,7 +629,7 @@ macro(tribits_define_global_options_and_define_extra_repos) advanced_set( ${PROJECT_NAME}_ELEVATE_ST_TO_PT ${${PROJECT_NAME}_ELEVATE_ST_TO_PT_DEFAULT} CACHE BOOL - "Elevate all defined ST SE packages to PT packages." ) + "Elevate all defined ST packages to PT packages." ) if ("${${PROJECT_NAME}_ENABLE_CPACK_PACKAGING_DEFAULT}" STREQUAL "") set(${PROJECT_NAME}_ENABLE_CPACK_PACKAGING_DEFAULT OFF) @@ -1408,22 +1408,22 @@ macro(tribits_handle_project_extra_link_flags_as_a_tpl) # Tack on ${PROJECT_NAME}TribitsLastLib as a dependency to all enabled # external packages/TPLs - foreach(TPL_NAME ${${PROJECT_NAME}_TPLS}) - list(APPEND ${TPL_NAME}_LIB_ALL_DEPENDENCIES ${lastLibTplName}) + foreach(TPL_NAME ${${PROJECT_NAME}_DEFINED_TPLS}) + list(APPEND ${TPL_NAME}_LIB_DEFINED_DEPENDENCIES ${lastLibTplName}) if (TPL_ENABLE_${TPL_NAME}) list(APPEND ${TPL_NAME}_LIB_ENABLED_DEPENDENCIES ${lastLibTplName}) endif() endforeach() # Prepend ${PROJECT_NAME}TribitsLastLib to the list of external packages/TPLs - list(PREPEND ${PROJECT_NAME}_TPLS ${lastLibTplName}) + list(PREPEND ${PROJECT_NAME}_DEFINED_TPLS ${lastLibTplName}) set(TPL_ENABLE_${lastLibTplName} ON) set(${lastLibTplName}_PACKAGE_BUILD_STATUS EXTERNAL) # Tack on ${PROJECT_NAME}TribitsLastLib as a dependency to all enabled # internal packages - foreach(PACKAGE_NAME ${${PROJECT_NAME}_PACKAGES}) - list(APPEND ${PACKAGE_NAME}_LIB_ALL_DEPENDENCIES ${lastLibTplName}) + foreach(PACKAGE_NAME ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) + list(APPEND ${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES ${lastLibTplName}) if (${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}) list(APPEND ${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES ${lastLibTplName}) endif() @@ -1440,14 +1440,14 @@ macro(tribits_process_enabled_tpls) tribits_config_code_start_timer(CONFIGURE_TPLS_TIME_START_SECONDS) - foreach(TPL_NAME ${${PROJECT_NAME}_TPLS}) + foreach(TPL_NAME ${${PROJECT_NAME}_DEFINED_TPLS}) if (TPL_ENABLE_${TPL_NAME}) tribits_process_enabled_tpl(${TPL_NAME}) endif() endforeach() tribits_config_code_stop_timer(CONFIGURE_TPLS_TIME_START_SECONDS - "\nTotal time to configure enabled TPLs") + "\nTotal time to configure enabled external packages/TPLs") endmacro() @@ -1762,7 +1762,7 @@ endmacro() # packages will be listed in the summary if they had one or more tests run. # macro(tribits_set_labels_to_subprojects_mapping) - set(CTEST_LABELS_FOR_SUBPROJECTS ${${PROJECT_NAME}_PACKAGES}) + set(CTEST_LABELS_FOR_SUBPROJECTS ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) endmacro() @@ -2055,7 +2055,7 @@ macro(tribits_configure_enabled_packages) # other even downstream packages (which is pretty messed up really). # - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) # Get all the package sources independent of whether they are enabled or not. # There are some messed up packages that grab parts out of unrelated @@ -2106,14 +2106,14 @@ macro(tribits_configure_enabled_packages) # Tell packages that are also repos they are being processed as a package. set(TRIBITS_PROCESSING_PACKAGE TRUE) - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) tribits_determine_if_process_package(${TRIBITS_PACKAGE} PROCESS_PACKAGE PACKAGE_ENABLE_STR) if (PROCESS_PACKAGE) - message("Processing enabled package: ${TRIBITS_PACKAGE} (${PACKAGE_ENABLE_STR})") + message("Processing enabled top-level package: ${TRIBITS_PACKAGE} (${PACKAGE_ENABLE_STR})") if (NOT ${PROJECT_NAME}_TRACE_DEPENDENCY_HANDLING_ONLY) @@ -2152,7 +2152,7 @@ macro(tribits_configure_enabled_packages) list(APPEND ${PROJECT_NAME}_LIBRARIES ${${TRIBITS_PACKAGE}_LIBRARIES}) tribits_package_config_code_stop_timer(PROCESS_THIS_PACKAGE_TIME_START_SECONDS - "-- Total time to configure package ${TRIBITS_PACKAGE}") + "-- Total time to configure top-level package ${TRIBITS_PACKAGE}") endif() @@ -2243,7 +2243,7 @@ macro(tribits_configure_enabled_packages) # Add empty _libs targets for top-level packages if asked if (${PROJECT_NAME}_DEFINE_MISSING_PACKAGE_LIBS_TARGETS) - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) if (NOT TARGET ${TRIBITS_PACKAGE}_libs) add_custom_target(${TRIBITS_PACKAGE}_libs COMMENT "Dummy target for ${TRIBITS_PACKAGE}_libs that builds nothing!") @@ -2276,20 +2276,19 @@ macro(tribits_setup_packaging_and_distribution) # The above must define the basic project settings for CPACK that are # specific to the project and should not be provided by the user. - # K.2) Removing any packages or SE packages not enabled from the tarball + # K.2) Removing any packages or packages not enabled from the tarball if (${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION) - set(_SE_OR_FULL_PACKAGES ${${PROJECT_NAME}_SE_PACKAGES}) + set(tribitsPackage ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) else() - set(_SE_OR_FULL_PACKAGES ${${PROJECT_NAME}_PACKAGES}) + set(tribitsPackage ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) endif() tribits_get_nonenabled_list( - _SE_OR_FULL_PACKAGES ${PROJECT_NAME} - NON_ENABLED_SE_OR_FULL_PACKAGES NUM_NON_ENABLED_SE_OR_FULL_PACKAGES) - #print_var(NON_ENABLED_SE_OR_FULL_PACKAGES) + tribitsPackage ${PROJECT_NAME} + nonEnabledTribitsPackage "") - foreach(TRIBITS_PACKAGE ${NON_ENABLED_SE_OR_FULL_PACKAGES}) + foreach(TRIBITS_PACKAGE ${nonEnabledTribitsPackage}) # Determine if this is a package to not ignore find_list_element(TRIBITS_CPACK_PACKAGES_TO_NOT_IGNORE @@ -2347,7 +2346,7 @@ macro(tribits_setup_packaging_and_distribution) # K.3) Set up install component dependencies tribits_get_enabled_list( - ${PROJECT_NAME}_PACKAGES ${PROJECT_NAME} + ${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES ${PROJECT_NAME} ENABLED_PACKAGES NUM_ENABLED) #message("ENABLED PACKAGES: ${ENABLED_PACKAGES} ${NUM_ENABLED}") @@ -2416,7 +2415,7 @@ endmacro() function(tribits_add_install_package_by_package_target) set(TRIBITS_ENABLED_PACKAGES_BINARY_DIRS) - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) list(APPEND TRIBITS_ENABLED_PACKAGES_BINARY_DIRS "${${TRIBITS_PACKAGE}_BINARY_DIR}") endforeach() diff --git a/cmake/tribits/core/package_arch/TribitsListHelpers.cmake b/cmake/tribits/core/package_arch/TribitsListHelpers.cmake index ea94d8cb1e91..92184a2520e6 100644 --- a/cmake/tribits/core/package_arch/TribitsListHelpers.cmake +++ b/cmake/tribits/core/package_arch/TribitsListHelpers.cmake @@ -94,7 +94,7 @@ endmacro() # ``${PROJECT_NAME}_HOSTTYPE`` variable for the current platform, then package # ```` test group classification is changed to ``EX``. Changing # the package test group classification to ``EX`` results in the package being -# disabled by default (see `EX SE packages disabled by default`_). However, +# disabled by default (see `EX packages disabled by default`_). However, # an explicit enable can still enable the package. # macro( tribits_disable_package_on_platforms PACKAGE_NAME ) diff --git a/cmake/tribits/core/package_arch/TribitsPackageDefineDependencies.cmake b/cmake/tribits/core/package_arch/TribitsPackageDefineDependencies.cmake index d66d1bbe58e6..c2136eb745b5 100644 --- a/cmake/tribits/core/package_arch/TribitsPackageDefineDependencies.cmake +++ b/cmake/tribits/core/package_arch/TribitsPackageDefineDependencies.cmake @@ -42,7 +42,7 @@ include(TribitsGeneralMacros) # @MACRO: tribits_package_define_dependencies() # -# Define the dependencies for a given `TriBITS SE Package`_ (i.e. a top-level +# Define the dependencies for a given `TriBITS Package`_ (i.e. a top-level # `TriBITS Package`_ or a `TriBITS Subpackage`_) in the package's # `/cmake/Dependencies.cmake`_ file. # @@ -65,74 +65,74 @@ include(TribitsGeneralMacros) # ] # ) # -# Every argument in this macro is optional (that is, an SE package can have no -# upstream dependencies). The arguments that apply to all SE packages are: +# Every argument in this macro is optional (that is, an package can have no +# upstream dependencies). The arguments that apply to all packages are: # # ``LIB_REQUIRED_PACKAGES`` # -# List of required upstream SE packages that must be enabled in order to -# build and use the libraries (or capabilities) in this SE package. +# List of required upstream packages that must be enabled in order to +# build and use the libraries (or capabilities) in this package. # # ``LIB_OPTIONAL_PACKAGES`` # -# List of additional optional upstream SE packages that can be used in -# this SE package if enabled. These upstream SE packages need not be -# enabled in order to enable this SE package but not enabling one or more -# of these optional upstream SE packages will result in diminished -# capabilities of this SE package. +# List of additional optional upstream packages that can be used in +# this package if enabled. These upstream packages need not be +# enabled in order to enable this package but not enabling one or more +# of these optional upstream packages will result in diminished +# capabilities of this package. # # ``TEST_REQUIRED_PACKAGES`` # -# List of additional upstream SE packages that must be enabled in order to -# build and/or run the tests and/or examples in this SE package. If any -# of these upstream SE packages are not enabled, then there will be no -# tests or examples defined or run for this SE package. +# List of additional upstream packages that must be enabled in order to +# build and/or run the tests and/or examples in this package. If any +# of these upstream packages are not enabled, then there will be no +# tests or examples defined or run for this package. # # ``TEST_OPTIONAL_PACKAGES`` # -# List of additional optional upstream SE packages that can be used by the -# tests in this SE package. These upstream SE packages need not be -# enabled in order to run some basic tests or examples for this SE -# package. Typically, extra tests that depend on optional test SE -# packages involve integration testing of some type. +# List of additional optional upstream packages that can be used by the +# tests in this package. These upstream packages need not be enabled in +# order to run some basic tests or examples for this package. Typically, +# extra tests that depend on optional test packages involve integration +# testing of some type. # # ``LIB_REQUIRED_TPLS`` # # List of required upstream TPLs that must be enabled in order to build -# and use the libraries (or capabilities) in this SE package. +# and use the libraries (or capabilities) in this package. # # ``LIB_OPTIONAL_TPLS`` # -# List of additional optional upstream TPLs that can be used in this SE +# List of additional optional upstream TPLs that can be used in this # package if enabled. These upstream TPLs need not be enabled in order to -# use this SE package but not enabling one or more of these optional -# upstream TPLs will result in diminished capabilities of this SE package. +# use this package but not enabling one or more of these optional upstream +# TPLs will result in diminished capabilities of this package. # # ``TEST_REQUIRED_TPLS`` # # List of additional upstream TPLs that must be enabled in order to build -# and/or run the tests and/or examples in this SE package. If any of +# and/or run the tests and/or examples in this package. If any of # these upstream TPLs are not enabled, then there will be no tests or -# examples defined or run for this SE package. +# examples defined or run for this package. # # ``TEST_OPTIONAL_TPLS`` # # List of additional optional upstream TPLs that can be used by the tests -# in this SE package. These upstream TPLs need not be enabled in order to -# run basic tests for this SE package. Typically, extra tests that depend +# in this package. These upstream TPLs need not be enabled in order to +# run basic tests for this package. Typically, extra tests that depend # on optional TPLs involve integration testing or some additional testing # of some type. # -# Only upstream SE packages can be listed (as defined by the order the SE -# packages are listed in `tribits_repository_define_packages()`_ in the +# Only upstream packages can be listed (as defined by the order the packages +# are listed in `tribits_repository_define_packages()`_ in the # `/PackagesList.cmake`_ file). Otherwise an error will occur and -# processing will stop. Misspelled SE package names are caught as well. +# processing will stop. Misspelled package names are caught as well. # -# Only direct SE package dependencies need to be listed. Indirect SE package -# dependencies are automatically handled. For example, if this SE package -# directly depends on SE package ``PKG2`` which depends on SE package ``PKG1`` -# (but this SE package does not directly depend on anything in ``PKG1``) then -# this SE package only needs to list a dependency on ``PKG2``, not ``PKG1``. +# Only direct package dependencies need to be listed. Indirect package +# dependencies are automatically handled. For example, if this package +# directly depends on package ``PKG2`` which depends on package ``PKG1`` +# (but this package does not directly depend on anything in ``PKG1``) then +# this package only needs to list a dependency on ``PKG2``, not ``PKG1``. # The dependency on ``PKG1`` will be taken care of automatically by the # TriBITS dependency management system. # @@ -140,13 +140,13 @@ include(TribitsGeneralMacros) # ones. This is a requirement that will be dropped in a future version of # TriBITS. # -# The SE packages listed in ``LIB_REQUIRED_PACKAGES`` are implicitly also +# The packages listed in ``LIB_REQUIRED_PACKAGES`` are implicitly also # dependencies in ``TEST_REQUIRED_PACKAGES``. Likewise # ``LIB_OPTIONAL_PACKAGES`` are implicitly also dependencies in # ``TEST_OPTIONAL_PACKAGES``. Same goes for TPL dependencies. # # The upstream dependencies within a single list do not need to be listed in -# any order. For example if ``PKG2`` depends on ``PKG1``, and this given SE +# any order. For example if ``PKG2`` depends on ``PKG1``, and this given # package depends on both, then one can list:: # # LIB_REQUIRED_PACKAGES PKG2 PKG1 @@ -157,7 +157,7 @@ include(TribitsGeneralMacros) # # Likewise the order that dependent TPLs are listed is not significant. # -# If some upstream SE packages are allowed to be missing, this can be specified +# If some upstream packages are allowed to be missing, this can be specified # by calling the macro `tribits_allow_missing_external_packages()`_. # # A top-level `TriBITS Package`_ can also be broken down into `TriBITS @@ -171,14 +171,14 @@ include(TribitsGeneralMacros) # columns: # # * **SUBPACKAGE** (Column 0): The name of the subpackage ````. -# The full SE package name is ``${PARENT_PACKAGE_NAME}``. -# The full SE package name is what is used in listing dependencies in -# other SE packages. +# The full package name is ``${PARENT_PACKAGE_NAME}``. +# The full package name is what is used in listing dependencies in +# other packages. # # * **DIRS** (Column 1): The subdirectory ```` relative to the # parent package's base directory. All of the contents of the # subpackage should be under this subdirectory. This is assumed by the -# TriBITS testing support software when mapping modified files to SE +# TriBITS testing support software when mapping modified files to # packages that need to be tested (see `checkin-test.py`_). # # * **CLASSIFICATIONS** (Column 2): The `Test Test Category`_ `PT`_, @@ -212,9 +212,9 @@ include(TribitsGeneralMacros) # * ``REGRESSION_EMAIL_LIST`` # * ``SUBPACKAGES_DIRS_CLASSIFICATIONS_OPTREQS`` # -# which are then read by the TriBITS cmake code to build the SE package +# which are then read by the TriBITS cmake code to build the package # dependency graph. The advantage of using this macro instead of just -# directly setting the variables is that an SE package only needs to list +# directly setting the variables is that an package only needs to list # dependencies that exist. Otherwise, the ``Dependencies.cmake`` file will # need to set all of the above local variables, even those that are empty. # This is an error checking property of the TriBITS system to avoid misspelling diff --git a/cmake/tribits/core/package_arch/TribitsPackageDependencies.cmake b/cmake/tribits/core/package_arch/TribitsPackageDependencies.cmake index bfcf785a4382..416b03d7fddf 100644 --- a/cmake/tribits/core/package_arch/TribitsPackageDependencies.cmake +++ b/cmake/tribits/core/package_arch/TribitsPackageDependencies.cmake @@ -97,13 +97,13 @@ macro(tribits_extpkg_define_dependencies tribits_check_for_unparsed_arguments(PARSE) tribits_assert_parse_arg_one_or_more_values(PARSE DEPENDENCIES) - set(${tplName}_LIB_ALL_DEPENDENCIES ${PARSE_DEPENDENCIES} CACHE STRING + set(${tplName}_LIB_DEFINED_DEPENDENCIES ${PARSE_DEPENDENCIES} CACHE STRING "List of all potential dependencies for external package/TPL '${tplName}'") - mark_as_advanced(${tplName}_LIB_ALL_DEPENDENCIES) + mark_as_advanced(${tplName}_LIB_DEFINED_DEPENDENCIES) endmacro() # -# NOTE: Above, we use a cache var for ${tplName}_LIB_ALL_DEPENDENCIES to allow +# NOTE: Above, we use a cache var for ${tplName}_LIB_DEFINED_DEPENDENCIES to allow # the user to override what dependencies a TPL can depend on. Since this does # not depend on what actual TPLs are enabled, it is okay to set this as a # cache var. As with any genetic change to a CMakeLists.txt file, you always @@ -120,10 +120,10 @@ endmacro() # # Macro that sets up the list of enabled external package/TPL dependencies # -# Takes the list ``_LIB_ALL_DEPENDENCIES`` and sets the +# Takes the list ``_LIB_DEFINED_DEPENDENCIES`` and sets the # default entries of the non-cache var # ``_LIB_ENABLED_DEPENDENCIES``. However, if -# ``${_LIB_ALL_DEPENDENCIES}`` is non-empty when this macro +# ``${_LIB_DEFINED_DEPENDENCIES}`` is non-empty when this macro # is called, then it will not be changed. That allows the user to override # the list of enabled TPL dependencies in the cache. This also sets the # non-cache vars ``_ENABLE_=ON`` for each @@ -137,7 +137,7 @@ macro(tribits_extpkg_setup_enabled_dependencies externalPkgName) set(libEnabledDependencies "") if (TPL_ENABLE_${externalPkgName}) - foreach(upstreamPkgEntry IN LISTS ${externalPkgName}_LIB_ALL_DEPENDENCIES) + foreach(upstreamPkgEntry IN LISTS ${externalPkgName}_LIB_DEFINED_DEPENDENCIES) tribits_extpkg_get_dep_name_and_vis(${upstreamPkgEntry} upstreamPkgName upstreamPkgVis) if (TPL_ENABLE_${upstreamPkgName}) diff --git a/cmake/tribits/core/package_arch/TribitsPackageMacros.cmake b/cmake/tribits/core/package_arch/TribitsPackageMacros.cmake index 62d3791e1b67..8a0475f6746e 100644 --- a/cmake/tribits/core/package_arch/TribitsPackageMacros.cmake +++ b/cmake/tribits/core/package_arch/TribitsPackageMacros.cmake @@ -68,7 +68,7 @@ include(TribitsReportInvalidTribitsUsage) # Macro that defines the package architecture system variables used to link -# different SE packages together +# different packages together # # See README.DEPENDENCIES for information on what these variables mean and how # they are used. @@ -87,7 +87,7 @@ macro(tribits_define_target_vars PARENT_PACKAGE_NAME_IN) endmacro() -# Set up some common variables used in the creation of an SE package +# Set up some common variables used in the creation of an package # macro(tribits_set_common_vars PACKAGE_NAME_IN) @@ -409,7 +409,7 @@ endmacro() # @MACRO: tribits_add_test_directories() # -# Macro called to add a set of test directories for an SE package. +# Macro called to add a set of test directories for an package. # # Usage:: # @@ -441,7 +441,7 @@ endmacro() # -# Macros to add common options to add to an SE package +# Macros to add common options to add to an package # @@ -530,7 +530,7 @@ endmacro() # @MACRO: tribits_add_example_directories() # -# Macro called to conditionally add a set of example directories for an SE +# Macro called to conditionally add a set of example directories for an # package. # # Usage:: diff --git a/cmake/tribits/core/package_arch/TribitsPrintDependencyInfo.cmake b/cmake/tribits/core/package_arch/TribitsPrintDependencyInfo.cmake index 52a39a3c93cb..143610266c51 100644 --- a/cmake/tribits/core/package_arch/TribitsPrintDependencyInfo.cmake +++ b/cmake/tribits/core/package_arch/TribitsPrintDependencyInfo.cmake @@ -38,6 +38,9 @@ # @HEADER +include(PrintNonemptyVarWithSpaces) + + # @FUNCTION: tribits_print_initial_dependency_info() # # Usage:: @@ -71,7 +74,7 @@ endfunction() # Does **not** modify any state! # function(tribits_print_tentatively_enabled_tpls) - foreach(TPL ${${PROJECT_NAME}_TPLS}) + foreach(TPL ${${PROJECT_NAME}_DEFINED_TPLS}) if (TPL_TENTATIVE_ENABLE_${TPL}) message("-- Tentatively enabling TPL '${TPL}'") #print_var(TPL_ENABLE_${TPL}) @@ -89,7 +92,7 @@ endfunction() # Function that dumps (prints to STDOUT) the package dependency info if # ``${PROJECT_NAME}_DUMP_PACKAGE_DEPENDENCIES==TRUE``. # -# Does **not** modify state! +# This function does **not** modify any state! # function(tribits_dump_package_dependencies_info) @@ -101,15 +104,17 @@ function(tribits_dump_package_dependencies_info) "Dump the package forward dependency information." "${${PROJECT_NAME}_VERBOSE_CONFIGURE}" ) + message("\nPackage dependencies information:") + + tribits_print_project_list_var_and_num(DEFINED_TPLS) + tribits_print_project_list_var_and_num(DEFINED_INTERNAL_TOPLEVEL_PACKAGES) + tribits_print_project_list_var_and_num(DEFINED_TOPLEVEL_PACKAGES) + tribits_print_project_list_var_and_num(DEFINED_INTERNAL_PACKAGES) + tribits_print_project_list_var_and_num(DEFINED_PACKAGES) + if (${PROJECT_NAME}_DUMP_PACKAGE_DEPENDENCIES) message("") - message("Printing package dependencies ...") - message("") - print_nonempty_var_with_spaces(${PROJECT_NAME}_PACKAGES DUMMY_OUT) - message("") - print_nonempty_var_with_spaces(${PROJECT_NAME}_SE_PACKAGES DUMMY_OUT) - message("") - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) tribits_print_package_dependencies(${TRIBITS_PACKAGE}) message("") endforeach() @@ -117,4 +122,14 @@ function(tribits_dump_package_dependencies_info) endfunction() + +function(tribits_print_project_list_var_and_num listVarSuffix) + message("") + if (${PROJECT_NAME}_DUMP_PACKAGE_DEPENDENCIES) + print_nonempty_var_with_spaces(${PROJECT_NAME}_${listVarSuffix} wasPrinted) + endif() + print_var(${PROJECT_NAME}_NUM_${listVarSuffix}) +endfunction() + + # LocalWords: TRIBITS diff --git a/cmake/tribits/core/package_arch/TribitsPrintEnabledPackagesLists.cmake b/cmake/tribits/core/package_arch/TribitsPrintEnabledPackagesLists.cmake index c1fd99ba4c83..547c9a9f60e9 100644 --- a/cmake/tribits/core/package_arch/TribitsPrintEnabledPackagesLists.cmake +++ b/cmake/tribits/core/package_arch/TribitsPrintEnabledPackagesLists.cmake @@ -48,18 +48,18 @@ # tribits_print_enables_before_adjust_package_enables() # function(tribits_print_enables_before_adjust_package_enables) - tribits_print_enabled_package_list( + tribits_print_internal_toplevel_package_list_enable_status( + "\nExplicitly enabled top-level packages on input (by user)" ON FALSE) + tribits_print_internal_package_list_enable_status( "\nExplicitly enabled packages on input (by user)" ON FALSE) - tribits_print_enabled_se_package_list( - "\nExplicitly enabled SE packages on input (by user)" ON FALSE) - tribits_print_enabled_package_list( + tribits_print_internal_toplevel_package_list_enable_status( + "\nExplicitly disabled top-level packages on input (by user or by default)" OFF FALSE) + tribits_print_internal_package_list_enable_status( "\nExplicitly disabled packages on input (by user or by default)" OFF FALSE) - tribits_print_enabled_se_package_list( - "\nExplicitly disabled SE packages on input (by user or by default)" OFF FALSE) - tribits_print_enabled_tpl_list( - "\nExplicitly enabled TPLs on input (by user)" ON FALSE) - tribits_print_enabled_tpl_list( - "\nExplicitly disabled TPLs on input (by user or by default)" OFF FALSE) + tribits_print_tpl_list_enable_status( + "\nExplicitly enabled external packages/TPLs on input (by user)" ON FALSE) + tribits_print_tpl_list_enable_status( + "\nExplicitly disabled external packages/TPLs on input (by user or by default)" OFF FALSE) endfunction() @@ -74,88 +74,100 @@ endfunction() # function(tribits_print_enables_after_adjust_package_enables) tribits_print_prefix_string_and_list( - "\nFinal set of enabled packages" "${${PROJECT_NAME}_ENABLED_PACKAGES}") + "\nFinal set of enabled top-level packages" + "${${PROJECT_NAME}_ENABLED_INTERNAL_TOPLEVEL_PACKAGES}") tribits_print_prefix_string_and_list( - "\nFinal set of enabled SE packages" "${${PROJECT_NAME}_ENABLED_SE_PACKAGES}") - tribits_print_enabled_package_list( + "\nFinal set of enabled packages" + "${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}") + tribits_print_internal_toplevel_package_list_enable_status( + "\nFinal set of non-enabled top-level packages" OFF TRUE) + tribits_print_internal_package_list_enable_status( "\nFinal set of non-enabled packages" OFF TRUE) - tribits_print_enabled_se_package_list( - "\nFinal set of non-enabled SE packages" OFF TRUE) - tribits_print_enabled_tpl_list( - "\nFinal set of enabled TPLs" ON FALSE) - tribits_print_enabled_tpl_list( - "\nFinal set of non-enabled TPLs" OFF TRUE) + tribits_print_tpl_list_enable_status( + "\nFinal set of enabled external packages/TPLs" ON FALSE) + tribits_print_tpl_list_enable_status( + "\nFinal set of non-enabled external packages/TPLs" OFF TRUE) endfunction() -# Function that prints the current set of enabled/disabled packages +# Function that prints the current set of enabled internal top-level packages # -function(tribits_print_enabled_package_list DOCSTRING ENABLED_FLAG INCLUDE_EMPTY) - tribits_print_enabled_packages_list_from_var( ${PROJECT_NAME}_PACKAGES +function(tribits_print_internal_toplevel_package_list_enable_status + DOCSTRING ENABLED_FLAG INCLUDE_EMPTY + ) + tribits_print_packages_list_enable_status_from_var( + ${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES "${DOCSTRING}" ${ENABLED_FLAG} ${INCLUDE_EMPTY} ) endfunction() -# Prints the current set of enabled/disabled SE packages +# Prints the current set of enabled/disabled internal packages # -function(tribits_print_enabled_se_package_list DOCSTRING ENABLED_FLAG INCLUDE_EMPTY) - if (ENABLED_FLAG AND NOT INCLUDE_EMPTY) - tribits_get_enabled_list( ${PROJECT_NAME}_SE_PACKAGES ${PROJECT_NAME} - ENABLED_SE_PACKAGES NUM_ENABLED) - elseif (ENABLED_FLAG AND INCLUDE_EMPTY) - tribits_get_nondisabled_list( ${PROJECT_NAME}_SE_PACKAGES ${PROJECT_NAME} - ENABLED_SE_PACKAGES NUM_ENABLED) - elseif (NOT ENABLED_FLAG AND NOT INCLUDE_EMPTY) - tribits_get_disabled_list( ${PROJECT_NAME}_SE_PACKAGES ${PROJECT_NAME} - ENABLED_SE_PACKAGES NUM_ENABLED) - else() # NOT ENABLED_FLAG AND INCLUDE_EMPTY - tribits_get_nonenabled_list( ${PROJECT_NAME}_SE_PACKAGES ${PROJECT_NAME} - ENABLED_SE_PACKAGES NUM_ENABLED) +function(tribits_print_internal_package_list_enable_status + DOCSTRING ENABLED_FLAG INCLUDE_EMPTY + ) + if (ENABLED_FLAG AND NOT INCLUDE_EMPTY) + tribits_get_enabled_list( + ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES ${PROJECT_NAME} + internalPackagesEnableStatusList "") + elseif (ENABLED_FLAG AND INCLUDE_EMPTY) + tribits_get_nondisabled_list( + ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES ${PROJECT_NAME} + internalPackagesEnableStatusList "") + elseif (NOT ENABLED_FLAG AND NOT INCLUDE_EMPTY) + tribits_get_disabled_list( + ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES ${PROJECT_NAME} + internalPackagesEnableStatusList "") + else() # NOT ENABLED_FLAG AND INCLUDE_EMPTY + tribits_get_nonenabled_list( + ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES ${PROJECT_NAME} + internalPackagesEnableStatusList "") endif() - tribits_print_prefix_string_and_list("${DOCSTRING}" "${ENABLED_SE_PACKAGES}") + tribits_print_prefix_string_and_list("${DOCSTRING}" + "${internalPackagesEnableStatusList}") endfunction() # Print the current set of enabled/disabled TPLs # -function(tribits_print_enabled_tpl_list DOCSTRING ENABLED_FLAG INCLUDE_EMPTY) +function(tribits_print_tpl_list_enable_status DOCSTRING ENABLED_FLAG INCLUDE_EMPTY) if (ENABLED_FLAG AND NOT INCLUDE_EMPTY) - tribits_get_enabled_list( ${PROJECT_NAME}_TPLS TPL - ENABLED_TPLS NUM_ENABLED) + tribits_get_enabled_list( ${PROJECT_NAME}_DEFINED_TPLS TPL + tplsEnableStatusList "") elseif (ENABLED_FLAG AND INCLUDE_EMPTY) - tribits_get_nondisabled_list( ${PROJECT_NAME}_TPLS TPL - ENABLED_TPLS NUM_ENABLED) + tribits_get_nondisabled_list( ${PROJECT_NAME}_DEFINED_TPLS TPL + tplsEnableStatusList "") elseif (NOT ENABLED_FLAG AND NOT INCLUDE_EMPTY) - tribits_get_disabled_list( ${PROJECT_NAME}_TPLS TPL - ENABLED_TPLS NUM_ENABLED) + tribits_get_disabled_list( ${PROJECT_NAME}_DEFINED_TPLS TPL + tplsEnableStatusList "") else() # NOT ENABLED_FLAG AND INCLUDE_EMPTY - tribits_get_nonenabled_list( ${PROJECT_NAME}_TPLS TPL - ENABLED_TPLS NUM_ENABLED) + tribits_get_nonenabled_list( ${PROJECT_NAME}_DEFINED_TPLS TPL + tplsEnableStatusList "") endif() - tribits_print_prefix_string_and_list("${DOCSTRING}" "${ENABLED_TPLS}") + tribits_print_prefix_string_and_list("${DOCSTRING}" "${tplsEnableStatusList}") endfunction() # Print the current set of enabled/disabled packages given input list of # packages # -function(tribits_print_enabled_packages_list_from_var PACKAGES_LIST_VAR +function(tribits_print_packages_list_enable_status_from_var PACKAGES_LIST_VAR DOCSTRING ENABLED_FLAG INCLUDE_EMPTY ) - if (ENABLED_FLAG AND NOT INCLUDE_EMPTY) + if (ENABLED_FLAG AND NOT INCLUDE_EMPTY) tribits_get_enabled_list(${PACKAGES_LIST_VAR} ${PROJECT_NAME} - ENABLED_PACKAGES NUM_ENABLED) - elseif (ENABLED_FLAG AND INCLUDE_EMPTY) + enableStatusList "") + elseif (ENABLED_FLAG AND INCLUDE_EMPTY) tribits_get_nondisabled_list(${PACKAGES_LIST_VAR} ${PROJECT_NAME} - ENABLED_PACKAGES NUM_ENABLED) - elseif (NOT ENABLED_FLAG AND NOT INCLUDE_EMPTY) + enableStatusList "") + elseif (NOT ENABLED_FLAG AND NOT INCLUDE_EMPTY) tribits_get_disabled_list(${PACKAGES_LIST_VAR} ${PROJECT_NAME} - ENABLED_PACKAGES NUM_ENABLED) - else() # NOT ENABLED_FLAG AND INCLUDE_EMPTY + enableStatusList "") + else() # NOT ENABLED_FLAG AND INCLUDE_EMPTY tribits_get_nonenabled_list(${PACKAGES_LIST_VAR} ${PROJECT_NAME} - ENABLED_PACKAGES NUM_ENABLED) + enableStatusList "") endif() - tribits_print_prefix_string_and_list("${DOCSTRING}" "${ENABLED_PACKAGES}") + tribits_print_prefix_string_and_list("${DOCSTRING}" "${enableStatusList}") endfunction() diff --git a/cmake/tribits/core/package_arch/TribitsProcessEnabledTpl.cmake b/cmake/tribits/core/package_arch/TribitsProcessEnabledTpl.cmake index c8cbdb4a90a6..dcdde4ce6349 100644 --- a/cmake/tribits/core/package_arch/TribitsProcessEnabledTpl.cmake +++ b/cmake/tribits/core/package_arch/TribitsProcessEnabledTpl.cmake @@ -56,7 +56,7 @@ include(TribitsStandardizePaths) function(tribits_process_enabled_tpl TPL_NAME) # Setup the processing string - set(PROCESSING_MSG_STRING "Processing enabled TPL: ${TPL_NAME} (") + set(PROCESSING_MSG_STRING "Processing enabled external package/TPL: ${TPL_NAME} (") if (TPL_${TPL_NAME}_ENABLING_PKG) string(APPEND PROCESSING_MSG_STRING "enabled by ${TPL_${TPL_NAME}_ENABLING_PKG}," ) diff --git a/cmake/tribits/core/package_arch/TribitsProcessExtraRepositoriesList.cmake b/cmake/tribits/core/package_arch/TribitsProcessExtraRepositoriesList.cmake index d9bdf527f03b..38484fd46d12 100644 --- a/cmake/tribits/core/package_arch/TribitsProcessExtraRepositoriesList.cmake +++ b/cmake/tribits/core/package_arch/TribitsProcessExtraRepositoriesList.cmake @@ -136,7 +136,7 @@ include(TribitsSortListAccordingToMasterList) # # NOTE: These repositories must be listed in the order of package # dependencies. That is, all of the packages listed in repository ``i`` must -# have upstream TPL and SE package dependencies listed before this package in +# have upstream TPL and package dependencies listed before this package in # this repository or in upstream repositories ``i-1``, ``i-2``, etc. # # NOTE: This module just sets the local variable:: diff --git a/cmake/tribits/core/package_arch/TribitsProcessPackagesAndDirsLists.cmake b/cmake/tribits/core/package_arch/TribitsProcessPackagesAndDirsLists.cmake index 92e5175e1b37..35a5d46b4864 100644 --- a/cmake/tribits/core/package_arch/TribitsProcessPackagesAndDirsLists.cmake +++ b/cmake/tribits/core/package_arch/TribitsProcessPackagesAndDirsLists.cmake @@ -91,7 +91,7 @@ include(TribitsListHelpers) # packages are modified and need to be retested (along with downstream # packages). For details, see `checkin-test.py`_. # -# 2. **CLASSIFICATION** (````): Gives the `SE Package Test +# 2. **CLASSIFICATION** (````): Gives the `Package Test # Group`_ `PT`_, `ST`_, or `EX`_ and the maturity level ``EP``, ``RS``, # ``PG``, ``PM``, ``GRS``, ``GPG``, ``GPM``, ``UM``. These are separated # by a coma with no space in between such as ``"RS,PT"`` for a "Research @@ -149,18 +149,18 @@ endmacro() # # tribits_allow_missing_external_packages( ...) # -# If the missing upstream SE package ```` is optional, then the effect +# If the missing upstream package ```` is optional, then the effect # will be to simply ignore the missing package (i.e. it will never be added to # package's list and not added to dependency data-structures) and remove it -# from the dependency lists for downstream SE packages that have an optional -# dependency on the missing upstream SE package ````. However, all -# downstream SE packages that have a required dependency on the missing -# upstream SE package ```` will be hard disabled, +# from the dependency lists for downstream packages that have an optional +# dependency on the missing upstream package ````. However, all +# downstream packages that have a required dependency on the missing +# upstream package ```` will be hard disabled, # i.e. ``${PROJECT_NAME}_ENABLE_{CURRENT_PACKAGE}=OFF`` and a note on the # disable will be printed. # # **WARNING**: This macro just sets the cache variable -# ``_ALLOW_MISSING_EXTERNAL_PACKAGE=TRUE`` for each SE package +# ``_ALLOW_MISSING_EXTERNAL_PACKAGE=TRUE`` for each package # ````. Therefore, using this function effectively turns off error # checking for misspelled package names so it is important to only use it when # it absolutely is needed (use cases mentioned below). Also note that missing @@ -373,12 +373,12 @@ endfunction() # ${REPOSITORY_NAME}_PACKAGES_AND_DIRS_AND_CLASSIFICATIONS # # from a `/PackagesList.cmake`_ file that just got read in and -# creates/updates the variables:: +# creates/updates the top-level non-cache variables: # -# ${PROJECT_NAME}_PACKAGES -# ${PROJECT_NAME}_NUM_PACKAGES -# ${PROJECT_NAME}_LAST_PACKAGE_IDX -# ${PROJECT_NAME}_REVERSE_PACKAGES +# * `${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ +# * `${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ +# * ``${PROJECT_NAME}_LAST_DEFINED_INTERNAL_TOPLEVEL_PACKAGE_IDX`` +# * ``${PROJECT_NAME}_REVERSE_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`` # # For each of the listed top-level (parent) packages ${PACKAGE_NAME}, it also # sets up constant variables defined in `TriBITS Package Top-Level Local @@ -416,22 +416,25 @@ macro(tribits_process_packages_and_dirs_lists REPOSITORY_NAME REPOSITORY_DIR) endif() list(LENGTH ${REPOSITORY_NAME}_PACKAGES_AND_DIRS_AND_CLASSIFICATIONS ${REPOSITORY_NAME}_NUM_PACKAGES_AND_FIELDS ) - math(EXPR ${REPOSITORY_NAME}_NUM_PACKAGES + math(EXPR ${REPOSITORY_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES "${${REPOSITORY_NAME}_NUM_PACKAGES_AND_FIELDS}/${PLH_NUM_FIELDS_PER_PACKAGE}") if (TRIBITS_PROCESS_PACKAGES_AND_DIRS_LISTS_VERBOSE) - print_var(${REPOSITORY_NAME}_NUM_PACKAGES) + print_var(${REPOSITORY_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES) endif() - math(EXPR ${REPOSITORY_NAME}_LAST_PACKAGE_IDX "${${REPOSITORY_NAME}_NUM_PACKAGES}-1") + math(EXPR ${REPOSITORY_NAME}_LAST_DEFINED_INTERNAL_TOPLEVEL_PACKAGE_IDX + "${${REPOSITORY_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}-1") # Process each of the packages defined - if (${REPOSITORY_NAME}_NUM_PACKAGES GREATER 0) + if (${REPOSITORY_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES GREATER 0) - foreach(PACKAGE_IDX RANGE ${${REPOSITORY_NAME}_LAST_PACKAGE_IDX}) + foreach(PACKAGE_IDX RANGE + ${${REPOSITORY_NAME}_LAST_DEFINED_INTERNAL_TOPLEVEL_PACKAGE_IDX} + ) if (TRIBITS_PROCESS_PACKAGES_AND_DIRS_LISTS_VERBOSE) message("") - print_var(${PROJECT_NAME}_PACKAGES) + print_var(${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES) endif() math(EXPR PACKAGE_NAME_IDX "${PACKAGE_IDX}*${PLH_NUM_FIELDS_PER_PACKAGE}+0") @@ -554,7 +557,7 @@ macro(tribits_process_packages_and_dirs_lists REPOSITORY_NAME REPOSITORY_DIR) endif() if (PACKAGE_EXISTS OR ${PROJECT_NAME}_IGNORE_PACKAGE_EXISTS_CHECK) - list(APPEND ${PROJECT_NAME}_PACKAGES ${TRIBITS_PACKAGE}) + list(APPEND ${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES ${TRIBITS_PACKAGE}) tribits_insert_standard_package_options(${TRIBITS_PACKAGE} ${PACKAGE_TESTGROUP}) set(${TRIBITS_PACKAGE}_PACKAGE_BUILD_STATUS INTERNAL) @@ -584,37 +587,38 @@ macro(tribits_process_packages_and_dirs_lists REPOSITORY_NAME REPOSITORY_DIR) endif() if (TRIBITS_PROCESS_PACKAGES_AND_DIRS_LISTS_VERBOSE) - print_var(${PROJECT_NAME}_PACKAGES) + print_var(${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES) endif() endforeach() # Get the actual number of packages that actually exist - list(LENGTH ${PROJECT_NAME}_PACKAGES ${PROJECT_NAME}_NUM_PACKAGES ) - math(EXPR ${PROJECT_NAME}_LAST_PACKAGE_IDX "${${PROJECT_NAME}_NUM_PACKAGES}-1") + list(LENGTH ${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES + ${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES ) + math(EXPR ${PROJECT_NAME}_LAST_DEFINED_INTERNAL_TOPLEVEL_PACKAGE_IDX + "${${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}-1") # Create a reverse list for later use - set(${PROJECT_NAME}_REVERSE_PACKAGES ${${PROJECT_NAME}_PACKAGES}) - list(REVERSE ${PROJECT_NAME}_REVERSE_PACKAGES) + set(${PROJECT_NAME}_REVERSE_DEFINED_INTERNAL_TOPLEVEL_PACKAGES + ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) + list(REVERSE ${PROJECT_NAME}_REVERSE_DEFINED_INTERNAL_TOPLEVEL_PACKAGES) else() - set(${REPOSITORY_NAME}_NUM_PACKAGES 0) - - endif() + set(${REPOSITORY_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES 0) - if (${PROJECT_NAME}_VERBOSE_CONFIGURE) - print_var(${REPOSITORY_NAME}_NUM_PACKAGES) endif() - print_var(${PROJECT_NAME}_NUM_PACKAGES) + message("-- After reading above PackagesList.cmake file: " + "${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES" + "='${${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}'") # Print the final set of packages in debug mode if (${PROJECT_NAME}_VERBOSE_CONFIGURE) - print_var(${PROJECT_NAME}_PACKAGES) + print_var(${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES) endif() endmacro() diff --git a/cmake/tribits/core/package_arch/TribitsProcessTplsLists.cmake b/cmake/tribits/core/package_arch/TribitsProcessTplsLists.cmake index b8d29f599fc8..0a9c2ea486bd 100644 --- a/cmake/tribits/core/package_arch/TribitsProcessTplsLists.cmake +++ b/cmake/tribits/core/package_arch/TribitsProcessTplsLists.cmake @@ -47,10 +47,10 @@ include(Split) # @MACRO: tribits_repository_define_tpls() # -# Define the list of `TriBITS TPLs`_ for a given `TriBITS Repository`_ which -# includes the TPL name, find module, and classification . This macro is -# typically called from inside of the repository's `/TPLsList.cmake`_ -# file. +# Define the list of `TriBITS TPLs`_ (external packages) for a given `TriBITS +# Repository`_ which includes the TPL name, find module, and classification . +# This macro is typically called from inside of the repository's +# `/TPLsList.cmake`_ file. # # Usage:: # @@ -82,7 +82,7 @@ include(Split) # ``FindTPL.cmake``. (See `Creating the FindTPL.cmake # file`_.) # -# 2. **CLASSIFICATION** (````): Gives the `SE Package Test +# 2. **CLASSIFICATION** (````): Gives the `Package Test # Group`_ `PT`_, `ST`_, or `EX`_ and the maturity level ``EP``, ``RS``, # ``PG``, ``PM``, ``GRS``, ``GPG``, ``GPM``, ``UM``. These are separated # by a coma with no space in between such as ``"RS,PT"`` for a "Research @@ -127,18 +127,17 @@ endmacro() # # ${REPOSITORY_NAME}_TPLS_FINDMODS_CLASSIFICATIONS # -# and updates the project-level variables:: +# This updates the project-level variables: # -# ${PROJECT_NAME}_TPLS -# ${PROJECT_NAME}_NUM_TPLS -# ${PROJECT_NAME}_REVERSE_TPLS +# * `${PROJECT_NAME}_DEFINED_TPLS`_ +# * `${PROJECT_NAME}_NUM_DEFINED_TPLS`_ # -# For each TPL, it also sets the variables:: +# For each TPL, it also sets the variables: # -# ${TPL_NAME}_FINDMOD -# ${TPL_NAME}_TESTGROUP -# ${TPL_NAME}_DEPENDENCIES_FILE -# ${TPL_NAME}_TPLS_LIST_FILE +# * `${TPL_NAME}_FINDMOD`_ +# * `${TPL_NAME}_TESTGROUP`_ +# * `${TPL_NAME}_DEPENDENCIES_FILE`_ +# * `${TPL_NAME}_TPLS_LIST_FILE`_ # # See `Function call tree for constructing package dependency graph`_ # @@ -214,7 +213,7 @@ macro(tribits_process_tpls_lists REPOSITORY_NAME REPOSITORY_DIR) " in the same location and not adding it again!") endif() else() - list(APPEND ${PROJECT_NAME}_TPLS ${TPL_NAME}) + list(APPEND ${PROJECT_NAME}_DEFINED_TPLS ${TPL_NAME}) endif() # Set ${TPL_NAME}_PACKAGE_BUILD_STATUS @@ -303,21 +302,12 @@ macro(tribits_process_tpls_lists REPOSITORY_NAME REPOSITORY_DIR) endif() if (${PROJECT_NAME}_VERBOSE_CONFIGURE) - print_var(${PROJECT_NAME}_TPLS) + print_var(${PROJECT_NAME}_DEFINED_TPLS) endif() - # Get the final length - - list(LENGTH ${PROJECT_NAME}_TPLS ${PROJECT_NAME}_NUM_TPLS) - print_var(${PROJECT_NAME}_NUM_TPLS) - - # Create a reverse list for later use - - if (${PROJECT_NAME}_TPLS) - set(${PROJECT_NAME}_REVERSE_TPLS ${${PROJECT_NAME}_TPLS}) - list(REVERSE ${PROJECT_NAME}_REVERSE_TPLS) - else() - set(${PROJECT_NAME}_REVERSE_TPLS) - endif() + # Get and print length + list(LENGTH ${PROJECT_NAME}_DEFINED_TPLS ${PROJECT_NAME}_NUM_DEFINED_TPLS) + message("-- After reading above TPLsList.cmake file: " + "${PROJECT_NAME}_NUM_DEFINED_TPLS='${${PROJECT_NAME}_NUM_DEFINED_TPLS}'") endmacro() diff --git a/cmake/tribits/core/package_arch/TribitsProjectImpl.cmake b/cmake/tribits/core/package_arch/TribitsProjectImpl.cmake index dfb8a60b41d3..fc9e30109206 100644 --- a/cmake/tribits/core/package_arch/TribitsProjectImpl.cmake +++ b/cmake/tribits/core/package_arch/TribitsProjectImpl.cmake @@ -191,7 +191,7 @@ macro(tribits_project_impl) # message("") - message("Getting information for all enabled TPLs ...") + message("Getting information for all enabled external packages/TPLs ...") message("") tribits_process_enabled_tpls() diff --git a/cmake/tribits/core/package_arch/TribitsReadAllProjectDepsFilesCreateDepsGraph.cmake b/cmake/tribits/core/package_arch/TribitsReadAllProjectDepsFilesCreateDepsGraph.cmake index 581d09fee74f..261d815f3e05 100644 --- a/cmake/tribits/core/package_arch/TribitsReadAllProjectDepsFilesCreateDepsGraph.cmake +++ b/cmake/tribits/core/package_arch/TribitsReadAllProjectDepsFilesCreateDepsGraph.cmake @@ -63,7 +63,8 @@ include(TimingUtils) # and more specifically the sections: # # * `Lists of external and internal packages`_ -# * `List variables defining the package dependencies graph`_ +# * `Variables defining the package dependencies graph`_ +# (`Legacy list variables defining the package dependencies graph`_) # * `TriBITS Package Top-Level Local Variables`_ # * `TriBITS Subpackage Top-Level Local Variables`_ # * `TriBITS Package Cache Variables`_ @@ -78,6 +79,13 @@ macro(tribits_read_all_project_deps_files_create_deps_graph) tribits_read_deps_files_create_deps_graph() + # ${PROJECT_NAME}_DEFINED_PACKAGES + set(${PROJECT_NAME}_DEFINED_PACKAGES + ${${PROJECT_NAME}_DEFINED_TPLS} + ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) + list(LENGTH ${PROJECT_NAME}_DEFINED_PACKAGES + ${PROJECT_NAME}_NUM_DEFINED_PACKAGES) + tribits_config_code_stop_timer(SET_UP_DEPENDENCIES_TIME_START_SECONDS "\nTotal time to read in all dependencies files and build dependencies graph") @@ -95,20 +103,17 @@ endmacro() # to get the list of defined external packages (TPLs) and internal top-level # (TriBITS) packages. # -# On output, this produces the list variables:: -# -# ${PROJECT_NAME}_DEFINED_TPLS -# ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES -# ${PROJECT_NAME}_ALL_DEFINED_TOPLEVEL_PACKAGES +# On output, this produces the local variables: # -# ${PROJECT_NAME}_NUM_DEFINED_TPLS -# ${PROJECT_NAME}_NUM_DEFINED_INTERNAL_PACKAGES -# ${PROJECT_NAME}_NUM_ALL_DEFINED_TOPLEVEL_PACKAGES +# * `${PROJECT_NAME}_DEFINED_TPLS`_ +# * `${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ +# * `${PROJECT_NAME}_DEFINED_TOPLEVEL_PACKAGES`_ # -# ${PROJECT_NAME}_PACKAGES (old) -# ${PROJECT_NAME}_TPLS (old) +# and the length vars for these: # -# and related variables. +# * `${PROJECT_NAME}_NUM_DEFINED_TPLS`_ +# * `${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ +# * `${PROJECT_NAME}_NUM_DEFINED_TOPLEVEL_PACKAGES`_ # # This includes the files: # @@ -128,19 +133,21 @@ macro(tribits_read_defined_external_and_internal_toplevel_packages_lists) tribits_set_all_extra_repositories() - # Set to empty - set(${PROJECT_NAME}_PACKAGES) - set(${PROJECT_NAME}_TPLS) + # Set package list vars to empty + set(${PROJECT_NAME}_DEFINED_TPLS "") + set(${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES "") # - # A) Read list of packages and TPLs from 'PRE' extra repos + # A) Read list of external packages/TPLs and top-level internal packages + # from 'PRE' extra repos # set(READ_PRE_OR_POST_EXRAREPOS PRE) tribits_read_extra_repositories_lists() # - # B) Read list of packages and TPLs from native repos + # B) Read list of external packages/TPLs and top-level internal packages + # from the native repos # foreach(NATIVE_REPO ${${PROJECT_NAME}_NATIVE_REPOSITORIES}) @@ -217,24 +224,34 @@ macro(tribits_read_defined_external_and_internal_toplevel_packages_lists) endforeach() # - # C) Read list of packages and TPLs from 'POST' extra repos + # C) Read list of external packages/TPLs and top-level internal packages + # from 'POST' extra repos # set(READ_PRE_OR_POST_EXRAREPOS POST) tribits_read_extra_repositories_lists() # - # D) Set names of new vars (#63) + # D) Compute lengths and other combined quantities # - set(${PROJECT_NAME}_DEFINED_TPLS ${${PROJECT_NAME}_TPLS}) + + # ${PROJECT_NAME}_NUM_DEFINED_TPLS list(LENGTH ${PROJECT_NAME}_DEFINED_TPLS ${PROJECT_NAME}_NUM_DEFINED_TPLS) - set(${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES ${${PROJECT_NAME}_PACKAGES}) - list(LENGTH ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES - ${PROJECT_NAME}_NUM_DEFINED_INTERNAL_PACKAGES) - set(${PROJECT_NAME}_ALL_DEFINED_TOPLEVEL_PACKAGES - ${${PROJECT_NAME}_DEFINED_TPLS} ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) - list(LENGTH ${PROJECT_NAME}_ALL_DEFINED_TOPLEVEL_PACKAGES - ${PROJECT_NAME}_NUM_ALL_DEFINED_TOPLEVEL_PACKAGES) + + # ${PROJECT_NAME}_REVERSE_DEFINED_TPLS (ToDo: Remove the need for this #63) + if (${PROJECT_NAME}_DEFINED_TPLS) + set(${PROJECT_NAME}_REVERSE_DEFINED_TPLS ${${PROJECT_NAME}_DEFINED_TPLS}) + list(REVERSE ${PROJECT_NAME}_REVERSE_DEFINED_TPLS) + else() + set(${PROJECT_NAME}_REVERSE_DEFINED_TPLS) + endif() + + # ${PROJECT_NAME}_DEFINED_TOPLEVEL_PACKAGES + set(${PROJECT_NAME}_DEFINED_TOPLEVEL_PACKAGES + ${${PROJECT_NAME}_DEFINED_TPLS} + ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) + list(LENGTH ${PROJECT_NAME}_DEFINED_TOPLEVEL_PACKAGES + ${PROJECT_NAME}_NUM_DEFINED_TOPLEVEL_PACKAGES) endmacro() diff --git a/cmake/tribits/core/package_arch/TribitsReadDepsFilesCreateDepsGraph.cmake b/cmake/tribits/core/package_arch/TribitsReadDepsFilesCreateDepsGraph.cmake index d254dcb0bae8..c55673ee927b 100644 --- a/cmake/tribits/core/package_arch/TribitsReadDepsFilesCreateDepsGraph.cmake +++ b/cmake/tribits/core/package_arch/TribitsReadDepsFilesCreateDepsGraph.cmake @@ -55,16 +55,16 @@ include(DualScopeSet) # `//cmake/Dependencies.cmake`_ files and builds the # package dependency graph variables. # -# This macro reads from the variables:: +# This macro reads from the variables: # -# ${PROJECT_NAME}_ALL_REPOSITORIES (old) -# ${PROJECT_NAME}_PACKAGES (old) +# * `${PROJECT_NAME}_ALL_REPOSITORIES`_ +# * `${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ # -# and writes to the variable:: +# and writes to the variables: # -# ${PROJECT_NAME}_SE_PACKAGES (old) +# * `${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES`_ # -# as well creates the package dependency variables described in `List +# as well creates the package dependency variables described in `Legacy list # variables defining the package dependencies graph`_ that defines the # directed acyclic dependency (DAG) package dependency graph (with navigation # up and down the graph). @@ -161,16 +161,16 @@ endmacro() # packages and subpackages, respectively, and builds the package dependency # graph variables. # -# This macro reads from the variables:: +# This macro reads from the variables: # -# ${PROJECT_NAME}_ALL_REPOSITORIES -# ${PROJECT_NAME}_PACKAGES (old) +# * `${PROJECT_NAME}_ALL_REPOSITORIES`_ +# * `${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ # -# And writes to the variable:: +# And writes to the variable: # -# ${PROJECT_NAME}_SE_PACKAGES (old) +# * `${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES`_ # -# as well creates the package dependency variables described in `List +# as well creates the package dependency variables described in `Legacy list # variables defining the package dependencies graph`_ that defines the # directed acyclic dependency (DAG) package dependency graph (with navigation # up and down the graph). @@ -183,21 +183,23 @@ macro(tribits_read_all_package_deps_files_create_deps_graph) tribits_read_external_package_deps_files_add_to_graph(${tribitsExternalPkg}) endforeach() - set(${PROJECT_NAME}_SE_PACKAGES "") # Packages and subpackages + set(${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES "") # Packages and subpackages - foreach(TRIBITS_PACKAGE IN LISTS ${PROJECT_NAME}_PACKAGES) + foreach(TRIBITS_PACKAGE IN LISTS ${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_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}) - if (${PROJECT_NAME}_REVERSE_SE_PACKAGES) - list(REVERSE ${PROJECT_NAME}_REVERSE_SE_PACKAGES) + # Create a reverse packages list for later use + set(${PROJECT_NAME}_REVERSE_DEFINED_INTERNAL_PACKAGES + ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) + if (${PROJECT_NAME}_REVERSE_DEFINED_INTERNAL_PACKAGES) + list(REVERSE ${PROJECT_NAME}_REVERSE_DEFINED_INTERNAL_PACKAGES) endif() - list(LENGTH ${PROJECT_NAME}_SE_PACKAGES ${PROJECT_NAME}_NUM_SE_PACKAGES) - print_var(${PROJECT_NAME}_NUM_SE_PACKAGES) + list(LENGTH ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES + ${PROJECT_NAME}_NUM_DEFINED_INTERNAL_PACKAGES) + print_var(${PROJECT_NAME}_NUM_DEFINED_INTERNAL_PACKAGES) endmacro() @@ -214,7 +216,7 @@ endmacro() # This reads in the file ``${_DEPENDENCIES_FILE}`` and sets the # varaible:: # -# _LIB_ALL_DEPENDENCIES +# _LIB_DEFINED_DEPENDENCIES # # See `Function call tree for constructing package dependency graph`_ # @@ -248,18 +250,21 @@ endmacro() # ${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES # ${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES # ${PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES -# ${PACKAGE_NAME}_FORWARD_LIB_REQUIRED_DEP_PACKAGES -# ${PACKAGE_NAME}_FORWARD_LIB_OPTIONAL_DEP_PACKAGES -# ${PACKAGE_NAME}_FORWARD_TEST_REQUIRED_DEP_PACKAGES -# ${PACKAGE_NAME}_FORWARD_TEST_OPTIONAL_DEP_PACKAGES +# _FORWARD_LIB_REQUIRED_DEP_PACKAGES +# _FORWARD_LIB_OPTIONAL_DEP_PACKAGES +# _FORWARD_TEST_REQUIRED_DEP_PACKAGES +# _FORWARD_TEST_OPTIONAL_DEP_PACKAGES # -# It also appends the list variable:: +# (where ```` are upstream dependencies of this package +# ``${PACKAGE_NAME}``). # -# ${PROJECT_NAME}_SE_PACKAGES (old) +# It also appends the list variable: # -# as for the subpackage dependencies under this top-level package are read in +# * `${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES`_ +# +# Also, the subpackage dependencies under this top-level package are read in # order and then this top-level package is appended and dependencies are -# dependencies are created for them. +# created for them. # # See `Function call tree for constructing package dependency graph`_ # @@ -291,7 +296,7 @@ macro(tribits_read_toplevel_package_deps_files_add_to_graph PACKAGE_NAME) # B.2) Process this package's subpackages first *before* finishing this packages! - tribits_parse_subpackages_append_se_packages_add_options(${PACKAGE_NAME}) + tribits_parse_subpackages_append_packages_add_options(${PACKAGE_NAME}) tribits_read_package_subpackage_deps_files_add_to_graph(${PACKAGE_NAME}) @@ -311,8 +316,8 @@ macro(tribits_read_toplevel_package_deps_files_add_to_graph PACKAGE_NAME) math(EXPR SUBPACKAGE_IDX "${SUBPACKAGE_IDX}+1") endforeach() - # Append this package to list of SE packages *after* subpackages are added! - list(APPEND ${PROJECT_NAME}_SE_PACKAGES ${PACKAGE_NAME}) + # Append this package to list of packages *after* subpackages are added! + list(APPEND ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES ${PACKAGE_NAME}) # Process this parent package's dependency lists! tribits_process_package_dependencies_lists(${PACKAGE_NAME}) @@ -335,17 +340,29 @@ endmacro() # Macro that sets to undefined all of the variables that must be set by the # `tribits_package_define_dependencies()`_ macro. # -# It also sets to empty the forward dependency list vars:: +# It also sets to empty the forward dependency list vars: # -# _FORWARD_ +# * `${PACKAGE_NAME}_FORWARD_LIB_DEP_PACKAGES`_ +# * `${PACKAGE_NAME}_FORWARD_TEST_DEP_PACKAGES`_ # -# for each of the forward/downstream in `List variables defining the package +# for each of the forward/downstream in `Variables defining the package # dependencies graph`_. # # See `Function call tree for constructing package dependency graph`_ # +# **__Legacy variables:__** +# +# It also sets to empty the forward dependency list vars: +# +# _FORWARD_ +# +# for each of the forward/downstream in `Legacy list variables defining the +# package dependencies graph`_. +# macro(tribits_prep_to_read_dependencies PACKAGE_NAME_IN) + # Initial vars that must be set in the Dependencies.cmake file + tribits_declare_undefined(LIB_REQUIRED_DEP_PACKAGES) tribits_declare_undefined(LIB_OPTIONAL_DEP_PACKAGES) tribits_declare_undefined(TEST_REQUIRED_DEP_PACKAGES) @@ -358,6 +375,12 @@ macro(tribits_prep_to_read_dependencies PACKAGE_NAME_IN) set(REGRESSION_EMAIL_LIST "") # Allow to be empty + # Initialize other vars + + set(${PACKAGE_NAME_IN}_FORWARD_LIB_DEP_PACKAGES "") + set(${PACKAGE_NAME_IN}_FORWARD_TEST_DEP_PACKAGES "") + + # Legacy vars #63 set(${PACKAGE_NAME_IN}_FORWARD_LIB_REQUIRED_DEP_PACKAGES "") set(${PACKAGE_NAME_IN}_FORWARD_LIB_OPTIONAL_DEP_PACKAGES "") set(${PACKAGE_NAME_IN}_FORWARD_TEST_REQUIRED_DEP_PACKAGES "") @@ -451,10 +474,10 @@ endmacro() # tribits_process_package_dependencies_lists() # # Sets up the upstream and downstream/forward package dependency list -# variables for ```` described in `List variables defining the -# package dependencies graph`_. Note that the downstream/forward dependencies -# of upstream packages on this package ```` are built up -# incrementally. +# variables for ```` described in `Legacy list variables defining +# the package dependencies graph`_. Note that the downstream/forward +# dependencies of upstream packages on this package ```` are +# built up incrementally. # # See `Function call tree for constructing package dependency graph`_ # @@ -488,8 +511,8 @@ endmacro() # package given the vars read in from the macro # `tribits_package_define_dependencies()`_. # -# Sets the upstream/backward dependency variables defined in the section `List -# variables defining the package dependencies graph`_. +# Sets the upstream/backward dependency variables defined in the section +# `Legacy list variables defining the package dependencies graph`_. # # This also handles the several types of issues: # @@ -510,7 +533,7 @@ function(tribits_set_dep_packages PACKAGE_NAME LIB_OR_TEST REQUIRED_OR_OPTIO set(LIST_TYPE ${LIB_OR_TEST}_${REQUIRED_OR_OPTIONAL}_DEP_PACKAGES) set(PACKAGE_DEPS_LIST "") - set(SE_PACKAGE_ENABLE_VAR ${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}) + set(PACKAGE_ENABLE_VAR ${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}) foreach(DEP_PKG ${${LIST_TYPE}}) if (TRIBITS_SET_DEP_PACKAGES_DEBUG_DUMP) @@ -534,7 +557,7 @@ function(tribits_set_dep_packages PACKAGE_NAME LIB_OR_TEST REQUIRED_OR_OPTIO AND NOT ${DEP_PKG}_ALLOW_MISSING_EXTERNAL_PACKAGE ) tribits_abort_on_missing_package( - "${DEP_PKG}" "${PACKAGE_NAME}" "${PROJECT_NAME}_SE_PACKAGES") + "${DEP_PKG}" "${PACKAGE_NAME}" "${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES") else() if (${DEP_PKG}_ALLOW_MISSING_EXTERNAL_PACKAGE) if (${PROJECT_NAME}_WARN_ABOUT_MISSING_EXTERNAL_PACKAGES) @@ -543,10 +566,10 @@ function(tribits_set_dep_packages PACKAGE_NAME LIB_OR_TEST REQUIRED_OR_OPTIO " ${${DEP_PKG}_ALLOW_MISSING_EXTERNAL_PACKAGE}!") endif() if (REQUIRED_OR_OPTIONAL STREQUAL "REQUIRED") - message_wrapper("NOTE: Setting ${SE_PACKAGE_ENABLE_VAR}=OFF because" + message_wrapper("NOTE: Setting ${PACKAGE_ENABLE_VAR}=OFF because" " package ${PACKAGE_NAME} has a required dependency on missing" " package ${DEP_PKG}!") - dual_scope_set(${SE_PACKAGE_ENABLE_VAR} OFF) + dual_scope_set(${PACKAGE_ENABLE_VAR} OFF) endif() endif() if (${PROJECT_NAME}_VERBOSE_CONFIGURE) @@ -582,7 +605,7 @@ endfunction() # # _FORWARD_ # -# for one of the vars listed in `List variables defining the package +# for one of the vars listed in `Legacy list variables defining the package # dependencies graph`_. # # This function is called multiple times to build up the forward package @@ -720,16 +743,16 @@ endfunction() ################################################################################ -# @MACRO: tribits_parse_subpackages_append_se_packages_add_options() +# @MACRO: tribits_parse_subpackages_append_packages_add_options() # # Usage:: # -# tribits_parse_subpackages_append_se_packages_add_options() +# tribits_parse_subpackages_append_packages_add_options() # # Macro that parses the read-in variable # ``SUBPACKAGES_DIRS_CLASSIFICATIONS_OPTREQS`` set by the macro -# `tribits_package_define_dependencies()`_ , add subpackages to the list of -# defined packages, and define user cache var options for those subpackages. +# `tribits_package_define_dependencies()`_ , adds subpackages to the list of +# defined packages, and defines user cache var options for those subpackages. # # This sets the list variables for the parent package ````:: # @@ -744,18 +767,16 @@ endfunction() # _PARENT_PACKAGE # _PARENT_REPOSITORY # -# And it appends for each subpackage to variable:: +# And it appends for each subpackage to variable: # -# ${PROJECT_NAME}_SE_PACKAGES (old) +# * `${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES`_ # # See `Function call tree for constructing package dependency graph`_ # -macro(tribits_parse_subpackages_append_se_packages_add_options +macro(tribits_parse_subpackages_append_packages_add_options PACKAGE_NAME ) - #message("TRIBITS_PARSE_SUBPACKAGES_APPEND_SE_PACKAGES_ADD_OPTIONS: ${PACKAGE_NAME}") - # Structure of SUBPACKAGES_DIRS_CLASSIFICATIONS_OPTREQS set(SPDC_SP_NAME_OFFSET 0) set(SPDC_SP_DIR_OFFSET 1) @@ -830,7 +851,7 @@ macro(tribits_parse_subpackages_append_se_packages_add_options list(APPEND ${PACKAGE_NAME}_SUBPACKAGES ${SUBPACKAGE_NAME}) list(APPEND ${PACKAGE_NAME}_SUBPACKAGE_DIRS ${SUBPACKAGE_DIR}) list(APPEND ${PACKAGE_NAME}_SUBPACKAGE_OPTREQ ${SUBPACKAGE_OPTREQ}) - list(APPEND ${PROJECT_NAME}_SE_PACKAGES ${SUBPACKAGE_FULLNAME}) + list(APPEND ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES ${SUBPACKAGE_FULLNAME}) set(${SUBPACKAGE_FULLNAME}_SOURCE_DIR "${SUBPACKAGE_FULL_SOURCE_DIR}") set(${SUBPACKAGE_FULLNAME}_REL_SOURCE_DIR "${${PACKAGE_NAME}_REL_SOURCE_DIR}/${SUBPACKAGE_DIR}") @@ -876,7 +897,7 @@ macro(tribits_read_package_subpackage_deps_files_add_to_graph PACKAGE_NAME) #message("TRIBITS_READ_PACKAGE_SUBPACKAGE_DEPS_FILES_ADD_TO_GRAPH: ${PACKAGE_NAME}") - #print_var(${PROJECT_NAME}_SE_PACKAGES) + #print_var(${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES) set(SUBPACKAGE_IDX 0) foreach(TRIBITS_SUBPACKAGE ${${PACKAGE_NAME}_SUBPACKAGES}) diff --git a/cmake/tribits/core/package_arch/TribitsSystemDataStructuresMacrosFunctions.rst b/cmake/tribits/core/package_arch/TribitsSystemDataStructuresMacrosFunctions.rst index bcf012bdd97f..3e5a4e3718b1 100644 --- a/cmake/tribits/core/package_arch/TribitsSystemDataStructuresMacrosFunctions.rst +++ b/cmake/tribits/core/package_arch/TribitsSystemDataStructuresMacrosFunctions.rst @@ -2,31 +2,145 @@ TriBITS System Data Structures ------------------------------ This section describes the global CMake variables that make up the -data-structures and the functions that create them that define the TriBITS -package dependency system. These variables all exist at the base -project-level CMakeLists.txt file and are typically not cache variables (and -therefore are recomputed on every reconfigure). These variables define a -graph of external packages (i.e. TPLs) and internal packages (i.e. buildable -CMake packages). This information is meant for maintainers of the TriBITS -system itself and should not need to be known by TriBITS Project maintainers. +data-structures and the macros/functions that create them that define the +TriBITS package dependency system. All of these variables all exist at the +base project-level ``CMakeLists.txt`` file and are typically not cache +variables (and therefore are recomputed on every reconfigure and can therefore +accommodate changing enables/disables without a full reconfigure from +scratch). These variables define a graph of external packages/TPLs +(i.e. pre-built and found out on the system) and internal packages +(i.e. buildable CMake packages). This information is meant for maintainers of +the TriBITS system itself and should **not** need to be known by `TriBITS +Project Developers`_ or even `TriBITS Project Architects`_. -Basic TriBITS Project, Repository, Package, and Subpackage Core Variables -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -The basic variables that define a TriBITS Project, Repository, Package and -Subpackage are listed at the below links: +TriBITS naming conventions +++++++++++++++++++++++++++ + +Before describing the TriBITS package architecture data-structures and the +macros/functions that create and manipulate those data-structures in detail, +first we define some naming conventions for TriBITS macros/function and +variables. + +First, the term "Package" is overloaded in the context of TriBITS (and in +CMake for that matter). In the context of TriBITS, here are the **different +types of entities called a "Package"**: + +* **TriBITS External packages/TPLs** listed in the `/TPLsList.cmake`_ + file and require a `/FindTPL.cmake`_ file. + +* **TriBITS Top-level internal packages** directly listed in the + `/PackagesList.cmake`_ file + +* **TriBITS Subpackages** for a top-level package (defined by the + ``SUBPACKAGES_DIRS_CLASSIFICATIONS_OPTREQS`` argument in + `tribits_package_define_dependencies()`_ command called in the + `/cmake/Dependencies.cmake`_ file) + +* **Native CMake packages** which are found using ``find_package()`` and + require a ``Config.cmake`` package config file or a + ``Find.cmake`` find module file + +* **CMake Packaging** of a CMake project which means breaking it into + components and provide various source and binary distributions. (A TriBITS + top-level package maps to a CMake packaging "component".) + +Also, there are the collection of all three of the TriBITS-related "packages". + +To try to avoid ambiguity, we define the following identifiers that appear in +TriBITS variable, macro, and function names: + +* **TPL** or **EXTERNAL_PACKAGE**: Variable or function specifically for + processing TriITS external packages/TPLs. + +* **TOPLEVEL_PACKAGE**: Variable or a function specifically for a top-level + package (or sometimes if there is no ambiguity just **PACKAGE**). + +* **SUBPACKAGE**: Variable or a function specifically for a subpackage (and + **SUBPACKAGE_FULLNAME** if it is the full name of a subpackage which + includes the top-level parent package name + ``${PARENT_PACKAGE_NAME}${SUBPACKAGE}``). + +* **PACKAGE**: Variable or function that could pertain to an external + package/TPL, or a top-level package, or a subpackage. + +TriBITS uses the follow general case naming conventions for variables, macros, +functions and module files: + +* ``ProperNoun_UPPER_CASE`` is generally used for global and cache variables. + The proper nouns using CamelCase include the names of TriBITS entities like + Projects, Repositories, and Packages. UPPER_CASE is used for non-proper + nouns. (E.g. ``Trilinos_SOURCE_DIR``) + +* ``camelCaseVariableName`` or ``lower_case_variable_name`` is generally used + for local variable names. + +* ``tribits_lower_case_name()`` is generally used for TriBITS functions and + macros. (E.g. ``trilinos_package_define_dependencies()``) + +* ``TribitsModuleName.cmake`` is generally used for TriBITS CMake module file + names. (E.g. ``TribitsAddTest.cmake``) + + +User-level TriBITS Project, Repository, Package and Subpackage Variables +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The user-level variables that define a TriBITS Project, Repository, Package +and Subpackage are listed in: * `TriBITS Project Core Variables`_ * `TriBITS Repository Core Variables`_ * `TriBITS Package Core Variables`_ * `TriBITS Subpackage Core Variables`_ +* `TriBITS External Package/TPL Core Variables`_ These are variables that can be accessed by `TriBITS Project Developers`_ but are also used in the internal implementation of TriBITS functionality. + Lists of external and internal packages +++++++++++++++++++++++++++++++++++++++ +List of non-cache top-level project variables: + +* `${PROJECT_NAME}_DEFINED_TPLS`_: List of all defined external packages/TPLs + + * Size `${PROJECT_NAME}_NUM_DEFINED_TPLS`_ + +* `${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_: List of all defined + internal top-level packages + + * Size `${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ + +* `${PROJECT_NAME}_DEFINED_TOPLEVEL_PACKAGES`_: List of all defined external + packages/TPLs and top-level internal packages + + * Size `${PROJECT_NAME}_NUM_DEFINED_TOPLEVEL_PACKAGES`_ + +* `${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES`_: List of all defined internal + top-level packages and subpackages + + * Size `${PROJECT_NAME}_NUM_DEFINED_INTERNAL_PACKAGES`_ + +* `${PROJECT_NAME}_DEFINED_PACKAGES`_: List of all defined external + packages/TPLs, internal top-level packages, and subpackages (size + `${PROJECT_NAME}_NUM_DEFINED_PACKAGES`_) + + * Size ${PROJECT_NAME}_NUM_DEFINED_PACKAGES + +* `${PROJECT_NAME}_ENABLED_PACKAGES`_: Subset of all enabled packages from + ``${PROJECT_NAME}_DEFINED_PACKAGES`` + + * Size `${PROJECT_NAME}_NUM_ENABLED_PACKAGES`_ + +All of the above list variables are sorted in a valid dependency ordering in +that any upstream dependent packages are listed before a given package in +these lists. After these variables have been set in the macro +`tribits_read_all_project_deps_files_create_deps_graph()`_, they should +considered to be constant and **not** modified. + +These variables are described in more detail below. + .. _${PROJECT_NAME}_DEFINED_TPLS: The original list of all defined external packages (TPLs) read from the @@ -34,364 +148,330 @@ processed `/TPLsList.cmake`_ files is given in the list variable:: ${PROJECT_NAME}_DEFINED_TPLS -.. _${PACKAGE_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES: +.. _${PROJECT_NAME}_NUM_DEFINED_TPLS: + +with size:: + + ${PROJECT_NAME}_NUM_DEFINED_TPLS + +.. _${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES: The original list of all defined internal top-level packages read in from the processed `/PackagesList.cmake`_ files is given in the list variable:: - ${PACKAGE_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES + ${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES -An internal TriBITS Package (i.e. a package that can be built from source) -will have a non-empty `${PACKAGE_NAME}_SOURCE_DIR`_ ``!= ""`` while an -external package (i.e. TPL that is pre-built and installed in some way) in -this list will have a non-empty `${PACKAGE_NAME}_FINDMOD`_ ``!= ""``. +.. _${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES: -The sizes of these lists is given by the variables:: +with size:: - ${PACKAGE_NAME}_NUM_DEFINED_TPLS - ${PACKAGE_NAME}_NUM_DEFINED_INTERNAL_PACKAGES + ${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES -The full list of defined external packages (TPLs) and top-level internal -packages (TriBITS packages) is stored in the project-level non-cache list -variable:: +In this list, a defined internal TriBITS Package (i.e. a package that can be +built from source) will have `${PACKAGE_NAME}_SOURCE_DIR`_ ``!= ""`` while a +defined external package/TPL will have a non-empty `${PACKAGE_NAME}_FINDMOD`_ +``!= ""``. + +.. _${PROJECT_NAME}_DEFINED_TOPLEVEL_PACKAGES: - ${PROJECT_NAME}_ALL_DEFINED_TOPLEVEL_PACKAGES +The full list of defined external packages/TPLs and top-level internal +packages (i.e. TriBITS top-level packages) (**not** including subpackages) is +stored in the project-level non-cache list variable:: -The first set of elements in this list are the defined external packages -(TPLs) that are read in from the `/TPLsList.cmake`_ files from each + ${PROJECT_NAME}_DEFINED_TOPLEVEL_PACKAGES + +.. _${PROJECT_NAME}_NUM_DEFINED_TOPLEVEL_PACKAGES: + +with size:: + + ${PROJECT_NAME}_NUM_DEFINED_TOPLEVEL_PACKAGES + +The first set of elements in this list are the defined external packages/TPLs +that are read in from the `/TPLsList.cmake`_ files from each processed TriBITS repository, in order. This is followed by the set of internal packages (TriBITS packages) that are defined in the `/PackagesList.cmake`_ files from each processed TriBITS repository, read in order. This list does **not** include any subpackages. Note that some of the packages listed in -`${PACKAGE_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ may actually be treated +`${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ may actually be treated as external packages and not build from source code and instead will be found -out on the system as pre-built/pre-installed packages using -``find_package()``. The final decision for if a package -is treated as an internal or external package is determined by the variable:: +on the system as pre-built/pre-installed packages using +``find_package()``. The final decision for if a package is +treated as an internal or external package is determined by the variable:: ${PACKAGE_NAME}_PACKAGE_BUILD_STATUS=[INTERNAL|EXTERNAL] -which gets set various criteria as described in section `Determining if a -package is internal or external`_. This variable determines what +which gets set using various criteria as described in section `Determining if +a package is internal or external`_. This variable determines what pre-built/pre-installed packages must be found out on the system if enabled and what internal packages need to be built if enabled. The set of external packages, internal top-level packages, and internal sub-packages are just called the list of "Packages". When the term "Packages" -is used with an adjective, it is usually meant in this more general context. +is used without an adjective, it is usually meant in this more general +context. -ToDo: Describe the data-structures of all "Packages" which includes -subpackages as well and the lists of enabled packages. +.. _${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES: -These data-structures as well as the package dependencies graph is built up in -the macro `tribits_read_all_project_deps_files_create_deps_graph()`_ with the -call graph described in the section `Function call tree for constructing -package dependency graph`_. +The set of all of the defined internal top-level packages **and subpackages** +is given by the non-cache project-level list variable:: -A set of enable/disable logic is applied in the macro -`tribits_adjust_package_enables()`_. Once all of this logic has been applied, -the final list of enabled external packages, internal packages, and all -enabled packages are given in the list variables:: + ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES - ${PROJECT_NAME}_ALL_ENABLED_EXTERNAL_PACKAGES - ${PROJECT_NAME}_ALL_ENABLED_INTERNAL_PACKAGES - ${PROJECT_NAME}_ALL_ENABLED_PACKAGES +.. _${PROJECT_NAME}_NUM_DEFINED_INTERNAL_PACKAGES: -where:: +with the size:: - length( ${PROJECT_NAME}_ALL_ENABLED_EXTERNAL_PACKAGES ) - + - length( ${PROJECT_NAME}_ALL_ENABLED_INTERNAL_PACKAGES ) - = - length( ${PROJECT_NAME}_ALL_ENABLED_PACKAGES ) + ${PROJECT_NAME}_NUM_DEFINED_INTERNAL_PACKAGES -Note that the list ``${PROJECT_NAME}_ALL_ENABLED_EXTERNAL_PACKAGES`` can -include both regular TPLs which have ``${PACKAGE_NAME}_FINDMOD != ""`` and -also packages that could be built as internal packages which have -``${PACKAGE_NAME}_SOURCE_DIR != ""``. Again, how such non-TPL external -packages are determined and found is the subject of section `Determining if a -package is internal or external`_. +.. _${PROJECT_NAME}_DEFINED_PACKAGES: -When sorting lists of packages, one only needs to consider enabled packages, -and therefore only the list ``${PROJECT_NAME}_ALL_ENABLED_PACKAGES`` needs to -be considered in those cases. +The set of all of the defined external packages/TPLs, internal top-level +packages **and subpackages** is given by the non-cache project-level list +variable:: + ${PROJECT_NAME}_DEFINED_PACKAGES ------------------------------------------------------------------------------------ +.. _${PROJECT_NAME}_NUM_DEFINED_PACKAGES: +with the size:: -ToDo: Deal with old data-structures below after the refactoring for #63 is -complete! + ${PROJECT_NAME}_NUM_DEFINED_PACKAGES -The full list of defined top-level parent packages is stored in the -project-level non-cache list variable:: +These data-structures as well as the package dependencies graph is built up in +the macro `tribits_read_all_project_deps_files_create_deps_graph()`_ with the +call graph described in the section `Function call tree for constructing +package dependency graph`_. These data-structures don't consider what +packages are actually enabled or disabled. - ${PROJECT_NAME}_PACKAGES +The enable/disable logic (given an initial set of enables and disables) is +applied in the macro `tribits_adjust_package_enables()`_. Once all of this +logic has been applied, several lists of enabled and non-enabled packages are +computed. -This list does **not** include any subpackages. This gets created from the -`/PackagesList.cmake`_ file from each processed TriBITS repository. +The list of enabled internal **top-level** packages is given in the non-cache +project-level list variable:: -The full list of all of the defined packages and subpackages is stored in the -project-level non-cache list variable:: + ${PROJECT_NAME}_ENABLED_INTERNAL_TOPLEVEL_PACKAGES - ${PROJECT_NAME}_SE_PACKAGES +with size:: -That list is created from the information in the -`/PackagesList.cmake`_ and `/cmake/Dependencies.cmake`_ -files for the top-level packages read and processed in the macro -`tribits_read_deps_files_create_deps_graph()`_ using macros in the file:: + ${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES - TribitsAdjustPackageEnables.cmake +The list of enabled external packages/TPLs and internal **top-level** packages +is given in the non-cache project-level list variable:: -One can determine if a package in this list is a top-level parent package or a -sub-subpackage based on the value of the variable -`${PACKAGE_NAME}_PARENT_PACKAGE`_. If the value is non empty, then -``${PACKAGE_NAME}`` is a subpackage. If the value is empty "", then -``${PACKAGE_NAME}`` is a parent package. + ${PROJECT_NAME}_ENABLED_TOPLEVEL_PACKAGES -This full number of defined top-level parent packages (i.e. the number of -items in the array ``${PROJECT_NAME}_PACKAGES``) is given in the variable:: +with size:: - ${PROJECT_NAME}_NUM_PACKAGES + ${PROJECT_NAME}_NUM_ENABLED_TOPLEVEL_PACKAGES -and the 0-based index of the last package in the array -``${PROJECT_NAME}_PACKAGES`` (i.e. ``${PROJECT_NAME}_NUM_PACKAGES - 1``) is -given in:: +.. _${PROJECT_NAME}_ENABLED_PACKAGES: - ${PROJECT_NAME}_LAST_PACKAGE_IDX +The list of enabled external packages/TPLs, internal **top-level and +subpackages** is given in the non-cache project-level list variable:: -This data gets set in functions in the file:: + ${PROJECT_NAME}_ENABLED_PACKAGES - TribitsProcessPackagesAndDirsLists.cmake +.. _${PROJECT_NAME}_NUM_ENABLED_PACKAGES: -The full list of defined TPLs is stored in the variable:: +with size:: - ${PROJECT_NAME}_TPLS + ${PROJECT_NAME}_NUM_ENABLED_PACKAGES -This list is created from the `/TPLsList.cmake`_ files from each -defined TriBITS Repository. Along with this, the following variables for each -of these TriBITS TPLs are defined:: -* `${TPL_NAME}_FINDMOD`_ -* `${TPL_NAME}_TESTGROUP`_ -This data gets set in functions in the file:: +Variables defining the package dependencies graph ++++++++++++++++++++++++++++++++++++++++++++++++++ - TribitsProcessTplsLists.cmake +TriBITS sets up the following project-level non-cache variables that define +the dependencies for each external package/TPL and internal package: -NOTE: The same external package (TPL) can be duplicated in multiple -``TPLsList.cmake`` files. This has the affect of allowing overrides of the -``FindTPL.cmake`` module. See the discussion in `TriBITS TPL`_ for -more details. + .. _${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES: + ``${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`` ------------------------------------------------------------------------------------ + The list of all **defined direct** required and optional upstream external + package/TPL and internal package dependencies, regardless if they are + enabled or not. (Note, this is currently the concatenation of the lists + `${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES`_, + `${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES`_, + ``${PACKAGE_NAME}_LIB_REQUIRED_DEP_TPLS``, and + ``${PACKAGE_NAME}_LIB_OPTIONAL_DEP_TPLS``. With the completion of #63, + the ``XXX_TPLS`` lists will be removed.) To determine if a given direct + upstream package ```` in this list is enabled or not for this + package ``${PACKAGE_NAME}``, check the value of + ``${PACKAGE_NAME}_ENABLE_``. NOTE: The variables + ``${PACKAGE_NAME}_ENABLE_`` will be set even for required upstream + packages to allow for uniform loops involving required and optional + upstream dependencies. (And for a parent package with subpackages, it is + possible for a required subpackage to **not** be enabled and for + ``${PACKAGE_NAME}_ENABLE_`` to be ``OFF`` as explained in + `Subpackage enable does not auto-enable the parent package`_.) This list + will be set regardless of if the package ``${PACKAGE_NAME}`` is enabled or + not. + .. _${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES: + ``${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES`` -List variables defining the package dependencies graph -++++++++++++++++++++++++++++++++++++++++++++++++++++++ + List of all **enabled direct** required and optional upstream external + package/TPL and internal package dependencies. This is strict subset of + `${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`_ (i.e. all of the ```` + items in this list will have ``${PACKAGE_NAME}_ENABLE_`` set to + ``ON``). -The following top-level non-cache variables are defined after reading in each -top-level package and subpackage ``Dependencies.cmake`` files and they are -used to define the basic dependencies that exist between packages in a project -to support the enable and disable logic described in section ???. These -variables taken together constitute a bidirectional acyclic graph (DAG) -data-structure for package dependencies. + .. _${PACKAGE_NAME}_LIB_DEP_REQUIRED_: -The following lists variables define the **direct** dependencies from a -package ``${PACKAGE_NAME}`` to its upstream packages which are directly set in -a package's `/cmake/Dependencies.cmake`_ file. (These lists -should **not** contain any *indirect* dependencies as the dependency system -already handles these automatically.) + ``${PACKAGE_NAME}_LIB_DEP_REQUIRED_`` - .. _${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES: + Is ``TRUE`` if the entry ```` in + `${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`_ or + `${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES`_ is a required LIB dependency + and is ``FALSE`` if it is only an optional LIB dependency. - ``${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES`` - - List of *direct* package dependencies that are required for the libraries - and non-test executables built by ``${PACKAGE_NAME}``. - - .. _${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES: + .. _${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES: - ``${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES`` - - List of *direct* package dependencies that are only optional for the - libraries and non-test executables built by ``${PACKAGE_NAME}``. - - .. _${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES: + ``${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES`` - ``${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES`` - - List of *direct* package dependencies that are required for the - tests/examples built by ``${PACKAGE_NAME}``. This list should **not** - contain any of the packages already listed in - ``${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES``. - - .. _${PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES: + This list of all **define direct** extra package test required and + optional upstream external package/TPL and internal package dependencies. + (Currently, this is a concatenation of the lists + `${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES`_, + `${PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES`_, + ``${PACKAGE_NAME}_TEST_REQUIRED_DEP_TPLS``, and + ``${PACKAGE_NAME}_TEST_OPTIONAL_DEP_TPLS``. With the completion of #63, + the ``XXX_TPLS`` lists will be removed.) This list is set regardless if + the package ``${PACKAGE_NAME}`` is enabled or not. - ``${PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES``` - - List of *direct* package dependencies that are optional for the - tests/examples built by ``${PACKAGE_NAME}``. This list should **not** - contain any of the SE packages listed in - ``${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES``, - ``${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES``, or - ``${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES``. + .. _${PACKAGE_NAME}_TEST_ENABLED_DEPENDENCIES: + + ``${PACKAGE_NAME}_TEST_ENABLED_DEPENDENCIES`` + + The list of all **enabled direct** extra required and optional upstream + external package/TPL and internal package dependencies. This is a strict + subset of `${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES`_. + + .. _${PACKAGE_NAME}_TEST_DEP_REQUIRED_: + + ``${PACKAGE_NAME}_TEST_DEP_REQUIRED_`` + + Is ``TRUE`` if the entry ```` in + `${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES`_ or + `${PACKAGE_NAME}_TEST_ENABLED_DEPENDENCIES`_ is a required TEST dependency + and is ``FALSE`` if it is only an optional TEST dependency. For the sake + of simplicity and generality, + ``${PACKAGE_NAME}_TEST_DEP_REQUIRED_`` will also be set to + ``TRUE`` or ``FALSE`` for ```` in the lists + `${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`_ or + `${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES`_ because a LIB dependency is + also implicitly a TEST dependency. + +NOTE: The same upstream package ```` can be included in both the lists +`${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`_ and +`${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES`_ if ```` is optional in +the former but required in the latter (which is a valid situation if you think +about it as a package that may be optional for the lib(s) of a package is +required by the tests for a package). (Otherwise, duplicate entries will be +removed from the list ``${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES``.) + +NOTE: Having flat lists containing both optional and required dependencies +with the bool variables ``${PACKAGE_NAME}_[LIB|TEST]_DEP_REQUIRED_`` +defining which entries are required or optional is modeled after the CMake +standard for handing the ``COMPONENTS`` and ``OPTIONAL_COMPONENTS`` arguments +to ``find_package()`` in that it passes that info to the +``Config.cmake`` file as the single list variable +``${CMAKE_FIND_PACKAGE_NAME}_FIND_COMPONENTS`` and the bool vars +``${CMAKE_FIND_PACKAGE_NAME}_FIND_REQUIRED_``. Given the above upstream dependency list variables, the following derived list variables are then constructed which provide navigation from a package to its downstream/forward dependent packages: - ``${PACKAGE_NAME}_FORWARD_LIB_REQUIRED_DEP_PACKAGES`` - + .. _${PACKAGE_NAME}_FORWARD_LIB_DEP_PACKAGES: + + ``${PACKAGE_NAME}_FORWARD_LIB_DEP_PACKAGES`` + For a given package ``${PACKAGE_NAME}``, lists the names of all of the - forward packages ``${FORWARD_PACKAGE_NAME}`` that list this package in - their ``${FORWARD_PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES`` variables. + forward packages ```` that list this package in their + ``_LIB_DEFINED_PACKAGES`` variables. + + .. _${PACKAGE_NAME}_FORWARD_TEST_DEP_PACKAGES: + + ``${PACKAGE_NAME}_FORWARD_TEST_DEP_PACKAGES`` + + For a given package ``${PACKAGE_NAME}``, lists the names of all of the + forward packages ```` that list this package in their + ``_TEST_DEFINED_PACKAGES`` variables. + + +User enable/disable cache variables ++++++++++++++++++++++++++++++++++++ + +The following variables can be set by the user to determine what packages get +enabled or disabled:: - ``${PACKAGE_NAME}_FORWARD_LIB_OPTIONAL_DEP_PACKAGES`` + ${PROJECT_NAME}_ENABLE_ALL_PACKAGES - For a given package ``${PACKAGE_NAME}``, lists the names of all of the - forward packages ``${FORWARD_PACKAGE_NAME}`` that list this package in - their ``${FORWARD_PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES`` variables. + ${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES - ``${PACKAGE_NAME}_FORWARD_TEST_REQUIRED_DEP_PACKAGES`` + ${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES + + ${PROJECT_NAME}_ENABLE_${PACKAGE_NAME} - For a given package ``${PACKAGE_NAME}``, lists the names of all of the - forward packages ``${FORWARD_PACKAGE_NAME}`` that list this package in - their ``${FORWARD_PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES`` variables. + ${PROJECT_NAME}_ENABLE_TESTS - ``${PACKAGE_NAME}_FORWARD_TEST_OPTIONAL_DEP_PACKAGES`` + ${PROJECT_NAME}_ENABLE_EXAMPLES - For a given package ``${PACKAGE_NAME}``, lists the names of all of the - forward packages ``${FORWARD_PACKAGE_NAME}`` that list this package in - their ``${FORWARD_PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES`` variables. + ${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_PACKAGE_NAME} + + ${PACKAGE_NAME}_ENABLE_TESTS + + ${PACKAGE_NAME}_ENABLE_EXAMPLES + +according to the rules described in `Package Dependencies and Enable/Disable +Logic`_. Determining if a package is internal or external ++++++++++++++++++++++++++++++++++++++++++++++++ As mentioned above, some subset of packages listed in -`${PACKAGE_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ (which all have +`${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ (which all have ``${PACKAGE_NAME}_SOURCE_DIR != ""``) may be chosen to be external packages. Packages that could be built internally may be chosen to be treated as -external packages by setting:: +external packages (and therefore located on the system using +``find_package()``) by setting:: - -D TPL_ENABLE_=ON + -D TPL_ENABLE_=ON or:: - -D _ROOT= + -D _ROOT= + +.. _${PACKAGE_NAME}_PACKAGE_BUILD_STATUS: -The final status of whether a listed package is an internal package or an +The final status of whether a package is treated as an internal package or an external package is provided by the variable:: ${PACKAGE_NAME}_PACKAGE_BUILD_STATUS=[INTERNAL|EXTERNAL] As a result, every other package upstream from any of these -```` packages must therefore also be treated as external -packages automatically. - -The primary TriBITS file that processes and defines these variables is:: - - TribitsAdjustPackageEnables.cmake - -There are pretty good unit and regression tests to demonstrate and protect -this functionality in the directory:: - - TriBITS/test/core/ - - -External package dependencies -+++++++++++++++++++++++++++++ - -ToDo: Document how dependencies between external packages/TPLs are determined -in ``FindTPLDependencies.cmake`` files and -``_LIB_REQUIRED_DEP_PACKAGES_OVERRIDE`` and -``_LIB_OPTIONAL_DEP_PACKAGES_OVERRIDE`` variables that can be -overridden in the cache. - - -Flat lists of direct package dependencies -+++++++++++++++++++++++++++++++++++++++++ - -TriBITS sets up the following lists of dependencies for each internal and -external package/TPL: - - .. _${PACKAGE_NAME}_LIB_ALL_DEPENDENCIES: - - ``${PACKAGE_NAME}_LIB_ALL_DEPENDENCIES`` - - The list of all **direct** required and optional upstream internal and - external packages/TPL dependencies, regardless if they are enabled or not. - This is concatenation of lists - `${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES`_, - `${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES`_, - ``${PACKAGE_NAME}_LIB_REQUIRED_DEP_TPLS``, and - ``${PACKAGE_NAME}_LIB_OPTIONAL_DEP_TPLS`` (with the latter two lists soon - to disappear as part of #63). To determine if a given direct upstream - package ```` in this list is enabled/supported or not for this - package ``${PACKAGE_NAME}``, check the value of - ``${PACKAGE_NAME}_ENABLE_``. NOTE: The variables - ``${PACKAGE_NAME}_ENABLE_`` will be set even for required upstream - internal and external packages/tpls to allow for uniform loops involving - required and optional upstream dependencies. (And for a parent package - with subpackages, it is possible for a required subpackage to **not** be - enabled and for ``${PACKAGE_NAME}_ENABLE_`` to be ``OFF`` as - explained in `Subpackage enable does not auto-enable the parent - package`_.) This list will be set regardless of if the package - ``${PACKAGE_NAME}`` is enabled or not. - - .. _${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES: - - ``${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES`` - - List of all **enabled** **direct** required and optional upstream internal - and external packages/TPL dependencies. This is strict subset - `${PACKAGE_NAME}_LIB_ALL_DEPENDENCIES`_ (i.e. all of the ```` - items in this list will have ``${PACKAGE_NAME}_ENABLE_`` set to - ``ON``). - - .. _${PACKAGE_NAME}_TEST_ALL_DEPENDENCIES: - - ``${PACKAGE_NAME}_TEST_ALL_DEPENDENCIES`` - - This list of all **direct** extra package test required and optional - upstream internal and external packages/TPLs. This list includes just the - extra dependencies not already listed in - `${PACKAGE_NAME}_LIB_ALL_DEPENDENCIES`_. This is a concatenation of the - lists `${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES`_, - `${PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES`_, - ``${PACKAGE_NAME}_TEST_REQUIRED_DEP_TPLS``, and - ``${PACKAGE_NAME}_TEST_OPTIONAL_DEP_TPLS`` (with the latter two lists soon - to disappear as part of #63). This list is set regardless if the package - ``${PACKAGE_NAME}`` is enabled or not. - - .. _${PACKAGE_NAME}_TEST_ENABLED_DEPENDENCIES: - - ``${PACKAGE_NAME}_TEST_ENABLED_DEPENDENCIES`` +```` packages must therefore also be treated as +external packages automatically and will have +``${PACKAGE_NAME}_PACKAGE_BUILD_STATUS=EXTERNAL`` set accordingly. - The list of all **enabled** **direct** extra required and optional - upstream internal and external packages/TPL dependencies. This is a - strict subset of `${PACKAGE_NAME}_TEST_ALL_DEPENDENCIES`_. This list - includes just the extra dependencies not already listed in - `${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES`_. +Other package-related variables ++++++++++++++++++++++++++++++++ -List variables defining include directories and libraries -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +The following global internal cache variables are used to provide more +information about a given internal package: -ToDo: Eliminate this section and these variables once we move to modern CMake -targets as part of #299. - -The following global internal cache variables are used to communicate the -required header directory paths and libraries needed to build and link against -a given package's capabilities: - ``${PACKAGE_NAME}_LIBRARIES`` - + Defines list of *only* the libraries associated with the given (sub)package and does *not* list libraries in upstream packages. Linkages to upstream packages is taken care of with calls to @@ -420,9 +500,9 @@ a given package's capabilities: ${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES=ON. NOTE: This list does *not* include the package itself. This list is created after all of the enable/disable logic is applied. - + ``${PARENT_PACKAGE_NAME}_LIB_TARGETS`` - + Lists all of the library targets for this package only that are as part of this package added by the `tribits_add_library()`_ function. This is used to define a target called ${PACKAGE_NAME}_libs that is then used by @@ -431,9 +511,9 @@ a given package's capabilities: upstream direct dependent packages will be added. This is needed for the chain of dependencies to work correctly. Note that subpackages don't have this variable defined for them. - + ``${PARENT_PACKAGE_NAME}_ALL_TARGETS`` - + Lists all of the targets associated with this package. This includes all libraries and tests added with `tribits_add_library()`_ and `tribits_add_executable()`_. If this package has no targets (no libraries @@ -442,37 +522,84 @@ a given package's capabilities: variable defined for them. -User enable/disable cache variables -+++++++++++++++++++++++++++++++++++ +Legacy list variables defining the package dependencies graph ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -The following variables can be set by the user to determine what packages get -enabled or disabled:: - - ${PROJECT_NAME}_ENABLE_ALL_PACKAGES - - ${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES - - ${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES +The following top-level non-cache variables are defined after reading in each +top-level package and subpackage ``Dependencies.cmake`` files and they are +used to define the basic dependencies that exist between packages in a project +to support the enable and disable logic described in section `Package +Dependencies and Enable/Disable Logic`_. These variables taken together +constitute a bidirectional acyclic graph (DAG) data-structure for package +dependencies. - ${PROJECT_NAME}_ENABLE_${PACKAGE_NAME} - - ${PROJECT_NAME}_ENABLE_TESTS - - ${PROJECT_NAME}_ENABLE_EXAMPLES - - ${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_PACKAGE_NAME} - - ${PACKAGE_NAME}_ENABLE_TESTS - - ${PACKAGE_NAME}_ENABLE_EXAMPLES +The following lists variables define the **direct** dependencies from a +package ``${PACKAGE_NAME}`` to its upstream packages which are directly set in +a package's `/cmake/Dependencies.cmake`_ file. (These lists +should **not** contain any *indirect* dependencies as the dependency system +already handles these automatically.) -according to the rules described in `Package Dependencies and Enable/Disable -Logic`_. + .. _${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES: + + ``${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES`` -There are pretty good unit and regression tests to demonstrate and protect -this functionality in the directory:: + List of *direct* package dependencies that are required for the libraries + and non-test executables built by ``${PACKAGE_NAME}``. - TriBITS/test/core/ + .. _${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES: + + ``${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES`` + + List of *direct* package dependencies that are only optional for the + libraries and non-test executables built by ``${PACKAGE_NAME}``. + + .. _${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES: + + ``${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES`` + + List of *direct* package dependencies that are required for the + tests/examples built by ``${PACKAGE_NAME}``. This list should **not** + contain any of the packages already listed in + ``${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES``. + + .. _${PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES: + + ``${PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES``` + + List of *direct* package dependencies that are optional for the + tests/examples built by ``${PACKAGE_NAME}``. This list should **not** + contain any of the packages listed in + ``${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES``, + ``${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES``, or + ``${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES``. + +Given the above upstream dependency list variables, the following derived list +variables are then constructed which provide navigation from a package to its +downstream/forward dependent packages: + + ``${PACKAGE_NAME}_FORWARD_LIB_REQUIRED_DEP_PACKAGES`` + + For a given package ``${PACKAGE_NAME}``, lists the names of all of the + forward packages ``${FORWARD_PACKAGE_NAME}`` that list this package in + their ``${FORWARD_PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES`` variables. + + ``${PACKAGE_NAME}_FORWARD_LIB_OPTIONAL_DEP_PACKAGES`` + + For a given package ``${PACKAGE_NAME}``, lists the names of all of the + forward packages ``${FORWARD_PACKAGE_NAME}`` that list this package in + their ``${FORWARD_PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES`` variables. + + ``${PACKAGE_NAME}_FORWARD_TEST_REQUIRED_DEP_PACKAGES`` + + For a given package ``${PACKAGE_NAME}``, lists the names of all of the + forward packages ``${FORWARD_PACKAGE_NAME}`` that list this package in + their ``${FORWARD_PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES`` variables. + + ``${PACKAGE_NAME}_FORWARD_TEST_OPTIONAL_DEP_PACKAGES`` + + For a given package ``${PACKAGE_NAME}``, lists the names of all of the + forward packages ``${FORWARD_PACKAGE_NAME}`` that list this package in + their ``${FORWARD_PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES`` variables. Function call tree for constructing package dependency graph @@ -503,7 +630,7 @@ lists and dependency data-structures described above. | ``include(`` `/cmake/Dependencies.cmake`_ ``)`` | `tribits_assert_read_dependency_vars()`_ | `tribits_save_off_dependency_vars()`_ -| `tribits_parse_subpackages_append_se_packages_add_options()`_ +| `tribits_parse_subpackages_append_packages_add_options()`_ | `tribits_read_package_subpackage_deps_files_add_to_graph()`_ | Foreach ``SUBPACKAGE``: | `tribits_read_subpackage_deps_file_add_to_graph()`_ @@ -520,52 +647,5 @@ lists and dependency data-structures described above. | `tribits_append_forward_dep_packages()`_ | `tribits_abort_on_missing_package()`_ - -Notes on dependency logic -------------------------- - -The logic used to define the intra-package linkage variables is complex due to -a number of factors: - -1) Packages can have libraries or no libraries. - -2) In installation-testing mode, the libraries for a package are read from a - file instead of generated in source. - -3) A library can be a regular package library, or a test-only library, in - which case it will not be listed in ``${PACKAGE_NAME}_LIBRARIES``. The - above description does not even talk about how test-only libraries are - handed within the system except to say that they are excluded from the - package's exported library dependencies. - -The management and usage of the intra-package linkage variables is spread -across a number of TriBITS ``*.cmake`` files but the primary ones are:: - - TribitsPackageMacros.cmake - TribitsSubPackageMacros.cmake - TribitsLibraryMacros.cmake - TribitsAddExecutable.cmake - -There are other TriBITS cmake files that also access these variables but these -are the key files. The CMake code in these files all work together in -coordination to set up and use these variables in a way that allows for smooth -compiling and linking of source code for users of the TriBITS system. - -Another file with complex dependency logic related to these variables is:: - - TribitsWriteClientExportFiles.cmake - -The TriBITS cmake code in this file servers a very similar role for external -clients and therefore needs to be considered in this setting. - -All of these variations and features makes this a bit of a complex system to -say the least. Also, currently, there is essentially no unit or regression -testing in place for the CMake code in these files that manipulate these -intra-package dependency variables. Because this logic is tied in with -actually building and linking code, there has not been a way set up yet to -allow it to be efficiently tested outside of the actual build. But there are -a number of example projects that are part of the automated TriBITS test suite -that do test much of the logic used in these variables. - .. LocalWords: acyclic TriBITS SUBPACKAGES CTEST subpackages buildable TPLs TPLS .. LocalWords: Subpackage CMake CMakeLists diff --git a/cmake/tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake b/cmake/tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake index 8a5eeb35f686..d3cb102cf3d2 100644 --- a/cmake/tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake +++ b/cmake/tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake @@ -741,9 +741,9 @@ endfunction() # tribits_tpl_tentatively_enable() # # This function can be called from any CMakeLists.txt file to put a TPL in -# tentative enable mode. But typically, it is called from an SE Package's +# tentative enable mode. But typically, it is called from an Package's # `/cmake/Dependencies.cmake`_ file (see `How to tentatively -# enable a TPL`_). +# enable an external package/TPL`_). # # This should only be used for optional TPLs. It will not work correctly for # required TPLs because any enabled packages that require this TPL will not be diff --git a/cmake/tribits/core/package_arch/TribitsWriteClientExportFiles.cmake b/cmake/tribits/core/package_arch/TribitsWriteClientExportFiles.cmake index cf3e9ef2f37b..1f31b6ec0c01 100644 --- a/cmake/tribits/core/package_arch/TribitsWriteClientExportFiles.cmake +++ b/cmake/tribits/core/package_arch/TribitsWriteClientExportFiles.cmake @@ -274,7 +274,7 @@ function(tribits_write_flexible_package_client_export_files) #to help us create a properly ordered list of tpls. if (FULL_TPL_SET) set(ORDERED_FULL_TPL_SET ${FULL_TPL_SET}) - tribits_sort_list_according_to_master_list("${${PROJECT_NAME}_REVERSE_TPLS}" + tribits_sort_list_according_to_master_list("${${PROJECT_NAME}_REVERSE_DEFINED_TPLS}" ORDERED_FULL_TPL_SET) endif() @@ -567,7 +567,7 @@ function(tribits_append_dependent_package_config_file_includes_and_enables packa # Add set of enables/disables for all upstream dependencies string(APPEND configFileStr "# Enables/Disables for upstream package dependencies\n") - foreach(depPkg IN LISTS ${packageName}_LIB_ALL_DEPENDENCIES) + foreach(depPkg IN LISTS ${packageName}_LIB_DEFINED_DEPENDENCIES) if (${packageName}_ENABLE_${depPkg}) set(enableVal ON) else() @@ -730,7 +730,7 @@ function(tribits_write_project_client_export_files) # Reversing the package list so that libraries will be produced in order of # most dependent to least dependent. - set(PACKAGE_LIST ${${PROJECT_NAME}_SE_PACKAGES}) + set(PACKAGE_LIST ${${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES}) if (PACKAGE_LIST) list(REVERSE PACKAGE_LIST) endif() @@ -750,8 +750,8 @@ function(tribits_write_project_client_export_files) # Reversing the tpl list so that the list of tpls will be produced in # order of most dependent to least dependent. - if (${PROJECT_NAME}_TPLS) - set(TPL_LIST ${${PROJECT_NAME}_TPLS}) + if (${PROJECT_NAME}_DEFINED_TPLS) + set(TPL_LIST ${${PROJECT_NAME}_DEFINED_TPLS}) list(REVERSE TPL_LIST) endif() diff --git a/cmake/tribits/core/std_tpls/FindTPLCUDA.cmake b/cmake/tribits/core/std_tpls/FindTPLCUDA.cmake index aee77cc7ef94..a8b1ab8b1ca1 100644 --- a/cmake/tribits/core/std_tpls/FindTPLCUDA.cmake +++ b/cmake/tribits/core/std_tpls/FindTPLCUDA.cmake @@ -53,18 +53,8 @@ # ************************************************************************ # @HEADER -find_package(CUDA REQUIRED) # Will abort if not found! - -macro(package_add_cuda_library cuda_target) - tribits_add_library(${cuda_target} ${ARGN} CUDALIBRARY) -endmacro() - -set(TPL_CUDA_INCLUDE_DIRS ${CUDA_TOOLKIT_INCLUDE}) -set(TPL_CUDA_LIBRARIES ${CUDA_CUDART_LIBRARY} ${CUDA_cublas_LIBRARY} - ${CUDA_cufft_LIBRARY}) - -tribits_tpl_find_include_dirs_and_libraries(CUDA - REQUIRED_LIBS_NAMES willNotBeUsed) - -unset(TPL_CUDA_INCLUDE_DIRS) -unset(TPL_CUDA_LIBRARIES) +find_package(CUDAToolkit REQUIRED) # Will abort if not found! +tribits_extpkg_create_imported_all_libs_target_and_config_file( CUDA + INNER_FIND_PACKAGE_NAME CUDAToolkit + IMPORTED_TARGETS_FOR_ALL_LIBS CUDA::cufft CUDA::cublas CUDA::cudart ) +# Above, we could add more dependencies if we need diff --git a/cmake/tribits/core/utils/PrintNonemptyVarWithSpaces.cmake b/cmake/tribits/core/utils/PrintNonemptyVarWithSpaces.cmake index 64ebe2a579f8..de8e331ade88 100644 --- a/cmake/tribits/core/utils/PrintNonemptyVarWithSpaces.cmake +++ b/cmake/tribits/core/utils/PrintNonemptyVarWithSpaces.cmake @@ -43,26 +43,26 @@ include(AppendStringVarWithSep) # @FUNCTION: print_nonempty_var_with_spaces() # -# Print a defined variable giving its name then value printed with spaces -# instead of ``';'`` but only if it is not empty. +# Print a list variable giving its name then value printed with spaces instead +# of ``';'``, but only if the list is non-empty. # # Usage:: # -# print_nonempty_var_with_spaces( ) +# print_nonempty_var_with_spaces( ) # # Prints the variable as:: # # : ... # -# If ``$`` is ``TRUE`` on input, then the variable is not -# touched. If however, the variable ``$`` is not ``TRUE`` on -# input, then it is set to ``TRUE`` on output. +# If ```` is ``TRUE`` on input, then the variable is not +# touched. If however, the variable ```` is not ``TRUE`` and +# the list ```` in non-empty, then ```` is set to +# ``TRUE`` on output. # -function(print_nonempty_var_with_spaces VARIBLE_NAME PRINTED_VAR_OUT) - assert_defined(VARIBLE_NAME) - if (NOT "${${VARIBLE_NAME}}" STREQUAL "") - string(REPLACE ";" " " OUTSTR "${${VARIBLE_NAME}}") - message("-- ${VARIBLE_NAME}: ${OUTSTR}") - set(${PRINTED_VAR_OUT} TRUE PARENT_SCOPE) +function(print_nonempty_var_with_spaces variableName printedVarOut) + if (NOT "${${variableName}}" STREQUAL "") + string(REPLACE ";" " " OUTSTR "${${variableName}}") + message("-- ${variableName}: ${OUTSTR}") + set(${printedVarOut} TRUE PARENT_SCOPE) endif() endfunction() diff --git a/cmake/tribits/ctest_driver/TribitsAddDashboardTarget.cmake b/cmake/tribits/ctest_driver/TribitsAddDashboardTarget.cmake index 723725deb3d7..52851ce3cc96 100644 --- a/cmake/tribits/ctest_driver/TribitsAddDashboardTarget.cmake +++ b/cmake/tribits/ctest_driver/TribitsAddDashboardTarget.cmake @@ -76,7 +76,7 @@ macro(tribits_add_dashboard_target) set(${PROJECT_NAME}_ENABLED_PACKAGES_LIST) set(${PROJECT_NAME}_ENABLED_PACKAGES_CMAKE_ARG_LIST) - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_SE_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_ENABLED_INTERNAL_PACKAGES}) if (${PROJECT_NAME}_ENABLE_${TRIBITS_PACKAGE} AND ${TRIBITS_PACKAGE}_ENABLE_TESTS) if (${PROJECT_NAME}_ENABLED_PACKAGES_LIST) set(${PROJECT_NAME}_ENABLED_PACKAGES_LIST @@ -118,7 +118,7 @@ macro(tribits_add_dashboard_target) append_set(EXPR_CMND_ARGS "CTEST_DO_COVERAGE_TESTING=${${PROJECT_NAME}_ENABLE_COVERAGE_TESTING}") endif() if (NOT "${CTEST_BUILD_FLAGS}" STREQUAL "") - append_set(EXPR_CMND_ARGS "CTEST_BUILD_FLAGS='${CTEST_BUILD_FLAGS}'") + append_set(EXPR_CMND_ARGS "CTEST_BUILD_FLAGS=${CTEST_BUILD_FLAGS}") endif() if (NOT "${CTEST_PARALLEL_LEVEL}" STREQUAL "") append_set(EXPR_CMND_ARGS "CTEST_PARALLEL_LEVEL=${CTEST_PARALLEL_LEVEL}") diff --git a/cmake/tribits/ctest_driver/TribitsCTestDriverCore.cmake b/cmake/tribits/ctest_driver/TribitsCTestDriverCore.cmake index 33f2c886b88a..500dd0bf9b0a 100644 --- a/cmake/tribits/ctest_driver/TribitsCTestDriverCore.cmake +++ b/cmake/tribits/ctest_driver/TribitsCTestDriverCore.cmake @@ -559,7 +559,7 @@ include(TribitsCTestDriverCoreHelpers) # the specific set of packages to test. If left at the default value of # empty "", then `${PROJECT_NAME}_ENABLE_ALL_PACKAGES`_ is set to ``ON`` # and that enables packages as described in `_ENABLE_ALL_PACKAGES -# enables all PT (cond. ST) SE packages`_. This variable can use ',' to +# enables all PT (cond. ST) packages`_. This variable can use ',' to # separate package names instead of ';'. The default value is empty "". # # .. _${PROJECT_NAME}_ADDITIONAL_PACKAGES: @@ -2269,12 +2269,12 @@ function(tribits_ctest_driver) set(${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES ON) set(DO_PROCESS_MPI_ENABLES FALSE) # Should not be needed but CMake is messing up tribits_adjust_and_print_package_dependencies() - # Above sets ${PROJECT_NAME}_NUM_ENABLED_PACKAGES + # Above sets ${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES select_final_set_of_packages_to_directly_test() # Above sets ${PROJECT_NAME}_PACKAGES_TO_DIRECTLY_TEST - tribits_print_enabled_packages_list_from_var( ${PROJECT_NAME}_PACKAGES_TO_DIRECTLY_TEST + tribits_print_packages_list_enable_status_from_var( ${PROJECT_NAME}_PACKAGES_TO_DIRECTLY_TEST "\nFinal set of packages to be explicitly processed by CTest/CDash" ON FALSE) message( @@ -2283,7 +2283,7 @@ function(tribits_ctest_driver) "\n***") if (CTEST_ENABLE_MODIFIED_PACKAGES_ONLY - AND ${PROJECT_NAME}_NUM_ENABLED_PACKAGES GREATER 0 + AND ${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES GREATER 0 AND MODIFIED_PACKAGES_LIST ) message("\nMODIFIED_PACKAGES_LIST='${MODIFIED_PACKAGES_LIST}'" @@ -2294,13 +2294,13 @@ function(tribits_ctest_driver) " Running in regular mode, processing all enabled packages!\n") endif() - if (${PROJECT_NAME}_NUM_ENABLED_PACKAGES GREATER 0) + if (${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES GREATER 0) message( - "\n${PROJECT_NAME}_NUM_ENABLED_PACKAGES=${${PROJECT_NAME}_NUM_ENABLED_PACKAGES}:" + "\n${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES=${${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES}:" " Configuring packages!\n") else() message( - "\n${PROJECT_NAME}_NUM_ENABLED_PACKAGES=${${PROJECT_NAME}_NUM_ENABLED_PACKAGES}:" + "\n${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES=${${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES}:" " Exiting the script!\n") report_queued_errors() return() diff --git a/cmake/tribits/ctest_driver/TribitsCTestDriverCoreHelpers.cmake b/cmake/tribits/ctest_driver/TribitsCTestDriverCoreHelpers.cmake index 1d62d292e8ea..c6135cb88c70 100644 --- a/cmake/tribits/ctest_driver/TribitsCTestDriverCoreHelpers.cmake +++ b/cmake/tribits/ctest_driver/TribitsCTestDriverCoreHelpers.cmake @@ -513,7 +513,7 @@ macro(enable_only_modified_packages) message("\nDirectly modified or failing non-disabled packages that need" " to be tested: ALL_PACKAGES") else() - tribits_print_enabled_se_package_list( + tribits_print_internal_package_list_enable_status( "\nDirectly modified or failing non-disabled packages that need to be tested" ON FALSE ) endif() @@ -542,7 +542,7 @@ macro(select_final_set_of_packages_to_directly_test) set(${PROJECT_NAME}_PACKAGES_TO_DIRECTLY_TEST) - foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_PACKAGES}) + foreach(TRIBITS_PACKAGE ${${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES}) set(PROCESS_THE_PACKAGE FALSE) diff --git a/cmake/tribits/doc/build_ref/TribitsBuildReferenceBody.rst b/cmake/tribits/doc/build_ref/TribitsBuildReferenceBody.rst index 1da6b9a05873..9abf82ed5cd2 100644 --- a/cmake/tribits/doc/build_ref/TribitsBuildReferenceBody.rst +++ b/cmake/tribits/doc/build_ref/TribitsBuildReferenceBody.rst @@ -49,7 +49,7 @@ If you have access to the git repositories (which which includes a snapshot of TriBITS), then install CMake with:: $ cd / - $ export TRIBITS_BASE_DIR=/cmake/tribits + $ TRIBITS_BASE_DIR=/cmake/tribits $ $TRIBITS_BASE_DIR/devtools_install/install-cmake.py \ --install-dir-base= --cmake-version=X.Y.Z \ --do-all @@ -165,6 +165,12 @@ Basic configuration A few different approaches for configuring are given below. +* `Create a do-configure script [Recommended]`_ +* `Create a *.cmake file and point to it [Most Recommended]`_ +* `Using the QT CMake configuration GUI`_ + +.. _Create a do-configure script [Recommended]: + a) Create a 'do-configure' script such as [Recommended]:: #!/bin/bash @@ -178,7 +184,7 @@ a) Create a 'do-configure' script such as [Recommended]:: ./do-configure [OTHER OPTIONS] -D_ENABLE_=ON - where ```` is a valid SE Package name (see above), etc. and + where ```` is a valid Package name (see above), etc. and ``SOURCE_BASE`` is set to the source base directory (or your can just give it explicitly in the script). @@ -193,6 +199,8 @@ a) Create a 'do-configure' script such as [Recommended]:: .. __CONFIGURE_OPTIONS_FILE: +.. _Create a *.cmake file and point to it [Most Recommended]: + b) Create a ``*.cmake`` file and point to it [Most Recommended]. Create a do-configure script like:: @@ -222,10 +230,12 @@ b) Create a ``*.cmake`` file and point to it [Most Recommended]. time stamp, unlike when using ``-C .cmake``, see below). One can use the ``FORCE`` option in the ``set()`` commands shown above and - that will override any value of the options that might already be set. - However, that will not allow the user to override the options on the CMake - command-line using ``-D=`` so it is generally **not** desired to - use ``FORCE``. + that will override any value of the options that might already be set (but + when using ``-C`` to include this forced ``set( ... FORCE)`` will only + override the value if the file with the ``set()`` is listed after the + ``-D=`` command-line option). However, that will not allow the + user to override the options on the CMake command-line using + ``-D=`` so it is generally **not** desired to use ``FORCE``. One can also pass in a list of configuration fragment files separated by commas ``','`` which will be read in the order they are given as:: @@ -265,30 +275,55 @@ b) Create a ``*.cmake`` file and point to it [Most Recommended]. project source directory location may not be known or easy to get). 2) When configuration files are read in using - ``_CONFIGURE_OPTIONS_FILE``, the will get reprocessed on every + ``_CONFIGURE_OPTIONS_FILE``, they will get reprocessed on every reconfigure (such as when reconfigure happens automatically when running ``make``). That means that if options change in those included ``*.cmake`` files from the initial configure, then those updated options will get automatically picked up in a reconfigure. But when processing ``*.cmake`` - files using the built-in ``-C .cmake`` argument, updated options - will not get set. Therefore, if one wants to have the ``*.cmake`` files + files using the built-in ``-C .cmake`` argument, updated options will + not get set. Therefore, if one wants to have the ``*.cmake`` files automatically be reprocessed, then one should use ``_CONFIGURE_OPTIONS_FILE``. But if one does not want to have the - contents of the ``*.cmake`` file reread on reconfigures, then one would want - to use ``-C``. - - 3) One can create and use parameterized ``*.cmake`` files that can be used - with multiple TriBITS projects. For example, one can have set statements - like ``set(${PROJECT_NAME}_ENABLE_Fortran OFF ...)`` since ``PROJECT_NAME`` - is known before the file is included. One can't do that with ``cmake -C`` - and instead would have to the full variables names specific for a given - project. - - 4) Non-cache project-level variables can be set in a ``*.cmake`` file that - will impact the configuration. When using the ``-C`` option, only variables - set with ``set( CACHE ...)`` will impact the configuration. - - 5) However, the ``*.cmake`` files specified by + contents of the ``.cmake`` file reread on reconfigures, then one would + want to use ``-C .cmake``. + + 3) When using ``_CONFIGURE_OPTIONS_FILE``, one can create and use + parameterized ``*.cmake`` files that can be used with multiple TriBITS + projects. For example, one can have set statements like + ``set(${PROJECT_NAME}_ENABLE_Fortran OFF ...)`` since ``PROJECT_NAME`` is + known before the file is included. One cannot do that with ``-C`` and + instead would have to provide the full variables names specific for a given + TriBITS project. + + 4) When using ``_CONFIGURE_OPTIONS_FILE``, non-cache project-level + variables can be set in a ``*.cmake`` file that will impact the + configuration. When using the ``-C`` option, only variables set with + ``set( CACHE ...)`` will impact the configuration. + + 5) Cache variables forced set with ``set( CACHE + "" FORCE)`` in a ``.cmake`` file pulled in with ``-C + .cmake`` will only override a cache variable ``-D=`` + passed on the command-line if the ``-C .cmake`` argument comes + **after** the ``-D=`` argument (i.e. ``cmake + -D= -C .cmake``). Otherwise, if the order of the + ``-D`` and ``-C`` arguments is reversed (i.e. ``cmake -C .cmake + -D=``) then the forced ``set()`` statement **WILL NOT** + override the cache var set on the command-line with ``-D=``. + However, note that a forced ``set()`` statement **WILL** override other + cache vars set with non-forced ``set()`` statements ``set( + CACHE "")`` in the same ``*.cmake`` file or in previously read + ``-C .cmake`` files included on the command-line before the file ``-C + .cmake``. Alternatively, if the file is pulled in with + ``-D_CONFIGURE_OPTIONS_FILE=.cmake``, then a ``set( + CACHE "" FORCE)`` statement in a ``.cmake`` **WILL** + override a cache variable passed in on the command-line + ``-D=`` no matter the order of the arguments + ``-D_CONFIGURE_OPTIONS_FILE=.cmake`` and + ``-D=``. (This is because the file ``.cmake`` is + included as part of the processing of the project's top-level + ``CMakeLists.txt`` file.) + + 6) However, the ``*.cmake`` files specified by ``_CONFIGURE_OPTIONS_FILE`` will only get read in **after** the project's ``ProjectName.cmake`` and other ``set()`` statements are called at the top of the project's top-level ``CMakeLists.txt`` file. So any CMake @@ -304,9 +339,18 @@ b) Create a ``*.cmake`` file and point to it [Most Recommended]. ``CMakeCache.txt`` file. In other words, the context and impact of what get be set from a ``*.cmake`` - file read in through the ``-C`` argument is more limited while the code - listed in the ``*.cmake`` file behaves just like regular CMake statements - executed in the project's top-level ``CMakeLists.txt`` file. + file read in through the built-in CMake ``-C`` argument is more limited + while the code listed in the ``*.cmake`` file pulled in with + ``-D_CONFIGURE_OPTIONS_FILE=.cmake`` behaves just like + regular CMake statements executed in the project's top-level + ``CMakeLists.txt`` file. In addition, any forced set statements in a + ``*.cmake`` file pulled in with ``-C`` **may or may not** override cache + vars sets on the command-line with ``-D=`` depending on the + order of the ``-C`` and ``-D`` options. (There is no order dependency for + ``*.cmake`` files passed in through + ``-D_CONFIGURE_OPTIONS_FILE=.cmake``.) + +.. _Using the QT CMake configuration GUI: c) Using the QT CMake configuration GUI: @@ -344,26 +388,26 @@ See the following use cases: Determine the list of packages that can be enabled ++++++++++++++++++++++++++++++++++++++++++++++++++ -In order to see the list of available SE Packages to enable, just +In order to see the list of available Packages to enable, just run a basic CMake configure, enabling nothing, and then grep the output to see what packages are available to enable. The full set of defined packages is -contained the lines starting with ``'Final set of enabled SE packages'`` and -``'Final set of non-enabled SE packages'``. If no SE packages are enabled by +contained the lines starting with ``'Final set of enabled packages'`` and +``'Final set of non-enabled packages'``. If no packages are enabled by default (which is base behavior), the full list of packages will be listed on -the line ``'Final set of non-enabled SE packages'``. Therefore, to see the +the line ``'Final set of non-enabled packages'``. Therefore, to see the full list of defined packages, run:: - ./do-configure 2>&1 | grep "Final set of .*enabled SE packages" + ./do-configure 2>&1 | grep "Final set of .*enabled packages" Any of the packages shown on those lines can potentially be enabled using ``-D _ENABLE_=ON`` (unless they are set to disabled for some reason, see the CMake output for package disable warnings). -Another way to see the full list of SE packages that can be enabled is to +Another way to see the full list of packages that can be enabled is to configure with `_DUMP_PACKAGE_DEPENDENCIES`_ = ``ON`` and then grep -for ``_SE_PACKAGES`` using, for example:: +for ``_INTERNAL_PACKAGES`` using, for example:: - ./do-configure 2>&1 | grep "_SE_PACKAGES: " + ./do-configure 2>&1 | grep "_INTERNAL_PACKAGES: " Print package dependencies @@ -376,12 +420,12 @@ setting the configure option:: -D _DUMP_PACKAGE_DEPENDENCIES=ON -This will print the basic forward/upstream dependencies for each SE package. +This will print the basic forward/upstream dependencies for each package. To find this output, look for the line:: Printing package dependencies ... -and the dependencies are listed below this for each SE package in the form:: +and the dependencies are listed below this for each package in the form:: -- _LIB_REQUIRED_DEP_TPLS: ... -- _LIB_OPTIONAL_DEP_TPLS: ... @@ -396,7 +440,7 @@ and the dependencies are listed below this for each SE package in the form:: there are no ``_LIB_OPTIONAL_DEP_PACKAGES`` dependencies, then that line is not printed.) -To also see the direct forward/downstream dependencies for each SE package, +To also see the direct forward/downstream dependencies for each package, also include:: -D _DUMP_FORWARD_PACKAGE_DEPENDENCIES=ON @@ -415,7 +459,7 @@ Enable a set of packages .. __ENABLE_TESTS: -To enable an SE package ```` (and optionally also its tests +To enable an package ```` (and optionally also its tests and examples), configure with:: -D _ENABLE_=ON \ @@ -445,7 +489,7 @@ take on the string enum values of ``"ON"``, ``"OFF"``, end empty ``""``. An empty enable means that the TriBITS dependency system is allowed to decide if an enable should be turned on or off based on various logic. The CMake GUI will enforce the values of ``"ON"``, ``"OFF"``, and empty ``""`` but it will -not enforce this if you set the value on the command line or in a set() +not enforce this if you set the value on the command line or in a ``set()`` statement in an input ```*.cmake`` options files. However, setting ``-DXXX_ENABLE_YYY=TRUE`` and ``-DXXX_ENABLE_YYY=FALSE`` is allowed and will be interpreted correctly.. @@ -514,7 +558,7 @@ Enable to test all effects of changing a given package(s) .. __ENABLE_ALL_FORWARD_DEP_PACKAGES: -To enable an SE package ```` to test it and all of its +To enable an package ```` to test it and all of its down-stream packages, configure with:: -D _ENABLE_=ON \ @@ -560,7 +604,7 @@ tested (PT) packages and code. To have this also enable all secondary tested -D _ENABLE_SECONDARY_TESTED_CODE=ON \ NOTE: If this project is a "meta-project", then -``_ENABLE_ALL_PACKAGES=ON`` may not enable *all* the SE packages but +``_ENABLE_ALL_PACKAGES=ON`` may not enable *all* the packages but only the project's primary meta-project packages. See `Package Dependencies and Enable/Disable Logic`_ and `TriBITS Dependency Handling Behaviors`_ for details. @@ -569,7 +613,7 @@ details. Disable a package and all its dependencies ++++++++++++++++++++++++++++++++++++++++++ -To disable an SE package and all of the packages that depend on it, add the +To disable an package and all of the packages that depend on it, add the configure options:: -D _ENABLE_=OFF @@ -1562,8 +1606,8 @@ where ```` = ``BLAS``, ``LAPACK`` ``Boost``, ``Netcdf``, etc. The full list of TPLs that is defined and can be enabled is shown by doing a configure with CMake and then grepping the configure output for ``Final set of -.* TPLs``. The set of TPL names listed in ``'Final set of enabled TPLs'`` and -``'Final set of non-enabled TPLs'`` gives the full list of TPLs that can be +.* TPLs``. The set of TPL names listed in ``'Final set of enabled external packages/TPLs'`` and +``'Final set of non-enabled external packages/TPLs'`` gives the full list of TPLs that can be enabled (or disabled). Some TPLs require only libraries (e.g. Fortran libraries like BLAS or LAPACK), @@ -1808,7 +1852,7 @@ dependencies may need to be tweaked to match how these TPLs were actually installed on some systems. To redefine what dependencies a TPL can have (if the upstream TPLs are enabled), set:: - -D _LIB_ALL_DEPENDENCIES=";;..." + -D _LIB_DEFINED_DEPENDENCIES=";;..." A dependency on an upstream TPL ```` will be set if the an upstream TPL ```` is actually enabled. @@ -2707,9 +2751,9 @@ NOTES: Generating export files ----------------------- -The project can generate export files for external CMake projects or -external Makefile projects. These export files provide the lists of -libraries, include directories, compilers and compiler options, etc. +The project can generate export files for external CMake projects. +These export files provide the lists of libraries, include directories, compilers +and compiler options, etc. To configure to generate CMake export files for the project, configure with:: @@ -2722,7 +2766,7 @@ In addition, this will install versions of these files into the install tree. The list of export files generated can be reduced by specifying the exact list of packages the files are requested for with:: - -D _GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_SE_PACKAGES=";" + -D _GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_PACKAGES=";" NOTES: @@ -4053,6 +4097,12 @@ and then watch that file in another terminal with:: $ tail -f make.dashboard.out +**NOTE:** To pass multiple arguments for ``CTEST_BUILD_FLAGS`` (like adding + ``-k 99999999`` to tell ninja to continue even if there are build errors), + one must quote the entire argument string as:: + + "-DCTEST_BUILD_FLAGS=-j4 -k 99999999" + Setting options to change behavior of 'dashboard' target -------------------------------------------------------- diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableAllPackages.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableAllPackages.txt index d7f508e8993c..07c2c9d87e59 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableAllPackages.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableAllPackages.txt @@ -1,4 +1,4 @@ -Enabling all SE packages that are not currently disabled because of \ +Enabling all packages that are not currently disabled because of \ Trilinos_ENABLE_ALL_PACKAGES=ON (Trilinos_ENABLE_SECONDARY_TESTED_CODE=OFF) ... -- Setting Trilinos_ENABLE_Teuchos=ON @@ -13,21 +13,21 @@ Enabling all remaining required TPLs for current set of enabled packages ... -- Setting TPL_ENABLE_BLAS=ON because it is required by the enabled package Teuchos -- Setting TPL_ENABLE_LAPACK=ON because it is required by the enabled package Teuchos -Final set of enabled packages: Teuchos RTOp Epetra Thyra 4 -Final set of enabled SE packages: Teuchos RTOp Epetra ThyraCoreLibs ThyraEpetra Thyra 6 -Final set of non-enabled packages: Triutils EpetraExt 2 -Final set of non-enabled SE packages: Triutils EpetraExt ThyraGoodStuff ThyraCrazyStuff ThyraEpetraExt 5 -Final set of enabled TPLs: BLAS LAPACK 2 -Final set of non-enabled TPLs: MPI Boost UMFPACK AMD PETSC 5 +Final set of enabled top-level packages: Teuchos RTOp Epetra Thyra 4 +Final set of enabled packages: Teuchos RTOp Epetra ThyraCoreLibs ThyraEpetra Thyra 6 +Final set of non-enabled top-level packages: Triutils EpetraExt 2 +Final set of non-enabled packages: Triutils EpetraExt ThyraGoodStuff ThyraCrazyStuff ThyraEpetraExt 5 +Final set of enabled external packages/TPLs: BLAS LAPACK 2 +Final set of non-enabled external packages/TPLs: MPI Boost UMFPACK AMD PETSC 5 -Getting information for all enabled TPLs ... +Getting information for all enabled external packages/TPLs ... -Processing enabled TPL: BLAS -Processing enabled TPL: LAPACK +Processing enabled external package/TPL: BLAS +Processing enabled external package/TPL: LAPACK Configuring individual enabled Trilinos packages ... -Processing enabled package: Teuchos (Libs) -Processing enabled package: RTOp (Libs) -Processing enabled package: Epetra (Libs) -Processing enabled package: Thyra (CoreLibs, Epetra) +Processing enabled top-level package: Teuchos (Libs) +Processing enabled top-level package: RTOp (Libs) +Processing enabled top-level package: Epetra (Libs) +Processing enabled top-level package: Thyra (CoreLibs, Epetra) diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableEpetra_EnableRTOp_DisableTeuchos.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableEpetra_EnableRTOp_DisableTeuchos.txt index 35c7ca34b5db..b3d165f62422 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableEpetra_EnableRTOp_DisableTeuchos.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableEpetra_EnableRTOp_DisableTeuchos.txt @@ -1,8 +1,8 @@ -Explicitly enabled packages on input (by user): RTOp Epetra 2 -Explicitly disabled packages on input (by user or by default): Teuchos 1 +Explicitly enabled top-level packages on input (by user): RTOp Epetra 2 +Explicitly disabled top-level packages on input (by user or by default): Teuchos 1 -Disabling forward required SE packages and optional intra-package support that have \ - a dependency on disabled SE packages Trilinos_ENABLE_=OFF ... +Disabling forward required packages and optional intra-package support that have \ + a dependency on disabled packages Trilinos_ENABLE_=OFF ... *** *** ERROR: Setting Trilinos_ENABLE_RTOp=OFF which was 'ON' because RTOp has a required \ diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableEpetra_EnableRTOp_DisableTeuchos_DisableEnabledFwdDepPackages.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableEpetra_EnableRTOp_DisableTeuchos_DisableEnabledFwdDepPackages.txt index ec97e9be6ec3..4df89e13e2e1 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableEpetra_EnableRTOp_DisableTeuchos_DisableEnabledFwdDepPackages.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableEpetra_EnableRTOp_DisableTeuchos_DisableEnabledFwdDepPackages.txt @@ -1,8 +1,8 @@ -Explicitly enabled packages on input (by user): RTOp Epetra 2 -Explicitly disabled packages on input (by user or by default): Teuchos 1 +Explicitly enabled top-level packages on input (by user): RTOp Epetra 2 +Explicitly disabled top-level packages on input (by user or by default): Teuchos 1 -Disabling forward required SE packages and optional intra-package support that \ - have a dependency on disabled SE packages Trilinos_ENABLE_=OFF ... +Disabling forward required packages and optional intra-package support that \ + have a dependency on disabled packages Trilinos_ENABLE_=OFF ... *** *** NOTE: Setting Trilinos_ENABLE_RTOp=OFF which was 'ON' because RTOp has \ @@ -10,5 +10,5 @@ Disabling forward required SE packages and optional intra-package support that \ Trilinos_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=ON! *** -Final set of enabled packages: Epetra 1 -Final set of non-enabled packages: Teuchos RTOp Triutils EpetraExt Thyra 5 +Final set of enabled top-level packages: Epetra 1 +Final set of non-enabled top-level packages: Teuchos RTOp Triutils EpetraExt Thyra 5 diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyraCoreLibs_EnableTests.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyraCoreLibs_EnableTests.txt index 7e20d3e74692..8ada266879d6 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyraCoreLibs_EnableTests.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyraCoreLibs_EnableTests.txt @@ -1,14 +1,14 @@ -Explicitly enabled packages on input (by user): 0 +Explicitly enabled top-level packages on input (by user): 0 -Explicitly enabled SE packages on input (by user): ThyraCoreLibs 1 +Explicitly enabled packages on input (by user): ThyraCoreLibs 1 -Explicitly disabled packages on input (by user or by default): 0 +Explicitly disabled top-level packages on input (by user or by default): 0 -Explicitly disabled SE packages on input (by user or by default): ThyraCrazyStuff 1 +Explicitly disabled packages on input (by user or by default): ThyraCrazyStuff 1 -Explicitly enabled TPLs on input (by user): 0 +Explicitly enabled external packages/TPLs on input (by user): 0 -Explicitly disabled TPLs on input (by user or by default): 0 +Explicitly disabled external packages/TPLs on input (by user or by default): 0 Enabling the shell of non-enabled parent packages (mostly for show) that have at least one subpackage enabled ... @@ -20,10 +20,10 @@ Enabling the shell of non-enabled parent packages (mostly for show) that have at -- Setting Trilinos_ENABLE_Thyra=ON because Trilinos_ENABLE_ThyraCoreLibs=ON -Final set of enabled packages: Teuchos RTOp Thyra 3 +Final set of enabled top-level packages: Teuchos RTOp Thyra 3 -Final set of enabled SE packages: Teuchos RTOp ThyraCoreLibs Thyra 4 +Final set of enabled packages: Teuchos RTOp ThyraCoreLibs Thyra 4 -Final set of non-enabled packages: Epetra Triutils EpetraExt 3 +Final set of non-enabled top-level packages: Epetra Triutils EpetraExt 3 -Final set of non-enabled SE packages: Epetra Triutils EpetraExt ThyraGoodStuff ThyraCrazyStuff ThyraEpetra ThyraEpetraExt 7 +Final set of non-enabled packages: Epetra Triutils EpetraExt ThyraGoodStuff ThyraCrazyStuff ThyraEpetra ThyraEpetraExt 7 diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyraEpetra_EnableTests.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyraEpetra_EnableTests.txt index 146e099fe930..9ad431f62a25 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyraEpetra_EnableTests.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyraEpetra_EnableTests.txt @@ -1,21 +1,21 @@ -Explicitly enabled packages on input (by user): 0 +Explicitly enabled top-level packages on input (by user): 0 -Explicitly enabled SE packages on input (by user): ThyraEpetra 1 +Explicitly enabled packages on input (by user): ThyraEpetra 1 -Explicitly disabled packages on input (by user or by default): 0 +Explicitly disabled top-level packages on input (by user or by default): 0 -Explicitly disabled SE packages on input (by user or by default): ThyraCrazyStuff 1 +Explicitly disabled packages on input (by user or by default): ThyraCrazyStuff 1 -Explicitly enabled TPLs on input (by user): 0 +Explicitly enabled external packages/TPLs on input (by user): 0 -Explicitly disabled TPLs on input (by user or by default): 0 +Explicitly disabled external packages/TPLs on input (by user or by default): 0 Enabling all tests and/or examples that have not been explicitly disabled because Trilinos_ENABLE_[TESTS,EXAMPLES]=ON ... -- Setting ThyraEpetra_ENABLE_TESTS=ON -- Setting ThyraEpetra_ENABLE_EXAMPLES=ON -Enabling all required (and optional since Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES=ON) upstream SE packages for current set of enabled packages (Trilinos_ENABLE_SECONDARY_TESTED_CODE=OFF) ... +Enabling all required (and optional since Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES=ON) upstream packages for current set of enabled packages (Trilinos_ENABLE_SECONDARY_TESTED_CODE=OFF) ... -- Setting Trilinos_ENABLE_Epetra=ON because ThyraEpetra has a required dependence on Epetra -- Setting Trilinos_ENABLE_ThyraCoreLibs=ON because ThyraEpetra has a required dependence on ThyraCoreLibs @@ -33,10 +33,10 @@ Enabling the shell of non-enabled parent packages (mostly for show) that have at -- Setting Thyra_ENABLE_TESTS=ON because ThyraEpetra_ENABLE_TESTS=ON -- Setting Thyra_ENABLE_EXAMPLES=ON because ThyraEpetra_ENABLE_EXAMPLES=ON -Final set of enabled packages: Teuchos RTOp Epetra Thyra 4 +Final set of enabled top-level packages: Teuchos RTOp Epetra Thyra 4 -Final set of enabled SE packages: Teuchos RTOp Epetra ThyraCoreLibs ThyraEpetra Thyra 6 +Final set of enabled packages: Teuchos RTOp Epetra ThyraCoreLibs ThyraEpetra Thyra 6 -Final set of non-enabled packages: Triutils EpetraExt 2 +Final set of non-enabled top-level packages: Triutils EpetraExt 2 -Final set of non-enabled SE packages: Triutils EpetraExt ThyraGoodStuff ThyraCrazyStuff ThyraEpetraExt 5 +Final set of non-enabled packages: Triutils EpetraExt ThyraGoodStuff ThyraCrazyStuff ThyraEpetraExt 5 diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_DisableEpetra_EnableTests.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_DisableEpetra_EnableTests.txt index dc3cff703a16..eb18a8887044 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_DisableEpetra_EnableTests.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_DisableEpetra_EnableTests.txt @@ -1,5 +1,5 @@ -Disabling forward required SE packages and optional intra-package support that have a \ - dependency on disabled SE packages Trilinos_ENABLE_=OFF ... +Disabling forward required packages and optional intra-package support that have a \ + dependency on disabled packages Trilinos_ENABLE_=OFF ... -- Setting Trilinos_ENABLE_Triutils=OFF because Triutils has a required library dependence \ on disabled package Epetra @@ -16,17 +16,17 @@ Disabling forward required SE packages and optional intra-package support that h -- Setting Thyra_ENABLE_ThyraEpetraExt=OFF because Thyra has an optional library \ disabled package ThyraEpetraExt -Final set of enabled packages: Teuchos RTOp Thyra 3 -Final set of enabled SE packages: Teuchos RTOp ThyraCoreLibs Thyra 4 -Final set of non-enabled packages: Epetra Triutils EpetraExt 3 -Final set of non-enabled SE packages: Epetra Triutils EpetraExt ThyraGoodStuff \ +Final set of enabled top-level packages: Teuchos RTOp Thyra 3 +Final set of enabled packages: Teuchos RTOp ThyraCoreLibs Thyra 4 +Final set of non-enabled top-level packages: Epetra Triutils EpetraExt 3 +Final set of non-enabled packages: Epetra Triutils EpetraExt ThyraGoodStuff \ ThyraCrazyStuff ThyraEpetra ThyraEpetraExt 7 -Final set of enabled TPLs: BLAS LAPACK 2 -Final set of non-enabled TPLs: MPI Boost UMFPACK AMD PETSC 5 +Final set of enabled external packages/TPLs: BLAS LAPACK 2 +Final set of non-enabled external packages/TPLs: MPI Boost UMFPACK AMD PETSC 5 Configuring individual enabled Trilinos packages ... -Processing enabled package: Teuchos (Libs) -Processing enabled package: RTOp (Libs) -Processing enabled package: Thyra (CoreLibs, Tests, Examples) +Processing enabled top-level package: Teuchos (Libs) +Processing enabled top-level package: RTOp (Libs) +Processing enabled top-level package: Thyra (CoreLibs, Tests, Examples) diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests.txt index 0fc373abad49..46e1cdc7ae5c 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests.txt @@ -1,9 +1,9 @@ +Explicitly enabled top-level packages on input (by user): Thyra 1 Explicitly enabled packages on input (by user): Thyra 1 -Explicitly enabled SE packages on input (by user): Thyra 1 -Explicitly disabled packages on input (by user or by default): 0 -Explicitly disabled SE packages on input (by user or by default): ThyraCrazyStuff 1 -Explicitly enabled TPLs on input (by user): 0 -Explicitly disabled TPLs on input (by user or by default): 0 +Explicitly disabled top-level packages on input (by user or by default): 0 +Explicitly disabled packages on input (by user or by default): ThyraCrazyStuff 1 +Explicitly enabled external packages/TPLs on input (by user): 0 +Explicitly disabled external packages/TPLs on input (by user or by default): 0 Enabling subpackages for hard enables of parent packages due to \ Trilinos_ENABLE_=ON ... @@ -13,8 +13,8 @@ Enabling subpackages for hard enables of parent packages due to \ -- Setting subpackage enable Trilinos_ENABLE_ThyraEpetra=ON because parent package \ Trilinos_ENABLE_Thyra=ON -Disabling forward required SE packages and optional intra-package support that have a \ - dependency on disabled SE packages Trilinos_ENABLE_=OFF ... +Disabling forward required packages and optional intra-package support that have a \ + dependency on disabled packages Trilinos_ENABLE_=OFF ... -- Setting Thyra_ENABLE_ThyraCrazyStuff=OFF because Thyra has an optional library \ dependence on disabled package ThyraCrazyStuff @@ -30,7 +30,7 @@ Enabling all tests and/or examples that have not been explicitly disabled becaus -- Setting Thyra_ENABLE_EXAMPLES=ON Enabling all required (and optional since Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES=ON) \ - upstream SE packages for current set of enabled packages \ + upstream packages for current set of enabled packages \ (Trilinos_ENABLE_SECONDARY_TESTED_CODE=OFF) ... -- NOTE: Not Setting Trilinos_ENABLE_ThyraGoodStuff=ON even though Thyra \ @@ -51,21 +51,21 @@ Enabling all remaining required TPLs for current set of enabled packages ... -- Setting TPL_ENABLE_BLAS=ON because it is required by the enabled package Teuchos -- Setting TPL_ENABLE_LAPACK=ON because it is required by the enabled package Teuchos -Final set of enabled packages: Teuchos RTOp Epetra Thyra 4 -Final set of enabled SE packages: Teuchos RTOp Epetra ThyraCoreLibs ThyraEpetra Thyra 6 -Final set of non-enabled packages: Triutils EpetraExt 2 -Final set of non-enabled SE packages: Triutils EpetraExt ThyraGoodStuff ThyraCrazyStuff ThyraEpetraExt 5 -Final set of enabled TPLs: BLAS LAPACK 2 -Final set of non-enabled TPLs: MPI Boost UMFPACK AMD PETSC 5 +Final set of enabled top-level packages: Teuchos RTOp Epetra Thyra 4 +Final set of enabled packages: Teuchos RTOp Epetra ThyraCoreLibs ThyraEpetra Thyra 6 +Final set of non-enabled top-level packages: Triutils EpetraExt 2 +Final set of non-enabled packages: Triutils EpetraExt ThyraGoodStuff ThyraCrazyStuff ThyraEpetraExt 5 +Final set of enabled external packages/TPLs: BLAS LAPACK 2 +Final set of non-enabled external packages/TPLs: MPI Boost UMFPACK AMD PETSC 5 -Getting information for all enabled TPLs ... +Getting information for all enabled external packages/TPLs ... -Processing enabled TPL: BLAS -Processing enabled TPL: LAPACK +Processing enabled external package/TPL: BLAS +Processing enabled external package/TPL: LAPACK Configuring individual enabled Trilinos packages ... -Processing enabled package: Teuchos (Libs) -Processing enabled package: RTOp (Libs) -Processing enabled package: Epetra (Libs) -Processing enabled package: Thyra (CoreLibs, Epetra, Tests, Examples) +Processing enabled top-level package: Teuchos (Libs) +Processing enabled top-level package: RTOp (Libs) +Processing enabled top-level package: Epetra (Libs) +Processing enabled top-level package: Thyra (CoreLibs, Epetra, Tests, Examples) diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests_EnableBoost_ST.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests_EnableBoost_ST.txt index cbca63ec91cb..00efe417fd24 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests_EnableBoost_ST.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests_EnableBoost_ST.txt @@ -1,9 +1,9 @@ +Explicitly enabled top-level packages on input (by user): Thyra 1 Explicitly enabled packages on input (by user): Thyra 1 -Explicitly enabled SE packages on input (by user): Thyra 1 -Explicitly disabled packages on input (by user or by default): 0 -Explicitly disabled SE packages on input (by user or by default): ThyraCrazyStuff 1 -Explicitly enabled TPLs on input (by user): Boost 1 -Explicitly disabled TPLs on input (by user or by default): 0 +Explicitly disabled top-level packages on input (by user or by default): 0 +Explicitly disabled packages on input (by user or by default): ThyraCrazyStuff 1 +Explicitly enabled external packages/TPLs on input (by user): Boost 1 +Explicitly disabled external packages/TPLs on input (by user or by default): 0 Enabling subpackages for hard enables of parent packages due to \ Trilinos_ENABLE_=ON ... @@ -17,8 +17,8 @@ Enabling subpackages for hard enables of parent packages due to \ -- Setting subpackage enable Trilinos_ENABLE_ThyraEpetraExt=ON because parent package \ Trilinos_ENABLE_Thyra=ON -Disabling forward required SE packages and optional intra-package support that have a \ - dependency on disabled SE packages Trilinos_ENABLE_=OFF ... +Disabling forward required packages and optional intra-package support that have a \ + dependency on disabled packages Trilinos_ENABLE_=OFF ... -- Setting Thyra_ENABLE_ThyraCrazyStuff=OFF because Thyra has an optional library \ dependence on disabled package ThyraCrazyStuff @@ -33,7 +33,7 @@ Enabling all tests and/or examples that have not been explicitly disabled becaus -- Setting Thyra_ENABLE_TESTS=ON Enabling all required (and optional since Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES=ON) \ - upstream SE packages for current set of enabled packages ... + upstream packages for current set of enabled packages ... -- Setting Trilinos_ENABLE_EpetraExt=ON because ThyraEpetraExt has a required dependence on EpetraExt -- Setting Trilinos_ENABLE_Epetra=ON because ThyraEpetra has a required dependence on Epetra @@ -62,25 +62,25 @@ Enabling all optional package TPL support _ENABLE_ not -- Setting Teuchos_ENABLE_Boost=ON since TPL_ENABLE_Boost=ON -Final set of enabled packages: Teuchos RTOp Epetra Triutils EpetraExt Thyra 6 -Final set of enabled SE packages: Teuchos RTOp Epetra Triutils EpetraExt ThyraCoreLibs \ +Final set of enabled top-level packages: Teuchos RTOp Epetra Triutils EpetraExt Thyra 6 +Final set of enabled packages: Teuchos RTOp Epetra Triutils EpetraExt ThyraCoreLibs \ ThyraGoodStuff ThyraEpetra ThyraEpetraExt Thyra 10 -Final set of non-enabled packages: 0 -Final set of non-enabled SE packages: ThyraCrazyStuff 1 -Final set of enabled TPLs: BLAS LAPACK Boost 3 -Final set of non-enabled TPLs: MPI UMFPACK AMD PETSC 4 +Final set of non-enabled top-level packages: 0 +Final set of non-enabled packages: ThyraCrazyStuff 1 +Final set of enabled external packages/TPLs: BLAS LAPACK Boost 3 +Final set of non-enabled external packages/TPLs: MPI UMFPACK AMD PETSC 4 -Getting information for all enabled TPLs ... +Getting information for all enabled external packages/TPLs ... -Processing enabled TPL: BLAS -Processing enabled TPL: LAPACK -Processing enabled TPL: Boost +Processing enabled external package/TPL: BLAS +Processing enabled external package/TPL: LAPACK +Processing enabled external package/TPL: Boost Configuring individual enabled Trilinos packages ... -Processing enabled package: Teuchos (Libs) -Processing enabled package: RTOp (Libs) -Processing enabled package: Epetra (Libs) -Processing enabled package: Triutils (Libs) -Processing enabled package: EpetraExt (Libs) -Processing enabled package: Thyra (CoreLibs, GoodStuff, Epetra, EpetraExt, Tests, Examples) +Processing enabled top-level package: Teuchos (Libs) +Processing enabled top-level package: RTOp (Libs) +Processing enabled top-level package: Epetra (Libs) +Processing enabled top-level package: Triutils (Libs) +Processing enabled top-level package: EpetraExt (Libs) +Processing enabled top-level package: Thyra (CoreLibs, GoodStuff, Epetra, EpetraExt, Tests, Examples) diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests_EnableBoost_ST_RequiredOnly.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests_EnableBoost_ST_RequiredOnly.txt index b97938e61dd8..3647d4d81d82 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests_EnableBoost_ST_RequiredOnly.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/EnableThyra_EnableTests_EnableBoost_ST_RequiredOnly.txt @@ -1,8 +1,8 @@ -Explicitly enabled SE packages on input (by user): Thyra 1 -Explicitly disabled packages on input (by user or by default): 0 -Explicitly disabled SE packages on input (by user or by default): ThyraCrazyStuff 1 -Explicitly enabled TPLs on input (by user): Boost 1 -Explicitly disabled TPLs on input (by user or by default): 0 +Explicitly enabled packages on input (by user): Thyra 1 +Explicitly disabled top-level packages on input (by user or by default): 0 +Explicitly disabled packages on input (by user or by default): ThyraCrazyStuff 1 +Explicitly enabled external packages/TPLs on input (by user): Boost 1 +Explicitly disabled external packages/TPLs on input (by user or by default): 0 Enabling subpackages for hard enables of parent packages due to \ Trilinos_ENABLE_=ON ... @@ -16,8 +16,8 @@ Enabling subpackages for hard enables of parent packages due to \ -- Setting subpackage enable Trilinos_ENABLE_ThyraEpetraExt=ON because parent package \ Trilinos_ENABLE_Thyra=ON -Disabling forward required SE packages and optional intra-package support that have a \ - dependency on disabled SE packages Trilinos_ENABLE_=OFF ... +Disabling forward required packages and optional intra-package support that have a \ + dependency on disabled packages Trilinos_ENABLE_=OFF ... -- Setting Thyra_ENABLE_ThyraCrazyStuff=OFF because Thyra has an optional library \ dependence on disabled package ThyraCrazyStuff @@ -36,7 +36,7 @@ Enabling all tests and/or examples that have not been explicitly disabled becaus -- Setting Thyra_ENABLE_TESTS=ON -- Setting Thyra_ENABLE_EXAMPLES=ON -Enabling all required upstream SE packages for current set of \ +Enabling all required upstream packages for current set of \ enabled packages (Trilinos_ENABLE_SECONDARY_TESTED_CODE=ON) ... -- Setting Trilinos_ENABLE_EpetraExt=ON because ThyraEpetraExt has a required \ @@ -67,23 +67,23 @@ Enabling all optional package TPL support _ENABLE_ not -- Setting Teuchos_ENABLE_Boost=ON since TPL_ENABLE_Boost=ON -Final set of enabled packages: Teuchos RTOp Epetra EpetraExt Thyra 5 -Final set of enabled SE packages: Teuchos RTOp Epetra EpetraExt ThyraCoreLibs ThyraGoodStuff ThyraEpetra ThyraEpetraExt Thyra 9 -Final set of non-enabled packages: Triutils 1 -Final set of non-enabled SE packages: Triutils ThyraCrazyStuff 2 -Final set of enabled TPLs: BLAS LAPACK Boost 3 -Final set of non-enabled TPLs: MPI UMFPACK AMD PETSC 4 +Final set of enabled top-level packages: Teuchos RTOp Epetra EpetraExt Thyra 5 +Final set of enabled packages: Teuchos RTOp Epetra EpetraExt ThyraCoreLibs ThyraGoodStuff ThyraEpetra ThyraEpetraExt Thyra 9 +Final set of non-enabled top-level packages: Triutils 1 +Final set of non-enabled packages: Triutils ThyraCrazyStuff 2 +Final set of enabled external packages/TPLs: BLAS LAPACK Boost 3 +Final set of non-enabled external packages/TPLs: MPI UMFPACK AMD PETSC 4 -Getting information for all enabled TPLs ... +Getting information for all enabled external packages/TPLs ... -Processing enabled TPL: BLAS -Processing enabled TPL: LAPACK -Processing enabled TPL: Boost +Processing enabled external package/TPL: BLAS +Processing enabled external package/TPL: LAPACK +Processing enabled external package/TPL: Boost Configuring individual enabled Trilinos packages ... -Processing enabled package: Teuchos (Libs) -Processing enabled package: RTOp (Libs) -Processing enabled package: Epetra (Libs) -Processing enabled package: EpetraExt (Libs) -Processing enabled package: Thyra (CoreLibs, GoodStuff, Epetra, EpetraExt, Tests, Examples) +Processing enabled top-level package: Teuchos (Libs) +Processing enabled top-level package: RTOp (Libs) +Processing enabled top-level package: Epetra (Libs) +Processing enabled top-level package: EpetraExt (Libs) +Processing enabled top-level package: Thyra (CoreLibs, GoodStuff, Epetra, EpetraExt, Tests, Examples) diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/ExpectedDependencies.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/ExpectedDependencies.txt index e176a320e287..3d636a3b981a 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/ExpectedDependencies.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/ExpectedDependencies.txt @@ -1,4 +1,19 @@ -Printing package dependencies ... +Package dependencies information: + +-- Trilinos_DEFINED_TPLS: MPI BLAS LAPACK Boost UMFPACK AMD PETSC +-- Trilinos_NUM_DEFINED_TPLS='7' + +-- Trilinos_DEFINED_INTERNAL_TOPLEVEL_PACKAGES: Teuchos RTOp Epetra Triutils EpetraExt Thyra +-- Trilinos_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES='6' + +-- Trilinos_DEFINED_TOPLEVEL_PACKAGES: MPI BLAS LAPACK Boost UMFPACK AMD PETSC Teuchos RTOp Epetra Triutils EpetraExt Thyra +-- Trilinos_NUM_DEFINED_TOPLEVEL_PACKAGES='13' + +-- Trilinos_DEFINED_INTERNAL_PACKAGES: Teuchos RTOp Epetra Triutils EpetraExt ThyraCoreLibs ThyraGoodStuff ThyraCrazyStuff ThyraEpetra ThyraEpetraExt Thyra +-- Trilinos_NUM_DEFINED_INTERNAL_PACKAGES='11' + +-- Trilinos_DEFINED_PACKAGES: MPI BLAS LAPACK Boost UMFPACK AMD PETSC Teuchos RTOp Epetra Triutils EpetraExt ThyraCoreLibs ThyraGoodStuff ThyraCrazyStuff ThyraEpetra ThyraEpetraExt Thyra +-- Trilinos_NUM_DEFINED_PACKAGES='18' -- Teuchos_LIB_REQUIRED_DEP_TPLS: BLAS LAPACK -- Teuchos_LIB_OPTIONAL_DEP_TPLS: Boost MPI @@ -29,44 +44,44 @@ Printing package dependencies ... Dumping direct dependencies for each package ... --- MPI_LIB_ALL_DEPENDENCIES: +-- MPI_LIB_DEFINED_DEPENDENCIES: --- BLAS_LIB_ALL_DEPENDENCIES: +-- BLAS_LIB_DEFINED_DEPENDENCIES: --- LAPACK_LIB_ALL_DEPENDENCIES: +-- LAPACK_LIB_DEFINED_DEPENDENCIES: --- Boost_LIB_ALL_DEPENDENCIES: +-- Boost_LIB_DEFINED_DEPENDENCIES: --- UMFPACK_LIB_ALL_DEPENDENCIES: +-- UMFPACK_LIB_DEFINED_DEPENDENCIES: --- AMD_LIB_ALL_DEPENDENCIES: +-- AMD_LIB_DEFINED_DEPENDENCIES: --- PETSC_LIB_ALL_DEPENDENCIES: +-- PETSC_LIB_DEFINED_DEPENDENCIES: -- Teuchos_LIB_ENABLED_DEPENDENCIES: BLAS LAPACK --- Teuchos_LIB_ALL_DEPENDENCIES: BLAS LAPACK Boost MPI +-- Teuchos_LIB_DEFINED_DEPENDENCIES: BLAS LAPACK Boost MPI -- RTOp_LIB_ENABLED_DEPENDENCIES: Teuchos --- RTOp_LIB_ALL_DEPENDENCIES: Teuchos +-- RTOp_LIB_DEFINED_DEPENDENCIES: Teuchos -- Epetra_LIB_ENABLED_DEPENDENCIES: BLAS LAPACK --- Epetra_LIB_ALL_DEPENDENCIES: BLAS LAPACK MPI +-- Epetra_LIB_DEFINED_DEPENDENCIES: BLAS LAPACK MPI --- Triutils_LIB_ALL_DEPENDENCIES: Epetra +-- Triutils_LIB_DEFINED_DEPENDENCIES: Epetra --- EpetraExt_LIB_ALL_DEPENDENCIES: Teuchos Epetra Triutils UMFPACK AMD PETSC +-- EpetraExt_LIB_DEFINED_DEPENDENCIES: Teuchos Epetra Triutils UMFPACK AMD PETSC -- ThyraCoreLibs_LIB_ENABLED_DEPENDENCIES: Teuchos RTOp --- ThyraCoreLibs_LIB_ALL_DEPENDENCIES: Teuchos RTOp +-- ThyraCoreLibs_LIB_DEFINED_DEPENDENCIES: Teuchos RTOp --- ThyraGoodStuff_LIB_ALL_DEPENDENCIES: ThyraCoreLibs +-- ThyraGoodStuff_LIB_DEFINED_DEPENDENCIES: ThyraCoreLibs --- ThyraCrazyStuff_LIB_ALL_DEPENDENCIES: ThyraGoodStuff +-- ThyraCrazyStuff_LIB_DEFINED_DEPENDENCIES: ThyraGoodStuff -- ThyraEpetra_LIB_ENABLED_DEPENDENCIES: Epetra ThyraCoreLibs --- ThyraEpetra_LIB_ALL_DEPENDENCIES: Epetra ThyraCoreLibs +-- ThyraEpetra_LIB_DEFINED_DEPENDENCIES: Epetra ThyraCoreLibs --- ThyraEpetraExt_LIB_ALL_DEPENDENCIES: ThyraEpetra EpetraExt +-- ThyraEpetraExt_LIB_DEFINED_DEPENDENCIES: ThyraEpetra EpetraExt -- Thyra_LIB_ENABLED_DEPENDENCIES: ThyraCoreLibs ThyraEpetra --- Thyra_LIB_ALL_DEPENDENCIES: ThyraCoreLibs ThyraGoodStuff ThyraCrazyStuff ThyraEpetra ThyraEpetraExt +-- Thyra_LIB_DEFINED_DEPENDENCIES: ThyraCoreLibs ThyraGoodStuff ThyraCrazyStuff ThyraEpetra ThyraEpetraExt diff --git a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/NoEnables.txt b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/NoEnables.txt index c6e81f48c706..970762a37c03 100644 --- a/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/NoEnables.txt +++ b/cmake/tribits/doc/guides/ReducedMockTrilinosOutput/NoEnables.txt @@ -1,19 +1,19 @@ +Explicitly enabled top-level packages on input (by user): 0 Explicitly enabled packages on input (by user): 0 -Explicitly enabled SE packages on input (by user): 0 -Explicitly disabled packages on input (by user or by default): 0 -Explicitly disabled SE packages on input (by user or by default): ThyraCrazyStuff 1 -Explicitly enabled TPLs on input (by user): 0 -Explicitly disabled TPLs on input (by user or by default): 0 +Explicitly disabled top-level packages on input (by user or by default): 0 +Explicitly disabled packages on input (by user or by default): ThyraCrazyStuff 1 +Explicitly enabled external packages/TPLs on input (by user): 0 +Explicitly disabled external packages/TPLs on input (by user or by default): 0 ... +Final set of enabled top-level packages: 0 Final set of enabled packages: 0 -Final set of enabled SE packages: 0 -Final set of non-enabled packages: Teuchos RTOp Epetra Triutils EpetraExt Thyra 6 -Final set of non-enabled SE packages: Teuchos RTOp Epetra Triutils EpetraExt \ +Final set of non-enabled top-level packages: Teuchos RTOp Epetra Triutils EpetraExt Thyra 6 +Final set of non-enabled packages: Teuchos RTOp Epetra Triutils EpetraExt \ ThyraCoreLibs ThyraGoodStuff ThyraCrazyStuff ThyraEpetra ThyraEpetraExt Thyra 11 -Final set of enabled TPLs: 0 -Final set of non-enabled TPLs: MPI BLAS LAPACK Boost UMFPACK AMD PETSC 7 +Final set of enabled external packages/TPLs: 0 +Final set of non-enabled external packages/TPLs: MPI BLAS LAPACK Boost UMFPACK AMD PETSC 7 ... diff --git a/cmake/tribits/doc/guides/TribitsCoreDetailedReference.rst b/cmake/tribits/doc/guides/TribitsCoreDetailedReference.rst index dfd5e4320172..50a99b926381 100644 --- a/cmake/tribits/doc/guides/TribitsCoreDetailedReference.rst +++ b/cmake/tribits/doc/guides/TribitsCoreDetailedReference.rst @@ -280,7 +280,7 @@ These options are described below. **${PROJECT_NAME}_ELEVATE_ST_TO_PT** - If ``${PROJECT_NAME}_ELEVATE_ST_TO_PT`` is set to ``ON``, then all ``ST`` SE + If ``${PROJECT_NAME}_ELEVATE_ST_TO_PT`` is set to ``ON``, then all ``ST`` packages will be elevated to ``PT`` packages. The TriBITS default is obviously ``OFF``. The default can be changed by setting:: @@ -723,14 +723,14 @@ These options are described below. thereby avoid the defect with gfortran described above. If CMake version 3.3 or greater is used, this variable is not required. - NOTE: Currently, a TriBITS SE package must have a direct dependency on a TPL + NOTE: Currently, a TriBITS package must have a direct dependency on a TPL to have ``-isystem`` added to a TPL's include directories on the compile lines for that package. That is, the TPL must be listed in the ``LIB_REQUIRED_TPLS`` or ``LIB_OPTIONAL_TPLS`` arguments passed into the - `tribits_package_define_dependencies()`_ function in the SE package's + `tribits_package_define_dependencies()`_ function in the package's `/cmake/Dependencies.cmake`_ file. In addition, to have ``-isystem`` added to the include directories for a TPL when compiling the - tests for an SE package, it must be listed in the ``TEST_REQUIRED_TPLS`` or + tests for an package, it must be listed in the ``TEST_REQUIRED_TPLS`` or ``TEST_OPTIONAL_TPLS`` arguments. This is a limitation of the TriBITS implementation that will be removed in a future version of TriBITS. diff --git a/cmake/tribits/doc/guides/TribitsDesignConsiderations.rst b/cmake/tribits/doc/guides/TribitsDesignConsiderations.rst index 9510d9c5701c..714e097ec768 100644 --- a/cmake/tribits/doc/guides/TribitsDesignConsiderations.rst +++ b/cmake/tribits/doc/guides/TribitsDesignConsiderations.rst @@ -7,8 +7,8 @@ the `TriBITS Overview`_ document. .. ToDo: Discuss design requirements for TriBITS in more detail. As stated in `TriBITS Dependency Handling Behaviors`_, `No circular -dependencies of any kind are allowed`_. That is, no TriBITS SE package (or -its tests) can declare a dependency on a `downstream`_ SE package, period! To +dependencies of any kind are allowed`_. That is, no TriBITS package (or +its tests) can declare a dependency on a `downstream`_ package, period! To some, this might seem over constraining but adding support for circular dependencies to the TriBITS system would add significant complexity and space/time overhead and is a bad idea from a basic software engineering @@ -17,7 +17,7 @@ Engineering Packaging Principles`_). From a versioning, building, and change-prorogation perspective, any packages involved in a circular dependency would need to be treated as a single software engineering package anyway so TriBITS forces development teams to glob all of this stuff together into a -single `TriBITS SE Package`_ when cycles in software exist. There are +single `TriBITS Package`_ when cycles in software exist. There are numerous wonderful ways to break circular dependencies between packages that are proven and well established in the SE community (for example, see [`Agile Software Development, 2003`_]). diff --git a/cmake/tribits/doc/guides/TribitsGuidesBody.rst b/cmake/tribits/doc/guides/TribitsGuidesBody.rst index 293fcca3ea1e..f6ab1b1b733f 100644 --- a/cmake/tribits/doc/guides/TribitsGuidesBody.rst +++ b/cmake/tribits/doc/guides/TribitsGuidesBody.rst @@ -49,10 +49,10 @@ know a subset of the `TriBITS Macros and Functions`_ defined in the document `TriBITS Users Guide and Reference`_ in addition to the genetic `TriBITS Build Reference `_ document. A slightly more sophisticated TriBITS Project Developer will also add new packages, add new -package dependencies, and define new TPLs. The `TriBITS Users Guide and -Reference`_ should supply everything such a developer needs to know and more. -However, only a smaller part of that document needs to be understood and -accessed by people assuming this role. +package dependencies, and define new external packages/TPLs. The `TriBITS +Users Guide and Reference`_ should supply everything such a developer needs to +know and more. However, only a smaller part of that document needs to be +understood and accessed by people assuming this role. .. jfrye: Add links to parts of document above? @@ -117,11 +117,11 @@ CMake Language Overview and Gotchas TriBITS removes a lot of the boiler plate code needed to write a CMake project. As a result, many people can come into a project that uses TriBITS and quickly start to contribute by adding new source files, adding new -libraries, adding new tests, and even adding new TriBITS packages and TPLs; -all without really having learned anything about CMake. Often one can use existing -example CMake code as a guide and be successful using basic functionality. As long -as nothing out of the ordinary happens, many people can get along just fine in this -mode for a time. +libraries, adding new tests, and even adding new TriBITS packages and external +packages/TPLs; all without really having learned anything about CMake. Often +one can use existing example CMake code as a guide and be successful using +basic functionality. As long as nothing out of the ordinary happens, many +people can get along just fine in this mode for a time. However, we have observed that most mistakes and problems that people run into when using TriBITS are due to lack of basic knowledge of the CMake language. One can find @@ -325,7 +325,7 @@ CMake language behavior with respect to case sensitivity is also strange: to use mixed case with underscores (e.g. ``CMAKE_Fortran_FLAGS``). TriBITS tends to use a similar naming convention where project-level and cache variables have mostly upper-case letters except for parts that are proper - nouns like the project, package or TPL name + nouns like the project, package or external package/TPL name (e.g. ``TribitsExProj_TRIBITS_DIR``, ``TriBITS_SOURCE_DIR``, ``Boost_INCLUDE_DIRS``). Local variables and function/macro parameters can use camelCase or lower_case_with_underscores. @@ -390,7 +390,7 @@ listed below: it is stable. Any of these six OO packaging principles (and other issues) may be considered -when deciding how to partition software into different `TriBITS SE Packages`_. +when deciding how to partition software into different `TriBITS Packages`_. NOTE: The purpose of this TriBITS Developers Guide document is not teach basic software engineering so these various principles will not be expanded on @@ -401,8 +401,6 @@ engineering books out there (see https://bartlettroscoe.github.io/reading-list/# TriBITS Project Structure ========================= -.. jfrye: What does the "F" in framework mean? - TriBITS is a Framework, implemented in CMake, to create CMake projects. As a `Software Framework`_, TriBITS defines the overall structure of a CMake build system for a project and it processes the various project-, repository-, and @@ -412,14 +410,15 @@ calls). The following subsections define the essence of the TriBITS framework in some detail. Later sections cover specific topics and the various sections link to each other. Within this section, the subsection `TriBITS Structural Units`_ defines the basic units `TriBITS Project`_, `TriBITS Repository`_, -`TriBITS Package`_, `TriBITS TPL`_ and other related structural units. The -subsection `Processing of TriBITS Files: Ordering and Details`_ defines -exactly what files TriBITS processes and in what order. It also shows how to -get TriBITS to show exactly what files it is processing to help in debugging -issues. The subsection `Coexisting Projects, Repositories, and Packages`_ -gives some of the rules and constrains for how the different structure units -can co-exist in the same directories. The last two subsections in this -section cover `Standard TriBITS TPLs`_ and `Common TriBITS TPLs`_. +`TriBITS Package`_, `TriBITS External Package/TPL`_ and other related +structural units. The subsection `Processing of TriBITS Files: Ordering and +Details`_ defines exactly what files TriBITS processes and in what order. It +also shows how to get TriBITS to show exactly what files it is processing to +help in debugging issues. The subsection `Coexisting Projects, Repositories, +and Packages`_ gives some of the rules and constrains for how the different +structure units can co-exist in the same directories. The last two +subsections in this section cover `Standard TriBITS TPLs`_ and `Common TriBITS +TPLs`_. TriBITS Structural Units ------------------------ @@ -429,23 +428,25 @@ a single `TriBITS Project`_, one or more `TriBITS Repositories`_ and one or more `TriBITS Packages`_. In addition, a TriBITS Package can be broken up into `TriBITS Subpackages`_. Together, the collection of TriBITS Packages and TriBITS Subpackages are called *TriBITS Software Engineering Packages*, or -`TriBITS SE Packages`_ for short. +`TriBITS Packages`_ for short. First, to better establish the basic nomenclature, the key structural TriBITS units are: -.. _TriBITS Packages: - -* `TriBITS Package`_: A collection of related software that typically includes - one or more source files built into one or more libraries and has associated - tests to help define and protect the functionality provided by the software. - A package also typically defines a single integrated unit of documentation - and testing (see `TriBITS Automated Testing`_). A TriBITS package may or - may not be broken down into multiple subpackages. Examples of TriBITS - packages in `TribitsExampleProject`_ include ``SimpleCXX``, - ``MixedLang`` and ``WithSubpackages``. (Don't confuse a TriBITS - "Package" with a raw CMake "Package". A raw CMake "Package" actually maps to - a `TriBITS TPL`_; see `Why a TriBITS Package is not a CMake Package`_.) +.. _TriBITS Top-Level Package: +.. _TriBITS Top-Level Packages: + +* `TriBITS Top-Level Package`_: A collection of related software that + typically includes one or more source files built into one or more libraries + and has associated tests to help define and protect the functionality + provided by the software. A top-level package (or just "package" if no + ambiguity) also typically defines a single integrated unit of documentation + and testing (see `TriBITS Automated Testing`_). A top-level TriBITS package + may or may not be broken down into multiple subpackages. Examples of TriBITS + packages in `TribitsExampleProject`_ include ``SimpleCXX``, ``MixedLang`` + and ``WithSubpackages``. (Don't confuse a TriBITS "Package" with a raw + CMake "Package". A raw CMake "Package" actually maps to a `TriBITS External + Package/TPL`_; see `Why a TriBITS Package is not a CMake Package`_.) .. _TriBITS Subpackages: @@ -461,34 +462,40 @@ units are: ``WithSubpackages`` depends on its subpackages ``WithSubpackagesA``, ``WithSubpackagesB``, and ``WithSubpackagesC``). -.. _TriBITS SE Package: -.. _TriBITS SE Packages: - -* **TriBITS SE Package**: The combined set of `TriBITS Packages`_ and `TriBITS - Subpackages`_ that constitute the basic *Software Engineering* packages of a - TriBITS project (see `Software Engineering Packaging Principles`_): SE - packages are the basis for setting dependencies in the TriBITS system. For - example, the SE Packages provided by the top-level example package - ``WithSubpackages`` (in order of increasing dependencies) are - ``WithSubpackagesA``, ``WithSubpackagesB``, ``WithSubpackagesC``, and - ``WithSubpackages`` (see `TribitsExampleProject`_). - +.. _TriBITS TPL: .. _TriBITS TPLs: +.. _TriBITS External Package/TPL: +.. _TriBITS External Packages/TPLs: + +* `TriBITS External Package/TPL`_: The specification for a particular external + dependency that is required or can be used in one or more `TriBITS + Packages`_. A modern TriBITS external package/TPL (Third Party Library) is + typically just a small file ``FindTPL.cmake`` that calls + ``find_package()`` and defines the ``::all_libs`` + target. More generally, an external package/TPL can be specificed as a list + list of libraries and/or include directories for header files. Examples of + basic external packages/TPLs include ``BLAS``, ``LAPACK``, and ``Boost``. + +.. _TriBITS Package: +.. _TriBITS Packages: -* `TriBITS TPL`_: The specification for a particular external dependency that - is required or can be used in one or more `TriBITS SE Packages`_. A TPL (a - Third Party Library) typically provides a list of libraries or a list - include directories for header files but can also be manifested in order - ways as well. Examples of basic TPLs include ``BLAS``, ``LAPACK``, and - ``Boost``. +* **TriBITS Package**: The combined set of `TriBITS Top-Level Packages`_, + `TriBITS Subpackages`_, and `TriBITS External Packages/TPLs`_ that + constitute the basic *Software Engineering* packages of a TriBITS project + (see `Software Engineering Packaging Principles`_): Packages are the basis + for setting dependencies in the TriBITS system. For example, the Packages + provided by the example top-level package ``WithSubpackages`` (in order of + increasing dependencies) are ``WithSubpackagesA``, ``WithSubpackagesB``, + ``WithSubpackagesC``, and ``WithSubpackages`` (see + `TribitsExampleProject`_). .. _TriBITS Repositories: * `TriBITS Repository`_: A collection of one or more `TriBITS Packages`_ - specified in a `/PackagesList.cmake`_ file and zero or more TPL - declarations specified in a `/TPLsList.cmake`_ file. - As discussed below, Repositories can include Native Repositories and Version - Control (VC) Repositories. + specified in a `/PackagesList.cmake`_ file and zero or more + external package/TPL declarations specified in a `/TPLsList.cmake`_ + file. As discussed below, Repositories can include Native Repositories and + Version Control (VC) Repositories. .. _TriBITS Projects: @@ -501,8 +508,8 @@ units are: .. _TriBITS Meta-Projects: * **TriBITS Meta-Project**: A `TriBITS Project`_ that contains no native - `TriBITS packages`_ or `TriBITS TPLs`_ but is composed out packages from - other `TriBITS Repositories`_. + `TriBITS packages`_ or `TriBITS external packages/TPLs`_ but is composed out + packages from other `TriBITS Repositories`_. In this document, dependencies are described as either being *upstream* or *downstream/forward* defined as: @@ -584,6 +591,7 @@ For more details on the definition of a TriBITS Project, see: * `TriBITS Project Core Files`_ * `TriBITS Project Core Variables`_ + TriBITS Project Core Files .......................... @@ -623,6 +631,7 @@ These TriBITS Project files are documented in more detail below: * `/cmake/tribits/`_ * `/cmake/ctest/CTestCustom.cmake.in`_ + .. _/ProjectName.cmake: **/ProjectName.cmake**: [Required] At a minimum provides a @@ -630,7 +639,7 @@ These TriBITS Project files are documented in more detail below: the first file that is read by a number of tools in order to get the TriBITS project's name. This file is read first in every context that involves processing the TriBITS project's files, including processes and tools that -just need to build the package and TPL dependency tree (see `Reduced Package +just need to build the package dependency tree (see `Reduced Package Dependency Processing`_). Being this is the first file read in for a TriBITS project and that it is read in first at the top level scope in every context, this is a good file to put in other universal static project options. Note @@ -648,6 +657,7 @@ TriBITS repos and packages are a bit messy and have other issues). For example, the CASL VERA TriBITS meta-project at one point had a very extensive collection of set statements in this file. + .. _/CMakeLists.txt: **/CMakeLists.txt**: [Required] The top-level CMake project file. @@ -708,6 +718,7 @@ For example, the ``VERA/CMakeLists.txt`` file lists as its first line:: cmake_minimum_required(VERSION ${VERA_TRIBITS_CMAKE_MINIMUM_REQUIRED} FATAL_ERROR) + .. _/CTestConfig.cmake: **/CTestConfig.cmake**: [Optional] Specifies the CDash site and @@ -741,6 +752,7 @@ in this file in order to submit to a second CDash site/location. For details, see `Dashboard Submissions`_. This is useful when considering a CDash upgrade and/or implementing new CDash features or tweaks. + .. _/Version.cmake: **/Version.cmake**: If defined, gives the project's version and @@ -775,6 +787,7 @@ project needs to define the variable (perhaps in ``/ProjectName.cmake``) to get right development mode behavior. + .. _/project-checkin-test-config.py: **/project-checkin-test-config.py**: [Optional] Used to define the @@ -793,6 +806,7 @@ data-structure called ``configuration`` which gives some default arguments in ``--default-builds``. For more details, see the section `Pre-push Testing using checkin-test.py`_. + .. _/cmake/NativeRepositoriesList.cmake: **/cmake/NativeRepositoriesList.cmake**: [Deprecated] If present, @@ -820,10 +834,10 @@ If this file ``NativeRepositoriesList.cmake`` does not exist, then TriBITS sets ``${PROJECT_NAME}_NATIVE_REPOSITORIES`` equal to ".", or the base project directory (i.e. ``/.``). In this case, the file ``/PackagesList.cmake`` and ``/TPLsList.cmake`` must -exist. However, if the project has no native packages or TPLs, then these -files can be set up to list no packages or TPLs. This is the case for -meta-projects like VERA that have only extra repositories specified in the -file `/cmake/ExtraRepositoriesList.cmake`_. +exist. However, if the project has no native packages or external +packages/TPLs, then these files can be set up with empty lists. This is the +case for meta-projects like CASL VERA that have only extra repositories +specified in the file `/cmake/ExtraRepositoriesList.cmake`_. .. _/cmake/ExtraRepositoriesList.cmake: @@ -950,8 +964,8 @@ override several of the repository-specific email addresses for its constituent repositories. In general, variables that affect how package dependencies are defined or -affect package and TPL enable/disable logic for *only this particular project* -should be defined in this file. +affect package enable/disable logic for *only this particular project* should +be defined in this file. .. _/cmake/CallbackDefineProjectPackaging.cmake: @@ -1102,8 +1116,8 @@ The following `cache variables` are defined for every TriBITS project: CMake cache variable that if set to ``ON``, then tests for all explicitly enabled packages will be turned on. This has a default value of ``OFF``. - This is used in logic to enable individual SE package tests (see - `_ENABLE_TESTS only enables explicitly enabled SE package + This is used in logic to enable individual package tests (see + `_ENABLE_TESTS only enables explicitly enabled package tests`_). ``${PACKAGE_NAME}_ENABLE_EXAMPLES`` @@ -1158,8 +1172,8 @@ different collections of software that use the TriBITS CMake build and system. In short, a TriBITS Repository: -* Is a named collection of related TriBITS Packages and TPLs (defined in - `/PackagesList.cmake`_ and `/TPLsList.cmake`_ +* Is a named collection of related TriBITS Packages and external packages/TPLs + (defined in `/PackagesList.cmake`_ and `/TPLsList.cmake`_ respectively) * Defines the base source and binary directories for the Repository ``${REPOSITORY_NAME}_SOURCE_DIR`` and ``${REPOSITORY_NAME}_BINARY_DIR``. @@ -1200,6 +1214,7 @@ These TriBITS Repository files are documented in more detail below: * `/cmake/CallbackSetupExtraOptions.cmake`_ * `/cmake/CallbackDefineRepositoryPackaging.cmake`_ + .. _/PackagesList.cmake: **/PackagesList.cmake**: [Required] Provides the list of top-level @@ -1228,20 +1243,22 @@ packages, only extra repositories. .. ToDo: Point to example meta-project. + .. _/TPLsList.cmake: -**/TPLsList.cmake**: [Required] Provides the list of TPLs that are -referenced as TPL dependencies in the repository's SE package's -`/cmake/Dependencies.cmake`_ files (see `TriBITS TPL`_). This -file typically just calls the macro `tribits_repository_define_tpls()`_ to -define the TPLs along with their find modules and other properties. An -example is `ReducedMockTrilinos`_/``TPLsList.cmake`` which shows: +**/TPLsList.cmake**: [Required] Provides the list of external +packages/TPLs that are referenced as dependencies in the repository's +package's `/cmake/Dependencies.cmake`_ files (see `TriBITS +External Package/TPL`_). This file typically just calls the macro +`tribits_repository_define_tpls()`_ to define the TPLs along with their find +modules and other properties. An example is +`ReducedMockTrilinos`_/``TPLsList.cmake`` which shows: .. include:: ../../examples/ReducedMockTrilinos/TPLsList.cmake :literal: -See `TriBITS TPL`_ for details on what gets defined for each TriBITS TPL once -this file is processed. +See `TriBITS External Package/TPL`_ for details on what gets defined for each +TriBITS TPL once this file is processed. It is perfectly fine to specify no TPLs at all for a repository with:: @@ -1251,6 +1268,7 @@ but the macro ``tribits_repository_define_tpls()`` has to be called, even if there are no TPLs. See `tribits_repository_define_tpls()`_ for further details and constraints. + .. _/Copyright.txt: **/Copyright.txt**: [Optional] Gives the default copyright and @@ -1459,19 +1477,24 @@ A TriBITS Package: * Is the fundamental TriBITS structural unit of software partitioning and aggregation. + * Must have a unique package name (``PACKAGE_NAME``) that is globally unique (see `Globally unique TriBITS package names`_). + * Typically defines a set of libraries and/or header files and/or executables and/or tests with CMake build targets for building these for which TriBITS exports the list of include directories, libraries, and targets that are created (along with CMake dependencies). + * Is declared in its parent repository's `/PackagesList.cmake`_ file. -* Declares dependencies on `upstream`_ TPLs and/or other SE packages by just - naming the dependencies in the file - `/cmake/Dependencies.cmake`_. + +* Declares dependencies on `upstream`_ packages by just naming the + dependencies in the file `/cmake/Dependencies.cmake`_. + * Can optionally have subpackages listed in the argument `SUBPACKAGES_DIRS_CLASSIFICATIONS_OPTREQS`_ to the macro call `tribits_package_define_dependencies()`_. + * Is the unit of testing as driven by `tribits_ctest_driver()`_ and displayed on CDash. @@ -1479,7 +1502,7 @@ A TriBITS Package: **WARNING:** As noted above, one must be very careful to pick **globally unique TriBITS package names**. This name must be unique not only within its -defined TriBITS repository but also across all SE packages in all TriBITS +defined TriBITS repository but also across all packages in all TriBITS repositories that ever might be cobbled together into a single TriBITS (meta) project! Choosing a good package name is the single most important decision when it comes to defining a TriBITS package. One must be careful **not** to @@ -1507,7 +1530,7 @@ There are a few simple rules for the location and the contents of the ``/`` directory: * The directory ``/`` must not be a subdirectory of the package - directory of any other SE package (e.g. not ``pkga/pkgb``). + directory of any other package (e.g. not ``pkga/pkgb``). * All of the source files, test files, etc. for the package should be included under ``/``. @@ -1527,7 +1550,7 @@ The following TriBITS Package files are documented in more detail below: .. _/cmake/Dependencies.cmake: **/cmake/Dependencies.cmake**: [Required] Defines the dependencies -for a given TriBITS (SE) package using the macro +for a given TriBITS package using the macro `tribits_package_define_dependencies()`_. This file is processed at the top-level project scope (using an ``include()``) so any local variables set will be seen by the entire project. This file is always processed, including @@ -1552,8 +1575,8 @@ which is: .. include:: ../../examples/TribitsExampleProject/packages/with_subpackages/cmake/Dependencies.cmake :literal: -``WithSubpackages`` defines three subpackages which creates three new SE -packages with names ``WithSubpackagesA``, ``WithSubpackagesB``, and +``WithSubpackages`` defines three subpackages which creates three new packages +with names ``WithSubpackagesA``, ``WithSubpackagesB``, and ``WithSubpackagesC``. if a TriBITS Package or Subpackage has no dependencies, it still has to call @@ -1593,7 +1616,7 @@ The variable ``HAVE_SIMPLECXX___INT64`` is set up in the base file ``SimpleCxx/CMakeLists.txt`` (see `/CMakeLists.txt`_ below). For an explanation of ``HAVE_SIMPLECXX_DEBUG``, see `tribits_add_debug_option()`_. For an explanation of ``HAVE_SIMPLECXX_SIMPLETPL``, see `How to add a new -TriBITS TPL dependency`_. For an explanation of +TriBITS external package/TPL dependency`_. For an explanation of ``@SIMPLECXX_DEPRECATED_DECLARATIONS@``, see `Setting up support for deprecated code handling`_. @@ -1694,12 +1717,12 @@ A packages' core variables are broken down into the following categories: .. _TriBITS Package Local Variables: The following locally scoped **TriBITS Package Local Variables** are defined -when the files for a given TriBITS Package (or any SE package for that matter) +when the files for a given TriBITS Package (or any package for that matter) are being processed: ``PACKAGE_NAME`` - The name of the current TriBITS SE package. This is set automatically by + The name of the current TriBITS package. This is set automatically by TriBITS before the packages' ``CMakeLists.txt`` file is processed. **WARNING:** This name must be globally unique across the entire project (see `Globally unique TriBITS package names`_). @@ -1721,7 +1744,7 @@ are being processed: .. _TriBITS Package Top-Level Local Variables: -Once all of the TriBITS SE package's ``Dependencies.cmake`` files have been +Once all of the TriBITS package's ``Dependencies.cmake`` files have been processed, the following **TriBITS Package Top-Level Local Variables** are defined: @@ -1769,14 +1792,14 @@ defined: ``${PACKAGE_NAME}_TESTGROUP`` - Defines the `SE Package Test Group`_ for the package. This determines in + Defines the `Package Test Group`_ for the package. This determines in what contexts the package is enabled or not for testing-related purposes (see `Nested Layers of TriBITS Project Testing`_) .. _TriBITS Package Cache Variables: -In addition, the following user-settable **TriBITS Package Cache Variables** are -defined before a (SE) Package's ``CMakeLists.txt`` file is processed: +In addition, the following user-settable **TriBITS Package Cache Variables** +are defined before a Package's ``CMakeLists.txt`` file is processed: .. _${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}: @@ -1797,7 +1820,7 @@ defined before a (SE) Package's ``CMakeLists.txt`` file is processed: Set to ``ON`` if support for the optional `upstream`_ dependent package ``${OPTIONAL_DEP_PACKAGE_NAME}`` is enabled in package ``${PACKAGE_NAME}``. Here ``${OPTIONAL_DEP_PACKAGE_NAME}`` corresponds to - each optional upstream SE package listed in the ``LIB_OPTIONAL_PACKAGES`` + each optional upstream package listed in the ``LIB_OPTIONAL_PACKAGES`` and ``TEST_OPTIONAL_PACKAGES`` arguments to the `tribits_package_define_dependencies()`_ macro. @@ -1809,28 +1832,12 @@ defined before a (SE) Package's ``CMakeLists.txt`` file is processed: ``${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_PACKAGE_NAME}`` can be explicitly turned off by the user even through the packages ``${PACKAGE_NAME}`` and ``${OPTIONAL_DEP_PACKAGE_NAME}`` are both enabled at the project level! - See `Support for optional SE package/TPL can be explicitly disabled`_. + See `Support for optional package can be explicitly disabled`_. **NOTE:** This variable will also be set for required dependencies as well to allow for uniform processing such as when looping over the items in - `${PACKAGE_NAME}_LIB_ALL_DEPENDENCIES`_. - - .. _${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_TPL_NAME}: - - ``${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_TPL_NAME}`` - - Set to ``ON`` if support for the optional `upstream`_ dependent TPL - ``${OPTIONAL_DEP_TPL_NAME}`` is enabled in package ``${PACKAGE_NAME}``. - Here ``${OPTIONAL_DEP_TPL_NAME}`` corresponds to each optional upstream - TPL listed in the ``LIB_OPTIONAL_TPLS`` and ``TEST_OPTIONAL_TPLS`` - arguments to the `tribits_package_define_dependencies()`_ macro. - **NOTE:** It is important that the CMake code in the package - ``${PACKAGE_NAME}`` key off of this variable and **not** the global - ``TPL_ENABLE_${OPTIONAL_DEP_TPL_NAME}`` variable because - ``${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_TPL_NAME}`` can be explicitly - turned off by the user even through the package ``${PACKAGE_NAME}`` and - the TPL ``${OPTIONAL_DEP_TPL_NAME}`` are both enabled (see `Support for - optional SE package/TPL can be explicitly disabled`_). + `${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`_ or + `${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES`_. .. _${PACKAGE_NAME}_ENABLE_TESTS: @@ -1852,8 +1859,8 @@ Logic`_. .. _TriBITS Package Optional Dependency Macro Variables: -The following local **TriBITS Package Optional Dependency Macro Variables** are -defined in the top-level project scope before a (SE) Package's +The following local **TriBITS Package Optional Dependency Macro Variables** +are defined in the top-level project scope before a Package's ``CMakeLists.txt`` file is processed: .. _HAVE__: @@ -1880,29 +1887,6 @@ defined in the top-level project scope before a (SE) Package's #cmakedefine HAVE_EPETRAEXT_TRIUTILS - .. _HAVE__: - - ``HAVE__`` - - Set to ``ON`` if support for the optional TPL ``${OPTIONAL_DEP_TPL_NAME}`` - is enabled in downstream package ``${PACKAGE_NAME}`` - (i.e. `${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_TPL_NAME}`_ = ``ON``) and is - set to ``FALSE`` otherwise. Here, ```` and - ```` are the upper-case names for the packages - ``${PACKAGE_NAME}`` and ``${OPTIONAL_DEP_TPL_NAME}``, respectively. For - example, if optional support for the TPL ``Boost`` is enabled in the - package ``Teuchos`` in `ReducedMockTrilinos`_, then - ``Teuchos_ENABLE_Boost=ON`` and ``HAVE_TUECHOS_BOOST=ON``. This variable - is meant to be used in:: - - #cmakedefine HAVE__ - - in configured header files - (e.g. `/cmake/_config.h.in`_). For example, for - the ``Teuchos`` and ``Boost`` example, this would be:: - - #cmakedefine HAVE_TEUCHOS_BOOST - Currently, a Package can refer to its containing Repository and refer to its source and binary directories. This is so that it can refer to repository-level resources (e.g. like the ``Trilinos_version.h`` file for @@ -1928,8 +1912,7 @@ A TriBITS Subpackage: * Is declared in its parent package's `/cmake/Dependencies.cmake`_ file in a call to `tribits_package_define_dependencies()`_ using the argument `SUBPACKAGES_DIRS_CLASSIFICATIONS_OPTREQS`_. -* Defines dependencies on `upstream`_ TPLs and/or other SE packages by just - naming the dependencies in the file +* Defines dependencies on `upstream`_ packages by just naming them in the file `//cmake/Dependencies.cmake`_ using the macro `tribits_package_define_dependencies()`_. * Can **NOT** have its own subpackages defined (only top-level packages can @@ -1996,8 +1979,8 @@ These TriBITS Subpackage files are documented in more detail below: **//cmake/Dependencies.cmake**: [Required] The contents of this file for subpackages are identical as for top-level packages. It just contains a call to the macro `tribits_package_define_dependencies()`_ to -define this SE package's `upstream`_ TPL and SE package dependencies. A -simple example is for the example subpackage ``WithSubpackagesB`` (declared in +define this package's `upstream`_ package dependencies. A simple example is +for the example subpackage ``WithSubpackagesB`` (declared in `with_subpackages/cmake/Dependencies.cmake`_) with the file: `TribitsExampleProject`_/``packages/with_subpackages/b/cmake/Dependencies.cmake`` @@ -2008,19 +1991,18 @@ which is: :literal: What this shows is that subpackages must list their dependencies on each other -(if such dependencies exist) using the full SE package name +(if such dependencies exist) using the full package name ``${PARENT_PACKAGE_NAME}${SUBPACKAGE_NAME}`` or in this case:: 'WithSubpackagesA' = 'WithSubpackages' + 'A' -Note that the parent SE package depends on its subpackages, not the other way -around. For example, the ``WithSubpackages`` parent SE package -automatically depends its SE subpackages -``WithSubpackagesA``, ``WithSubpackagesC``, -and ``WithSubpackagesC``. As such all (direct) dependencies -for a subpackage must be listed in its own ``Dependencies.cmake`` file. For -example, the ``WithSubpackages`` subpackage ``A`` depends on -the ``SimpleCxx`` package and is declared as such as shown in: +Note that the parent package depends on its subpackages, not the other way +around. For example, the ``WithSubpackages`` parent package automatically +depends its subpackages ``WithSubpackagesA``, ``WithSubpackagesC``, and +``WithSubpackagesC``. As such all (direct) dependencies for a subpackage must +be listed in its own ``Dependencies.cmake`` file. For example, the +``WithSubpackages`` subpackage ``A`` depends on the ``SimpleCxx`` package and +is declared as such as shown in: `TribitsExampleProject`_/``packages/with_subpackages/a/cmake/Dependencies.cmake`` @@ -2029,7 +2011,7 @@ which is: .. include:: ../../examples/TribitsExampleProject/packages/with_subpackages/a/cmake/Dependencies.cmake :literal: -What this means is that any TPL or library dependencies listed in the parent +What this means is that any package dependencies listed in the parent package's `/cmake/Dependencies.cmake`_ file are **NOT** dependencies of its subpackages. For example, if `with_subpackages/cmake/Dependencies.cmake`_ where changed to be:: @@ -2041,10 +2023,10 @@ dependencies of its subpackages. For example, if ... ) -then the ``Boost`` TPL would **NOT** be a dependency of the SE package +then the ``Boost`` TPL would **NOT** be a dependency of the package ``WithSubpackagesA`` but instead would be listed as a -dependency of the parent SE package ``WithSubpackages``. (And in this -case, this TPL dependency is pretty worthless since the SE package +dependency of the parent package ``WithSubpackages``. (And in this +case, this TPL dependency is pretty worthless since the package ``WithSubpackages`` does not even define any libraries or tests of its own.) @@ -2130,7 +2112,7 @@ How is a TriBITS Subpackage different from a TriBITS Package? A common question this is natural to ask is how a TriBITS Subpackage is different from a TriBITS Package? They contain the same basic files (i.e. a ``cmake/Dependencies.cmake`` file, a top-level ``CMakeLists.txt`` file, source -files, test files, etc.). They both are included in the list of `TriBITS SE +files, test files, etc.). They both are included in the list of `TriBITS Packages`_ and therefore can both be enabled/disabled by the user or in automatic dependency logic (see `Package Dependencies and Enable/Disable Logic`_). The primary difference is that a subpackage is meant to involve @@ -2141,8 +2123,8 @@ so when the parent package is explicitly enabled or disabled, it is identical to explicitly enabling or disabling all of its subpackages (see `Enable/disable of parent package is enable/disable for subpackages`_). Also, subpackages are tested along with their peer subpackages with the parent -package as part of `TriBITS CTest/CDash Driver`_. This effectively means that if a -build failure is detected in any subpackage, then that will effectively +package as part of `TriBITS CTest/CDash Driver`_. This effectively means that +if a build failure is detected in any subpackage, then that will effectively disable the parent package and all of its other subpackages in downstream testing. This is a type of "all for one and one for all" when it comes to the relationship between the subpackages within a single parent package. These @@ -2150,8 +2132,6 @@ are some of the issues to consider when breaking up software into packages and subpackages that will be mentioned in other sections as well. -.. _TriBITS TPL: - TriBITS External Package/TPL ++++++++++++++++++++++++++++ @@ -2173,15 +2153,16 @@ A *TriBITS External Package/TPL*: The TriBITS external package/TPL mechanism provides a uniform way to find and provide access to any type of external resource no matter how it might be -installed or ways to provide access to it. Using a TriBITS TPL is to be -preferred over using raw CMake ``find_package()`` call because -the TriBITS system guarantees that only a single unique version of an external -package/TPL of the same version will be used all of the downstream packages -that uses it. Also, by defining a TriBITS TPL, automatic enable/disable logic -will be applied as described in `Package Dependencies and Enable/Disable -Logic`_. For example, if a TPL is explicitly disabled, all of the downstream -packages that depend on that TPL will be automatically disabled as well (see -`TPL disable triggers auto-disables of downstream dependencies`_). +installed or ways to provide access to it. Using a TriBITS external +package/TPL is to be preferred over using raw CMake +``find_package()`` call because the TriBITS system guarantees +that only a single unique version of an external package/TPL of the same +version will be used all of the downstream packages that uses it. Also, by +defining a TriBITS TPL, automatic enable/disable logic will be applied as +described in `Package Dependencies and Enable/Disable Logic`_. For example, +if an external package/TPL is explicitly disabled, all of the downstream +packages that depend on it will be automatically disabled as well (see `TPL +disable triggers auto-disables of downstream dependencies`_). .. _Globally unique TriBITS TPL names: @@ -2189,10 +2170,10 @@ packages that depend on that TPL will be automatically disabled as well (see External Package/TPL names** ```` across all TPLs in all TriBITS repositories that ever might be cobbled together into a single TriBITS (meta) project! However, choosing TPL names is usually much easier and less risky -than choosing `Globally unique TriBITS package names`_ because the native TPLs -themselves tend to be uniquely named. For example, the TPL names ``BLAS`` and -``LAPACK`` are well defined in the applied math and computational science -community and are not likely to clash. +than choosing `Globally unique TriBITS package names`_ because widely used +TPLs tend to already be uniquely named. For example, the external package/TPL +names ``BLAS`` and ``LAPACK`` are well defined in the applied math and +computational science community and are not likely to clash. TriBITS External Package/TPL Core Files @@ -2204,9 +2185,10 @@ The core files that define a *TriBITS External Package/TPL* are:: FindTPL.cmake # The name is not fixed (see _FINDMOD) FindTPLDependencies.cmake # [Optional], defines upstream dependencies -Above, ``/`` can be a subdirectory under a TriBITS repository -``/`` (e.g. ``/cmake/tpls/``) or can be under a TriBITS -package directory ``/`` (e.g. ``/cmake/tpls/``). +Above, ``/`` can be a subdirectory under a parent TriBITS +repository ``/`` (e.g. ``/cmake/tpls/``) or can be under a +TriBITS package directory ``/`` +(e.g. ``/cmake/tpls/``). The following TriBITS External Package/TPL files are documented in more detail below: @@ -2325,7 +2307,7 @@ defined TPL ``TPL_NAME`` is assigned the following global non-cache variables: ``${TPL_NAME}_TESTGROUP`` - TPL's `SE Package Test Group`_: This is set using the ``CLASSIFICATION`` + TPL's `Package Test Group`_: This is set using the ``CLASSIFICATION`` field in the call to `tribits_repository_define_tpls()`_. If multiple repos define a given TPL, then the *first* `/TPLsList.cmake`_ file that is processed that declares the TPL ``TPL_NAME`` specifies the @@ -2339,7 +2321,7 @@ defined TPL ``TPL_NAME`` is assigned the following global non-cache variables: TPL if desired by setting ``${TPL_NAME}_TESTGROUP`` before the first `/TPLsList.cmake`_ file gets processed. - .. _+${TPL_NAME}_TPLS_LIST_FILE: + .. _${TPL_NAME}_TPLS_LIST_FILE: ``${TPL_NAME}_TPLS_LIST_FILE`` @@ -2456,7 +2438,7 @@ proceeds through the call to `tribits_project()`_. | * For each ```` in all subpackages for this package: | * ``include(`` `//cmake/Dependencies.cmake`_ ``)`` | - Sets all subpackage-specific options -| 10) Adjust SE package and TPLs enables and disables +| 10) Adjust package and TPLs enables and disables | (see `Package Dependencies and Enable/Disable Logic`_) | 11) `Probe and set up the environment`_ (finds MPI, compilers, etc.) | (see `TriBITS Environment Probing and Setup`_) @@ -2678,22 +2660,24 @@ The primary use case for collapsing a project, repository, and package into a single base source directory would be to support the stand-alone build of a TriBITS package as its own entity that uses an independent installation of the TriBITS (or a minimal snapshot of TriBITS). If a given TriBITS package has no -required `upstream`_ TriBITS package dependencies and minimal TPL dependencies -(or only uses `Standard TriBITS TPLs`_ or `Common TriBITS TPLs`_ already -defined in the ``tribits/core/std_tpls/`` or ``tribits/common_tpls/`` -directories), then creating a stand-alone project build of a single TriBITS -package requires fairly little extra overhead or duplication. +required `upstream`_ TriBITS package dependencies and minimal external +package/TPL dependencies (or only uses `Standard TriBITS TPLs`_ or `Common +TriBITS TPLs`_ already defined in the ``tribits/core/std_tpls/`` or +``tribits/common_tpls/`` directories), then creating a stand-alone project +build of a single TriBITS package requires fairly little extra overhead or +duplication. Standard and Common TPLs ------------------------ -While a TriBITS Repository can define their own TPLs and their own TPL find -modules (see `TriBITS TPL`_), the TriBITS source tree contains the find -modules for a few different standard TPLs and common TPLs. `Standard TriBITS -TPLs`_ are integral to the TriBITS system itself while `Common TriBITS TPLs`_ -are TPL that are used in several different TriBITS Repositories and are -contained in TriBITS for convenience and uniformity. +While a TriBITS Repository can define their own external packages/TPLs and +their own TPL find modules (see `TriBITS External Package/TPL`_), the TriBITS +source tree contains TriBITS find modules for a few different standard TPLs +and common TPLs. `Standard TriBITS TPLs`_ are integral to the TriBITS system +itself while `Common TriBITS TPLs`_ are TPL that are used in several different +TriBITS Repositories and are contained in TriBITS for convenience and +uniformity. Standard TriBITS TPLs @@ -2866,7 +2850,7 @@ This simple project shows how what is listed in files: * `/cmake/Dependencies.cmake`_, and * `//cmake/Dependencies.cmake`_ -are used to specify the packages and SE packages in a TriBITS project and +are used to specify the packages and packages in a TriBITS project and repository. More details about the contents of the ``Dependencies.cmake`` files is described in the section `Package Dependencies and Enable/Disable Logic`_. @@ -2948,7 +2932,7 @@ explained in `TriBITS Package Core Files`_, the files must exist for every package directory listed in `/PackagesList.cmake`_ and we see these files under in the directory ``packages/simple_cxx/``. The package ``SimpleCxx`` does not have any -`upstream`_ SE package dependencies. +`upstream`_ package dependencies. Now consider the example top-level package ``WithSubpackages`` which, as the name suggests, is broken down into subpackages. The @@ -2964,7 +2948,7 @@ with contents: references the three subpackages with sub-directories ```` = ``A``, ``B``, and ``C`` under the parent package directory ``packages/package_with_packages/`` which are shown in `TribitsExampleProject -Files and Directories`_. This gives another set of three SE packages +Files and Directories`_. This gives another set of three packages ``WithSubpackagesA``, ``WithSubpackagesB``, and ``WithSubpackagesC``. Combining `` = packages/package_with_packages`` and ```` for each subpackage gives @@ -2974,19 +2958,19 @@ the subpackage directories:: TribitsExampleProject/packages/with_subpackages/b/ TribitsExampleProject/packages/with_subpackages/c/ -Together with the top-level parent SE package ``WithSubpackages`` -itself, this top-level package provides four `TriBITS SE Packages`_ giving the -final list of SE packages provided by this TriBITS repo as:: +Together with the top-level parent package ``WithSubpackages`` +itself, this top-level package provides four `TriBITS Packages`_ giving the +final list of packages provided by this TriBITS repo as:: SimpleCxx MixedLang WithSubpackagesA WithSubpackagesB WithSubpackagesC \ WithSubpackages WrapExternal 7 -The above list of SE packages is printed (with the number of packages printed +The above list of packages is printed (with the number of packages printed at the end) by TriBITS to the ``cmake`` stdout on the line starting with -``"Final set of non-enabled SE packages:"`` when no packages are enabled (see +``"Final set of non-enabled packages:"`` when no packages are enabled (see `Selecting the list of packages to enable`_). (Note that TriBITS does not put in line-brakes with continuation characters ``"\"`` as shown above.) TriBITS -defines enable/disable cache variables for each of these defined SE packages +defines enable/disable cache variables for each of these defined packages like ``TribitsExProj_ENABLE_SimpleCxx`` and ``TribitsExProj_ENABLE_WithSubpackagesA``, and defines all the variables listed in `TriBITS Package Cache Variables`_ that are settable @@ -3049,7 +3033,8 @@ TriBITS repositories like: optional `upstream`_ packages (see `Multi-Repository Support`_). * ``extraTrilinosRepo``: Just a typical extra repo with add-on packages and - TPLs that depends on a few upstream ``MockTrilinos`` packages. + external packages/TPLs that depends on a few upstream ``MockTrilinos`` + packages. New test extra repositories are added when new types of tests are needed that would require new package and TPL dependency structures since existing @@ -3087,7 +3072,7 @@ It is a scaled-down version of the `MockTrilinos`_ test project with just a handful of packages and some modified dependencies. Its primary purpose for this example project is to be used for examples in the section `Package Dependencies and Enable/Disable Logic`_ and to test a few features of the -TriBITS system not tested in other tests. +TriBITS system not covered in other tests. The list of packages in:: @@ -3180,27 +3165,27 @@ because only pre-built binary libraries and tools are available to install. This section is organized and broken-down as follows. First, the subsection `Example ReducedMockTrilinos Project Dependency Structure`_ presents the `ReducedMockTrilinos`_ example project, describes its dependency structure, -and uses it to begin to describe how TriBITS sets up and manages package and -TPL dependencies. The packages in this `ReducedMockTrilinos`_ example project -are used in the following subsections so one will be constantly referred back -to this subsection. The following subsection `TriBITS Dependency Handling +and uses it to begin to describe how TriBITS sets up and manages package +dependencies. The packages in this `ReducedMockTrilinos`_ example project are +used in the following subsections so one will be constantly referred back to +this subsection. The following subsection `TriBITS Dependency Handling Behaviors`_ defines and describes the nitty-gritty details of the TriBITS -package and TPL dependency structure and the algorithms that manipulate the -various package, TPL, and test enables and disables. Specific examples for -the TriBITS dependency handling algorithms are given in the subsection -`Example Enable/Disable Use Cases`_. Finally, the subsection +package dependency structure and the algorithms that manipulate the various +package and test enables and disables. Specific examples for the TriBITS +dependency handling algorithms are given in the subsection `Example +Enable/Disable Use Cases`_. Finally, the subsection `PackageDependencies.xml`_ describes the standard XML output data-structure that gets created by TriBITS that defines a project's package -and TPL dependencies. +dependencies. Example ReducedMockTrilinos Project Dependency Structure -------------------------------------------------------- -To demonstrate the TriBITS package and TPL dependency handling system, the -small simple `ReducedMockTrilinos`_ project is used. The list of packages for -this project is defined in the file ``ReducedMockTrilinos/PackagesList.cmake`` -(see `/PackagesList.cmake`_) which contents: +To demonstrate the TriBITS package dependency handling system, the small +simple `ReducedMockTrilinos`_ project is used. The list of packages for this +project is defined in the file ``ReducedMockTrilinos/PackagesList.cmake`` (see +`/PackagesList.cmake`_) which contents: .. include:: ../../examples/ReducedMockTrilinos/PackagesList.cmake :literal: @@ -3218,30 +3203,30 @@ This gives the full list of top-level TriBITS packages:: Teuchos RTOp Epetra Triutils EpetraExt Thyra Adding in the subpackages defined in the top-level ``Thyra`` package, the full -set of `TriBITS SE Packages`_ for this project is:: +set of `TriBITS Packages`_ for this project is:: Teuchos RTOp Epetra Triutils EpetraExt ThyraCoreLibs ThyraGoodStuff \ ThyraCrazyStuff ThyraEpetra ThyraEpetraExt Thyra -Note that one can see this full list of top-level packages and SE packages in +Note that one can see this full list of top-level packages and packages in the ``cmake`` configure output lines starting with:: + Final set of non-enabled top-level packages: Final set of non-enabled packages: - Final set of non-enabled SE packages: respectively, when configuring with no package enables as shown in the example `Default configure with no packages enabled on input`_. -The list of `TriBITS TPLs`_ for this example project given in the file -``ReducedMockTrilinos/TPLsList.cmake`` (see `/TPLsList.cmake`_) which -is: +The list of `TriBITS External Packages/TPLs`_ for this example project given +in the file ``ReducedMockTrilinos/TPLsList.cmake`` (see +`/TPLsList.cmake`_) which is: .. include:: ../../examples/ReducedMockTrilinos/TPLsList.cmake :literal: -Take note of the `SE Package Test Group`_ (i.e. `PT`_, `ST`_, or `EX`_) -assigned to each SE package and TPL as it plays a significant role in how the -TriBITS dependency system handles enables and disables. +Take note of the `Package Test Group`_ (i.e. `PT`_, `ST`_, or `EX`_) assigned +to each package as it plays a significant role in how the TriBITS dependency +system handles enables and disables. The dependency structure of this simple TriBITS project is shown below in `ReducedMockTrilinos Dependencies`_. @@ -3256,7 +3241,7 @@ The dependency structure of this simple TriBITS project is shown below in The above dependency structure printout is produced by configuring with ``${PROJECT_NAME}_DUMP_PACKAGE_DEPENDENCIES=ON`` (which also results in more dependency information than what is shown above, e.g. like computed forward -package dependencies). Note that the top-level SE package ``Thyra`` is shown +package dependencies). Note that the top-level package ``Thyra`` is shown to depend on its subpackages (not the other way around). (Many people are confused about the nature of the dependencies between packages and subpackages. See `//cmake/Dependencies.cmake`_ for more @@ -3264,15 +3249,15 @@ discussion.) .. ToDo: Show diagram with this dependency structure. -A number of user-settable CMake cache variables determine what SE packages -(and TPLs) and what tests and examples get enabled. These cache variables are -described in `Selecting the list of packages to enable`_ and are described -below. Also, the assigned `SE Package Test Group`_ (i.e. `PT`_, `ST`_, and -`EX`_) also affects what packages get enabled or disabled. +A number of user-settable CMake cache variables determine what packages and +what tests and examples get enabled. These cache variables are described in +`Selecting the list of packages to enable`_ and are described below. Also, +the assigned `Package Test Group`_ (i.e. `PT`_, `ST`_, and `EX`_) also affects +what packages get enabled or disabled. -Any of these SE packages can be enabled or disabled with +Any of these packages can be enabled or disabled with ``${PROJECT_NAME}_ENABLE_=(ON|OFF)`` (the default enable is -typically empty ``""``, see `PT/ST SE packages given default unset +typically empty ``""``, see `PT/ST packages given default unset enable/disable state`_). For ``ReducedMockTrilinos``, this gives the enable/disable cache variables (with the initial default values):: @@ -3287,7 +3272,7 @@ enable/disable cache variables (with the initial default values):: Trilinos_ENABLE_ThyraEpetra="" Trilinos_ENABLE_ThyraEpetraExt="" -Every TriBITS SE package is assumed to have tests and/or examples so TriBITS +Every TriBITS package is assumed to have tests and/or examples so TriBITS defines the following cache variables as well (with the initial default values):: @@ -3303,7 +3288,7 @@ values):: Thyra_ENABLE_TESTS="" NOTE: TriBITS only sets the variables ``_ENABLE_TESTS`` into -the cache if the SE package ```` becomes enabled at some +the cache if the package ```` becomes enabled at some point. This cuts down the clutter in the CMake cache for large projects with lots of packages where the user only enables a subset of the packages. @@ -3311,9 +3296,10 @@ NOTE: TriBITS also defines the cache variables ``_ENABLE_EXAMPLES`` for each enabled TriBITS package which is handled the same way as the ``_ENABLE_TEST`` variables. -Also, every defined TPL is given its own ``TPL_ENABLE_`` -enable/disable cache variable. For the TPLs in ``ReducedMockTrilinos``, this -gives the enable/disable cache variables (with default values):: +Also, every defined external package/TPL is given its own +``TPL_ENABLE_`` enable/disable cache variable. For the TPLs in +``ReducedMockTrilinos``, this gives the enable/disable cache variables (with +default values):: TPL_ENABLE_MPI="" TPL_ENABLE_BLAS="" @@ -3323,10 +3309,10 @@ gives the enable/disable cache variables (with default values):: TPL_ENABLE_AMD="" TPL_ENABLE_PETSC="" -In addition, for every optional SE package and TPL dependency, TriBITS defines -a cache variable ``_ENABLE_``. For the -optional dependencies shown in `ReducedMockTrilinos Dependencies`_, that gives -the additional cache variables (with default values):: +In addition, for every optional package dependency, TriBITS defines a cache +variable ``_ENABLE_``. For the optional +dependencies shown in `ReducedMockTrilinos Dependencies`_, that gives the +additional cache variables (with default values):: Teuchos_ENABLE_Boost="" Teuchos_ENABLE_MPI="" @@ -3363,31 +3349,31 @@ system are described. Examples refer to the `Example ReducedMockTrilinos Project Dependency Structure`_. More detailed examples of these behaviors are given in the section `Example Enable/Disable Use Cases`_. -In brief, the rules/behaviors of the TriBITS package and TPL dependency -management system are: +In brief, the rules/behaviors of the TriBITS package dependency management +system are: 0) `No circular dependencies of any kind are allowed`_ -1) `PT/ST SE packages given default unset enable/disable state`_ -2) `EX SE packages disabled by default`_ -3) `SE package enable triggers auto-enables of upstream dependencies`_ -4) `SE package disable triggers auto-disables of downstream dependencies`_ +1) `PT/ST packages given default unset enable/disable state`_ +2) `EX packages disabled by default`_ +3) `Package enable triggers auto-enables of upstream dependencies`_ +4) `Package disable triggers auto-disables of downstream dependencies`_ 5) `PT/ST TPLs given default unset enable/disable state`_ 6) `EX TPLs given default unset enable/disable state`_ -7) `Required TPLs are auto-enabled for enabled SE packages`_ +7) `Required TPLs are auto-enabled for enabled packages`_ 8) `Optional TPLs only enabled explicitly by the user`_ 9) `TPL disable triggers auto-disables of downstream dependencies`_ 10) `Disables trump enables where there is a conflict`_ 11) `Enable/disable of parent package is enable/disable for subpackages`_ 12) `Enable/disable of parent package tests/examples is enable/disable for subpackages tests/examples`_ 13) `Subpackage enable does not auto-enable the parent package`_ -14) `Support for optional SE package/TPL is enabled by default`_ -15) `Support for optional SE package/TPL can be explicitly disabled`_ -16) `Explicit enable of optional SE package/TPL support auto-enables SE package/TPL`_ -17) `ST SE packages only auto-enabled if ST code is enabled`_ +14) `Support for optional package/TPL is enabled by default`_ +15) `Support for optional package can be explicitly disabled`_ +16) `Explicit enable of optional package/TPL support auto-enables package/TPL`_ +17) `ST packages only auto-enabled if ST code is enabled`_ 18) `_ENABLE_ALL_FORWARD_DEP_PACKAGES enables downstream packages/tests`_ -19) `_ENABLE_ALL_PACKAGES enables all PT (cond. ST) SE packages`_ -20) `_ENABLE_TESTS only enables explicitly enabled SE package tests`_ -21) `If no SE packages are enabled, nothing will get built`_ +19) `_ENABLE_ALL_PACKAGES enables all PT (cond. ST) packages`_ +20) `_ENABLE_TESTS only enables explicitly enabled package tests`_ +21) `If no packages are enabled, nothing will get built`_ 22) `TriBITS prints all enables and disables to stdout`_ 23) `TriBITS auto-enables/disables done using non-cache local variables`_ @@ -3396,8 +3382,8 @@ In more detail, these rules/behaviors are: .. _No circular dependencies of any kind are allowed: 0) **No circular dependencies of any kind are allowed**: The zeroth rule of - the TriBITS dependency management system is that no TriBITS SE package (or - its tests) can declare a dependency on a `downstream`_ SE package, period! + the TriBITS dependency management system is that no TriBITS package (or + its tests) can declare a dependency on a `downstream`_ package, period! This is one of the most basic `Software Engineering Packaging Principles`_ stated as the *ADP (Acyclic Dependencies Principle)*, i.e. "Allow no cycles in the package dependency graph". By default, the TriBITS system will @@ -3405,11 +3391,11 @@ In more detail, these rules/behaviors are: found. For a more detailed discussion of circular package dependencies, see `Design Considerations for TriBITS`_. -.. _PT/ST SE packages given default unset enable/disable state: +.. _PT/ST packages given default unset enable/disable state: -1) **PT/ST SE packages given default unset enable/disable state**: An SE - package ```` with testing group ``PT`` or ``ST`` is given - an **unset enable/disable state by default** +1) **PT/ST packages given default unset enable/disable state**: A package + ```` with testing group ``PT`` or ``ST`` is given an + **unset enable/disable state by default** (i.e. ``${PROJECT_NAME}_ENABLE_=""``). For example, the ``PT`` package ``Teuchos`` is not enabled or disabled by default and is given the initial value ``Trilinos_ENABLE_Teuchos=""``. For an example, @@ -3421,48 +3407,48 @@ In more detail, these rules/behaviors are: these variables, then on future configures it will be defined but have the value of empty "". -.. _EX SE packages disabled by default: +.. _EX packages disabled by default: -2) **EX SE packages disabled by default**: An SE package ```` +2) **EX packages disabled by default**: An package ```` with testing group ``EX`` is **disabled by default** (i.e. ``${PROJECT_NAME}_ENABLE_=OFF``). For an example, see `Default configure with no packages enabled on input`_. This results - in all required `downstream`_ SE packages to be disabled by default. + in all required `downstream`_ packages to be disabled by default. However, the user can explicitly set ``${PROJECT_NAME}_ENABLE_=ON`` for an ``EX`` package and it will be enabled (unless one of its required dependencies are not enabled for some reason). In this case, the cache variable is given the cache value of ``OFF``. -.. _SE package enable triggers auto-enables of upstream dependencies: +.. _Package enable triggers auto-enables of upstream dependencies: -3) **SE package enable triggers auto-enables of upstream dependencies**: Any - SE package ```` can be explicitly **enabled** by the user +3) **Package enable triggers auto-enables of upstream dependencies**: Any + package ```` can be explicitly **enabled** by the user by setting the cache variable ``${PROJECT_NAME}_ENABLE_=ON`` - (e.g. ``Trilinos_ENABLE_EpetraExt=ON``). When an SE package is enabled in + (e.g. ``Trilinos_ENABLE_EpetraExt=ON``). When an package is enabled in this way, the TriBITS system will try to enable all of the required - upstream SE packages and TPLs defined by the package (specified in its - ``Dependencies.cmake`` file). If an enabled SE package can't be enabled + upstream packages and TPLs defined by the package (specified in its + ``Dependencies.cmake`` file). If an enabled package can't be enabled and has to be disabled, either a warning is printed or processing will stop with an error (depending on the value of ``${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES``, see `Disables trump enables where there is a conflict`_). In addition, if ``${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES=ON``, then TriBITS will try - to enable all of the specified optional `PT`_ SE packages as well (and also - optional upstream `ST`_ SE packages if + to enable all of the specified optional `PT`_ packages as well (and also + optional upstream `ST`_ packages if ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=ON``). For an example, see `Explicit enable of a package, its tests, an optional TPL, with ST enabled`_. -.. _SE package disable triggers auto-disables of downstream dependencies: +.. _Package disable triggers auto-disables of downstream dependencies: -4) **SE package disable triggers auto-disables of downstream dependencies**: - Any SE package ```` can be explicitly **disabled** by the +4) **Package disable triggers auto-disables of downstream dependencies**: + Any package ```` can be explicitly **disabled** by the user by setting the cache variable ``${PROJECT_NAME}_ENABLE_=OFF`` - (e.g. ``Trilinos_ENABLE_Teuchos=OFF``). When an SE package is explicitly - disabled, it will result in the disable of all `downstream`_ SE packages + (e.g. ``Trilinos_ENABLE_Teuchos=OFF``). When an package is explicitly + disabled, it will result in the disable of all `downstream`_ packages that have required dependency on it. It will also disable optional support for the disabled packages in downstream packages that list it as an optional dependency. For an example, see `Explicit disable of a package`_. @@ -3484,22 +3470,22 @@ In more detail, these rules/behaviors are: enable/disable state by default** (i.e. ``TPL_ENABLE_=""``, same as for ``PT`` and ``EX`` TPLs). For an example, see `Default configure with no packages enabled on input`_. This is different behavior - than for ``EX`` SE packages described above which provides an initial hard + than for ``EX`` packages described above which provides an initial hard disable. However, since TriBITS will never automatically enable an optional TPL (see `Optional TPLs only enabled explicitly by the user`_) and - since only `downstream`_ ``EX`` SE packages are allowed to have a required + since only `downstream`_ ``EX`` packages are allowed to have a required dependencies on an ``EX`` TPL, there is no need to set the default enable - for an ``EX`` TPL to ``OFF``. If an ``EX`` SE package has a required - dependency on an ``EX`` TPL, just enabling the ``EX`` SE package should + for an ``EX`` TPL to ``OFF``. If an ``EX`` package has a required + dependency on an ``EX`` TPL, just enabling the ``EX`` package should automatically enable the ``EX`` TPL as described in `Required TPLs are - auto-enabled for enabled SE packages`_. + auto-enabled for enabled packages`_. -.. _Required TPLs are auto-enabled for enabled SE packages: +.. _Required TPLs are auto-enabled for enabled packages: -7) **Required TPLs are auto-enabled for enabled SE packages**: All TPLs listed - as required TPL dependencies for the final set of enabled SE packages are +7) **Required TPLs are auto-enabled for enabled packages**: All TPLs listed + as required TPL dependencies for the final set of enabled packages are **set to enabled** (i.e. ``TPL_ENABLE_=ON``), unless the - listed TPLs are already explicit disabled (in which case the SE package + listed TPLs are already explicit disabled (in which case the package would be disabled or an error would occur, see `Disables trump enables where there is a conflict`_). For example, if the ``Teuchos`` package is enabled, then that will trigger the enable of its required TPLs ``BLAS`` @@ -3523,13 +3509,13 @@ In more detail, these rules/behaviors are: 9) **TPL disable triggers auto-disables of downstream dependencies**: Any TPLs that are explicitly disabled (i.e. ``TPL_ENABLE_=OFF``) will - result in the disable of all `downstream`_ dependent SE packages that have - a required dependency on the TPL. For example, if the user sets - ``TPL_ENABLE_LAPACK=OFF``, then this will result in the disable of SE - packages ``Teuchos`` and ``Epetra``, and all of the required SE packages - downstream from them. Also, the explicitly disabled TPL will result in the - disable of optional support in all downstream SE packages. For example, if - the user sets ``TPL_ENABLE_MPI=OFF``, then TriBITS will automatically set + result in the disable of all `downstream`_ dependent packages that have a + required dependency on the TPL. For example, if the user sets + ``TPL_ENABLE_LAPACK=OFF``, then this will result in the disable of packages + ``Teuchos`` and ``Epetra``, and all of the required packages downstream + from them. Also, the explicitly disabled TPL will result in the disable of + optional support in all downstream packages. For example, if the user sets + ``TPL_ENABLE_MPI=OFF``, then TriBITS will automatically set ``Teuchos_ENABLE_MPI=OFF`` and ``Epetra_ENABLE_MPI=OFF``. For examples, see `Explicit disable of an optional TPL`_ and `Explicit disable of a required TPL`_. @@ -3558,7 +3544,7 @@ In more detail, these rules/behaviors are: * If ``${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=OFF``, then TriBITS will generate a detailed error message printed to ``cmake`` stdout and then abort processing. In the above example, TriBITS will - report that ``RTOp`` is enabled but the required SE package ``Teuchos`` + report that ``RTOp`` is enabled but the required package ``Teuchos`` is disabled and therefore ``RTOp`` can't be enabled and processing must stop. @@ -3580,7 +3566,7 @@ In more detail, these rules/behaviors are: Trilinos_ENABLE_ThyraEpetraExt=ON # Only if enabling ST code! (Note that ``Trilinos_ENABLE_ThyraCrazyStuff`` is **not** set to ``ON`` - because it is already set to ``OFF`` by default, see `EX SE packages + because it is already set to ``OFF`` by default, see `EX packages disabled by default`_.) Likewise, explicitly setting ``Trilinos_ENABLE_Thyra=OFF`` is equivalent to explicitly setting all of the ``Thyra`` subpackages to ``OFF`` at the outset. For a ``PT`` example, @@ -3605,13 +3591,13 @@ In more detail, these rules/behaviors are: .. _Subpackage enable does not auto-enable the parent package: 13) **Subpackage enable does not auto-enable the parent package**: Enabling an - SE package that is a subpackage does **not** automatically enable the + package that is a subpackage does **not** automatically enable the parent package (except for at the very end, mostly just for show). For - example, enabling the SE package ``ThyraEpetra`` does not result in enable + example, enabling the package ``ThyraEpetra`` does not result in enable of the parent ``Thyra`` package, (except when ``${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES=ON`` for course). For an example, see `Explicit enable of a subpackage`_. This means that if a - `downstream`_ package declares a dependency on the SE package + `downstream`_ package declares a dependency on the package ``ThyraEpetra``, but not the parent package ``Thyra``, then the ``Thyra`` package (and its other subpackages and their dependencies) will not get auto-enabled. Also note that enabling a subset of the required @@ -3625,12 +3611,12 @@ In more detail, these rules/behaviors are: does imply that all of the required subpackages will be enabled, only that the parent package will be processed.) -.. _Support for optional SE package/TPL is enabled by default: +.. _Support for optional package/TPL is enabled by default: -14) **Support for optional SE package/TPL is enabled by default**: For an SE - package ```` with an optional dependency on an - `upstream`_ SE package or TPL ````, TriBITS - will automatically set the intra-enable variable +14) **Support for optional package/TPL is enabled by default**: For an package + ```` with an optional dependency on an `upstream`_ + package or TPL ````, TriBITS will + automatically set the intra-enable variable ``_ENABLE_=ON`` if ```` and ```` are **both enabled**. For example, if the packages ``Triutils`` and ``EpetraExt`` @@ -3642,16 +3628,16 @@ In more detail, these rules/behaviors are: behavior. See the full context for these examples in `Explicit enable of a package, its tests, an optional TPL, with ST enabled`_. -.. _Support for optional SE package/TPL can be explicitly disabled: +.. _Support for optional package can be explicitly disabled: -15) **Support for optional SE package/TPL can be explicitly disabled:** Even +15) **Support for optional package can be explicitly disabled:** Even though TriBITS will automatically set ``_ENABLE_=ON`` by default if ```` and ```` are both enabled at the project level (as described above), the user can explicitly set ``_ENABLE_=OFF`` which - will turn off optional package-level support for the upstream SE package - or TPL ```` in the downstream SE package + will turn off optional package-level support for the upstream package + or TPL ```` in the downstream package ````. For example, the user can enable ``EpetraExt`` and ``Triutils`` at the project level, but set ``EpetraExt_ENABLE_Triutils=OFF`` which will turn off package-level @@ -3662,13 +3648,13 @@ In more detail, these rules/behaviors are: an optional package dependency`_ and `Explicit disable of an optional TPL dependency`_. -.. _Explicit enable of optional SE package/TPL support auto-enables SE package/TPL: +.. _Explicit enable of optional package/TPL support auto-enables package/TPL: -16) **Explicit enable of optional SE package/TPL support auto-enables SE - package/TPL**: If the user explicitly enables the TriBITS SE package +16) **Explicit enable of optional package/TPL support auto-enables + package/TPL**: If the user explicitly enables the TriBITS package ```` and explicitly sets ``_ENABLE_=ON`` on input, - then that will automatically enable the SE package or TPL + then that will automatically enable the package or TPL ```` (and all of its upstream dependencies accordingly). For example, if the user sets ``Trilinos_ENABLE_EpetraExt=ON`` and ``EpetraExt_ENABLE_Triutils=ON``, @@ -3676,22 +3662,22 @@ In more detail, these rules/behaviors are: ``Trilinos_ENABLE_Triutils=ON`` regardless of the value of ``${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES`` or ``${PROJECT_NAME}_SECONDARY_TESTED_CODE``. This true even if the optional - SE package or TPL is ``EX``. For example, setting + package or TPL is ``EX``. For example, setting ``Thyra_ENABLE_ThyraCrazyStuff=ON`` will result in the enabling of the ``EX`` package ``ThyraCrazyStuff``. However, always remember that `Disables trump enables where there is a conflict`_. For example, see `Explicit enable of an optional package dependency`_. -.. _ST SE packages only auto-enabled if ST code is enabled: +.. _ST packages only auto-enabled if ST code is enabled: -17) **ST SE packages only auto-enabled if ST code is enabled**: TriBITS will - only enable an optional ``ST`` SE package when +17) **ST packages only auto-enabled if ST code is enabled**: TriBITS will + only enable an optional ``ST`` package when ``${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES=ON`` if ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=ON`` is also set. Otherwise, when - an optional ``ST`` `upstream`_ dependent SE package is not enabled due to + an optional ``ST`` `upstream`_ dependent package is not enabled due to ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=OFF``, then a one-line warning is printed to stdout. For example, if the ``EpetraExt`` package is enabled - but ``ST`` code is not enabled, then the optional SE package ``Triutils`` + but ``ST`` code is not enabled, then the optional package ``Triutils`` will not be enabled (for an example, see `Explicit enable of a package and its tests`_). However, when ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=ON`` and ``EpetraExt`` is enabled, then ``Triutils`` will be enabled too (for an @@ -3706,25 +3692,25 @@ In more detail, these rules/behaviors are: 18) **_ENABLE_ALL_FORWARD_DEP_PACKAGES enables downstream packages/tests**: Setting the user cache-variable ``${PROJECT_NAME}_ENABLE_ALL_FORWARD_PACKAGES=ON`` will result in the - `downstream`_ ``PT`` SE packages and tests to be enabled (and all ``PT`` - and ``ST`` SE packages and tests when + `downstream`_ ``PT`` packages and tests to be enabled (and all ``PT`` + and ``ST`` packages and tests when ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=ON``) for all explicitly enabled - SE packages. For example, configuring with ``Trilinos_ENABLE_Epetra=ON``, + packages. For example, configuring with ``Trilinos_ENABLE_Epetra=ON``, ``Trilinos_ENABLE_TESTS=ON``, and ``Trilinos_ENABLE_ALL_FORWARD_PACKAGES=ON`` will result the package - enables (and test and example enables) for the SE packages ``Triutils``, + enables (and test and example enables) for the packages ``Triutils``, ``EpetraExt``, ``ThyraCoreLibs``, ``ThyraEpetra`` and ``Thyra``. For an example, see `Explicit enable of a package and downstream packages and tests`_. .. _${PROJECT_NAME}_ENABLE_ALL_PACKAGES: -.. __ENABLE_ALL_PACKAGES enables all PT (cond. ST) SE packages: +.. __ENABLE_ALL_PACKAGES enables all PT (cond. ST) packages: -19) **_ENABLE_ALL_PACKAGES enables all PT (cond. ST) SE packages**: +19) **_ENABLE_ALL_PACKAGES enables all PT (cond. ST) packages**: Setting the user cache-variable ``${PROJECT_NAME}_ENABLE_ALL_PACKAGES=ON`` - will result in the enable of all ``PT`` SE packages when - ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=OFF`` and all ``PT`` and ``ST`` SE + will result in the enable of all ``PT`` packages when + ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=OFF`` and all ``PT`` and ``ST`` packages when ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=ON``. For an example, see `Enable all packages`_. When the project is a meta-project, this will only enable the project's primary meta-project packages (PMPP). @@ -3735,14 +3721,14 @@ In more detail, these rules/behaviors are: ${REPOSITORY_NAME}_NO_PRIMARY_META_PROJECT_PACKAGES=TRUE - then the SE package may be enabled if it (or its parent package) is listed + then the package may be enabled if it (or its parent package) is listed in `${REPOSITORY_NAME}_NO_PRIMARY_META_PROJECT_PACKAGES_EXCEPT`_. -.. __ENABLE_TESTS only enables explicitly enabled SE package tests: +.. __ENABLE_TESTS only enables explicitly enabled package tests: -20) **_ENABLE_TESTS only enables explicitly enabled SE package +20) **_ENABLE_TESTS only enables explicitly enabled package tests**: Setting ``${PROJECT_NAME}_ENABLE_TESTS=ON`` will **only enable - tests for explicitly enabled SE packages** on input. For example, + tests for explicitly enabled packages** on input. For example, configuring with ``Trilinos_ENABLE_RTOp=ON`` and ``Trilinos_ENABLE_TESTS=ON`` will only result in the enable of tests for ``RTOp``, not ``Teuchos`` (even through TriBITS will enable ``Teuchos`` @@ -3751,13 +3737,13 @@ In more detail, these rules/behaviors are: meta-project, this will only enable tests for the project's primary meta-project packages (PMPP). The uses the same logic as for ``${PROJECT_NAME}_ENABLE_ALL_PACKAGES``, see - `_ENABLE_ALL_PACKAGES enables all PT (cond. ST) SE packages`_. + `_ENABLE_ALL_PACKAGES enables all PT (cond. ST) packages`_. -.. _If no SE packages are enabled, nothing will get built: +.. _If no packages are enabled, nothing will get built: -21) **If no SE packages are enabled, nothing will get built**: Most TriBITS +21) **If no packages are enabled, nothing will get built**: Most TriBITS projects are set up such that if the user does not explicitly enable at - least one SE package in some way, then nothing will be enabled or built. + least one package in some way, then nothing will be enabled or built. In this case, when ``${PROJECT_NAME}_ALLOW_NO_PACKAGES=TRUE`` a warning will be printed and configuration will complete. However, if ``${PROJECT_NAME}_ALLOW_NO_PACKAGES=FALSE``, then the configure will die @@ -3773,10 +3759,10 @@ In more detail, these rules/behaviors are: (to ``cmake`` stdout) the initial set of enables/disables on input, prints a line whenever it sets (or overrides) an enable or disable, and prints out the final set of enables/disables. Therefore, the user just needs to - grep the ``cmake`` stdout to find out why any particular SE package or TPL + grep the ``cmake`` stdout to find out why any particular package or TPL is enabled or disabled in the end. In addition, will print out when - tests/examples for a given SE package gets enabled and when support for - optional SE packages and TPLs is enabled or not. Examples of this output + tests/examples for a given package gets enabled and when support for + optional packages and TPLs is enabled or not. Examples of this output is given in all of the below examples but a detailed description of this output is given in `Explicit enable of a package and its tests`_. @@ -3789,8 +3775,8 @@ In more detail, these rules/behaviors are: they don't get set in the cache and so that the same dependency enable/disable logic is redone, from scratch, with each re-configure. This results in the same enable/disable logic output as for the initial - configure. This is to avoid confusion by the user about why some SE - packages and TPLs are enabled and some are not on subsequent reconfigures. + configure. This is to avoid confusion by the user about why some packages + and TPLs are enabled and some are not on subsequent reconfigures. However, this implementation choice must be understood when one wants to go about tweaking these TriBITS enable/disable variables as described in `How to check for and tweak TriBITS "ENABLE" cache variables`_ and `How to @@ -3834,7 +3820,7 @@ implicitly or not by TriBITS: The above variables typically are defined in the outer TriBITS Project's CTest driver scripts or even in top-level project files in order to adjust how packages in its listed repositories are handled. What these variable do is to -allow a large project to turn off the auto-enable of optional SE packages in a +allow a large project to turn off the auto-enable of optional packages in a given TriBITS repository to provide more detailed control of what gets used from a given TriBITS repository. This, for example, is used in the CASL VERA project to manage some of its extra repositories and packages to further reduce @@ -3904,12 +3890,12 @@ which produces the relevant dependency-related output: The above example demonstrates the following behaviors of the TriBITS dependency handling system: -* `PT/ST SE packages given default unset enable/disable state`_ -* `EX SE packages disabled by default`_ (i.e., the ``EX`` SE package +* `PT/ST packages given default unset enable/disable state`_ +* `EX packages disabled by default`_ (i.e., the ``EX`` package ``ThyraCrazyStuff`` is set to ``OFF`` by default at the very beginning). * `PT/ST TPLs given default unset enable/disable state`_ * `EX TPLs given default unset enable/disable state`_ -* `If no SE packages are enabled, nothing will get built`_ +* `If no packages are enabled, nothing will get built`_ .. _Explicit enable of a package and its tests: @@ -3947,34 +3933,34 @@ the behavior `Enable/disable of parent package is enable/disable for subpackages`_. Note that the ``ST`` subpackages ``ThyraGoodStuff`` and ``ThyraEpetraExt`` where *not* enabled because ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=OFF`` (which is off by default) which -demonstrates the behavior `ST SE packages only auto-enabled if ST code is +demonstrates the behavior `ST packages only auto-enabled if ST code is enabled`_. -Second, note the auto-enable of required upstream SE packages ``Epetra``, +Second, note the auto-enable of required upstream packages ``Epetra``, ``RTOp`` and ``Teuchos`` shown in lines like:: -- Setting Trilinos_ENABLE_Teuchos=ON because ThyraCoreLibs has a required dependence on Teuchos -Lastly, note that the final set of enabled packages, SE packages, -tests/examples and TPLs can be clearly seen when processing the TPLs and -top-level packages in the lines:: +Lastly, note that the final set of enabled packages, packages, tests/examples +and external packages/TPLs can be clearly seen when processing the external +packages/TPLs and top-level packages in the lines:: - Getting information for all enabled TPLs ... + Getting information for all enabled external packages/TPLs ... - -- Processing enabled TPL: BLAS - -- Processing enabled TPL: LAPACK + -- Processing enabled external package/TPL: BLAS + -- Processing enabled external package/TPL: LAPACK Configuring individual enabled Trilinos packages ... - Processing enabled package: Teuchos (Libs) - Processing enabled package: RTOp (Libs) - Processing enabled package: Epetra (Libs) - Processing enabled package: Thyra (CoreLibs, Epetra, Tests, Examples) + Processing enabled top-level package: Teuchos (Libs) + Processing enabled top-level package: RTOp (Libs) + Processing enabled top-level package: Epetra (Libs) + Processing enabled top-level package: Thyra (CoreLibs, Epetra, Tests, Examples) Note that subpackage enables are listed with their parent packages along with -if the tests and/or examples are enabled. Top-level level packages that don't -have subpackages just show if the ``Libs`` or also the ``Tests`` and -``Examples`` have been enabled as well. +if the tests and/or examples are enabled. Top-level packages that don't have +subpackages just show ``Libs`` and ``Tests`` and ``Examples`` if they have +been enabled as well. .. _Explicit enable of a package, its tests, an optional TPL, with ST enabled: @@ -4007,7 +3993,7 @@ First, note the enable of the ``ST`` ``Thyra`` subpackages in lines like:: -- Setting subpackage enable Trilinos_ENABLE_ThyraGoodStuff=ON because parent package \ Trilinos_ENABLE_Thyra=ON -Second, note the auto-enable of support for optional SE packages in lines +Second, note the auto-enable of support for optional packages in lines like:: -- Setting EpetraExt_ENABLE_Triutils=ON since Trilinos_ENABLE_EpetraExt=ON \ @@ -4047,7 +4033,7 @@ which produces the relevant dependency-related output: :literal: Note how the disable of ``Epetra`` wipes out all of the required and optional -SE packages and intra-package dependencies that depend on ``Epetra``. What is +packages and intra-package dependencies that depend on ``Epetra``. What is left is only the ``ThyraCoreLibs`` and its upstream dependencies that don't depend on ``Epetra`` (which is only ``RTOp`` and ``Teuchos``). @@ -4136,7 +4122,7 @@ ToDo: Set Trilinos_ENABLE_Epetra=ON and Trilinos_ENABLE_BLAS=OFF **Explicit enable of a subpackage** -ToDo: Enable ThyraEpetra and show how it enables other SE packages and at the +ToDo: Enable ThyraEpetra and show how it enables other packages and at the end, enables the Thyra package (just for show). .. _Explicit enable of an optional package dependency: @@ -4204,7 +4190,7 @@ produces the relevant dependency-related output: .. include:: ReducedMockTrilinosOutput/EnableAllPackages.txt :literal: -As shown above, only the ``PT`` SE packages get enabled. To also enable the +As shown above, only the ``PT`` packages get enabled. To also enable the ``ST`` packages as well, one additionally set ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=ON`` at configure time. @@ -4240,8 +4226,8 @@ packages from the `MockTrilinos`_ project is shown below:: This XML file contains the names, directories, `Test Test Category`_ -(i.e. ``type``), CDash email address, and all of the SE package and TPL -dependencies for every SE package in the TriBITS project (including add-on +(i.e. ``type``), CDash email address, and all of the package and TPL +dependencies for every package in the TriBITS project (including add-on repositories if specified). There are several python tools under ``tribits/ci_support/`` that read in this file and use the created data-structure for various tasks. This file and these tools are used by @@ -4279,20 +4265,20 @@ Once the XML file ```` is created, it can be used in various types of analysis and used with different tools and commands. The tool `get-tribits-packages-from-files-list.py`_ can be used to determine -the list of TriBITS SE packages that need to be tested given a list of changed +the list of TriBITS packages that need to be tested given a list of changed files (e.g. as returned from ``git diff --name-only .. > changed-files.txt``). This is used in the `checkin-test.py`_ tool and the `tribits_ctest_driver()`_ function to determine what TriBITS packages need to be tested based on what files have been changed. The tool `get-tribits-packages-from-last-tests-failed.py`_ can be used to -extract the list of TriBITS SE packages that correspond to the failings tests +extract the list of TriBITS packages that correspond to the failings tests listed in the CTest-generated ``/Testing/Temporary/LastTestsFailed*.log`` file. This tool is used in the `tribits_ctest_driver()`_ function in CI-testing mode to determine what packages must be re-tested if they failed in the last CI iteration. -The tool `filter-packages-list.py`_ takes in a list of TriBITS SE package +The tool `filter-packages-list.py`_ takes in a list of TriBITS package names and then filters the list according the `Test Test Category`_ of the packages. This is used in testing workflows that only test a subset of packages according to the Test Test Category at different stages in the @@ -4343,22 +4329,22 @@ to be included in a given project build and test definition. These different classification are: * `Repository Test Classification`_ -* `SE Package Test Group`_ +* `Package Test Group`_ * `Test Test Category`_ These different test-related classifications are used to defined several different `Nested Layers of TriBITS Project Testing`_. First, the `Repository Test Classification`_ determines what repositories are even processed in order -for their SE packages to even consider being enabled. Second, if a repository -is selected, then the `SE Package Test Group`_ determines what SE packages +for their packages to even consider being enabled. Second, if a repository +is selected, then the `Package Test Group`_ determines what packages (and optional code in those packages) are even enabled such that their `/CMakeLists.txt`_ files are even processed (i.e. according to -`TriBITS Dependency Handling Behaviors`_). Lastly, if an SE package gets +`TriBITS Dependency Handling Behaviors`_). Lastly, if an package gets enabled, then the `Test Test Category`_ determines what test executables and test cases get defined using the functions `tribits_add_executable()`_, `tribits_add_test()`_ and `tribits_add_advanced_test()`_. -More detailed descriptions of `Repository Test Classifications`_, `SE Package +More detailed descriptions of `Repository Test Classifications`_, `Package Test Groups`_, and `Test Test Categories`_ are given in the following subsections. @@ -4408,7 +4394,7 @@ for details). by default as part of any automated testing described in the subsection `Nested Layers of TriBITS Project Testing`_ (except for perhaps some experimental builds). The main reason that an extra repo may be marked as - ``Experimental`` is that it may only contain ``EX`` SE packages and + ``Experimental`` is that it may only contain ``EX`` packages and therefore none of these packages would be enabled by default anyway. Also, a repo may be marked as ``Experimental`` if it is developed in a very sloppy way such that one cannot even assume that the repository's @@ -4426,44 +4412,43 @@ for details). .. However, it does seem they get cloned no matter what their classification .. in the TribitsCTestDriverCore.cmake script. -.. _SE Package Test Group: -.. _SE Package Test Groups: +.. _Package Test Group: +.. _Package Test Groups: -**SE Package Test Group** +**Package Test Group** Once a set of TriBITS repositories are selected in accordance with their -`Repository Test Classification`_, that determines the set of SE packages and -TPLs defined for the TriBITS project. Given the set of defined SE packages -and TPLs, the set of SE packages that get enabled is determined by the **SE -Package Test Group** which is defined and described here. - -Every `TriBITS SE Package`_ and `TriBITS TPL`_ is assigned a test group. These -test groups are for *Primary Tested* (`PT`_) code, *Secondary Tested* (`ST`_) -code, and *Experimental* (`EX`_) code. The test group defines *what* SE -packages and TPL get selected (or are excluded from being selected) to include -in a given build for testing-related purposes. SE packages may also -conditionally build in additional code based on the testing group. The -detailed rules for when an SE package or TPL are selected or excluded from the -build based on the test group is given in `TriBITS Dependency Handling -Behaviors`_. We only summarize those rules here. +`Repository Test Classification`_, that determines the set of packages defined +for the TriBITS project. Given the set of defined packages, the set of +packages that get enabled is determined by the **Package Test Group** which is +defined and described here. + +Every `TriBITS Package`_ is assigned a test group. These test groups are for +*Primary Tested* (`PT`_) code, *Secondary Tested* (`ST`_) code, and +*Experimental* (`EX`_) code. The test group defines *what* package get +selected (or are excluded from being selected) to include in a given build for +testing-related purposes. packages may also conditionally build in additional +code based on the testing group. The detailed rules for when an package is +selected or excluded from the build based on the test group is given in +`TriBITS Dependency Handling Behaviors`_. We only summarize those rules here. More detailed descriptions of the test groups are given below. .. _PT: * **Primary Tested (PT)** Code is of the highest priority to keep working for - the current development effort. SE packages and TPLs may be selected to be - ``PT`` for a number of reasons. First, if the capability provided by the - code is mature and if a regression would cause major harm to a customer, the - code should likely be marked as ``PT``. Also, if the build and correct - functioning of the code is needed by other development team members to - support their day-to-day development activities, then the code should be - marked as ``PT`` as well. A TPL, on the other hand, is marked as ``PT`` if - it is required by a ``PT`` SE package. Every project developer is expected - to have every ``PT`` TPL installed on every machine where they do + the current development effort. Packages may be selected to be ``PT`` for a + number of reasons. First, if the capability provided by the code is mature + and if a regression would cause major harm to a customer, the code should + likely be marked as ``PT``. Also, if the build and correct functioning of + the code is needed by other development team members to support their + day-to-day development activities, then the code should be marked as ``PT`` + as well. An external package/TPL, on the other hand, is marked as ``PT`` if + it is required by a downstream ``PT`` package. Every project developer is + expected to have every ``PT`` TPL installed on every machine where they do development on and from which they push to the global repo (see - `checkin-test.py`_ tool). ``PT`` SE packages and TPLs are the foundation - for `Pre-Push CI Testing`_. + `checkin-test.py`_ tool). ``PT`` packages are the foundation for `Pre-Push + CI Testing`_. .. _ST: @@ -4473,19 +4458,20 @@ More detailed descriptions of the test groups are given below. marked as ``ST`` if is not critical to drive most day-to-day development activities. If ``ST`` code breaks, it usually will not cause immediate and major harm to most developers. Also, code may be marked as ``ST`` if it has - required dependencies on ``ST`` TPLs which are either hard to install or may - not be available on all platforms where developers do their development and - from where they push changes to the global repo. In addition, code may be - marked as ``ST`` if the project is just too big and developers can't be - expected to build and test all of this code with every push (so a decision - is made to only make some code as ``PT`` so that pushes don't take too - long). ``ST`` code can be included in the TriBITS auto-enable algorithms by - setting the variable ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=ON`` (see - `TriBITS Dependency Handling Behaviors`_). Otherwise, ``ST`` code **is - not** enabled by auto-enable algorithms. Typically, ``ST`` code is excluded - from the default builds in `Pre-Push CI Testing`_ but ``ST`` code **is** - typically tested in `Post-Push CI Testing`_, `Nightly Testing`_ as well as - in other testing cases. + required dependencies on ``ST`` external packages/TPLs which are either hard + to install or may not be available on all platforms where developers do + their development and from where they push changes to the global repo. In + addition, code may be marked as ``ST`` if the project is just too big and + developers can't be expected to build and test all of this code with every + push (so a decision is made to only make some code as ``PT`` so that pushes + don't take too long). ``ST`` code can be included in the TriBITS + auto-enable algorithms by setting the variable + ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=ON`` (see `TriBITS Dependency + Handling Behaviors`_). Otherwise, ``ST`` code **is not** enabled by + auto-enable algorithms. Typically, ``ST`` code is excluded from the default + builds in `Pre-Push CI Testing`_ but ``ST`` code **is** typically tested in + `Post-Push CI Testing`_, `Nightly Testing`_ as well as in other testing + cases. .. _EX: @@ -4512,18 +4498,19 @@ The test group for each type of entity is assigned in the following places: argument in the macro call `tribits_package_define_dependencies()`_ in its parent package's `/cmake/Dependencies.cmake`_ file. -* A `TriBITS TPL`_'s test group is assigned using the ``CLASSIFICATION`` field - in the macro call `tribits_repository_define_tpls()`_ in its parent - repository's `/TPLsList.cmake`_ file. +* A `TriBITS External Package/TPL`_'s test group is assigned using the + ``CLASSIFICATION`` field in the macro call + `tribits_repository_define_tpls()`_ in its parent repository's + `/TPLsList.cmake`_ file. After these files are processed, the variable `${PACKAGE_NAME}_TESTGROUP`_ -gives the test group for each defined SE Package while the variable +gives the test group for each defined Package while the variable ``${TPL_NAME}_TESTGROUP`` gives the test group for each defined TPL. Note that the test group classification ``PT``/``ST``/``EX`` is *not* to be -confused with the *maturity level* of the SE package as discussed in the +confused with the *maturity level* of the package as discussed in the `TriBITS Lifecycle Model`_. The test group classification in no way implies -the maturity of the given TriBITS SE Package or piece of code. Instead, the +the maturity of the given TriBITS Package or piece of code. Instead, the test group is just used to sub-select packages (and pieces of code within those packages) that are the most important to sustain for the various current development group's activities. While more-mature code would typically never @@ -4534,8 +4521,8 @@ the low *maturity level* of *Research Stable* (``RS``) or even *Exploratory* (``EP``) because keeping that code working may be critical to keeping the research project on track. -In addition to just selecting ``PT`` and ``ST`` SE packages as a whole, a -TriBITS ``PT`` SE package can also contain conditional code and test +In addition to just selecting ``PT`` and ``ST`` packages as a whole, a +TriBITS ``PT`` package can also contain conditional code and test directories that get enabled when ``${PROJECT_NAME}_SECONDARY_TESTED_CODE=ON`` and therefore represents more ``ST`` code. The package's `/CMakeLists.txt`_ files can contain simple if statements and can @@ -4543,8 +4530,8 @@ use the `tribits_set_st_for_dev_mode()`_ function to automatically select extra code to enable when ``ST`` is enabled or when the project is in release mode. -.. ToDo: Provide examples in TribitsExampleProject of ST and EX SE packages -.. and of conditional ST and EX code in an PT SE package. This is important +.. ToDo: Provide examples in TribitsExampleProject of ST and EX packages +.. and of conditional ST and EX code in an PT package. This is important .. to round out the examples. .. _Test Test Category: @@ -4554,7 +4541,7 @@ mode. Once a package is even defined (due to its parent repository's selection consistent with its `Repository Test Classification`_) and is the package is -enabled (consistent with its `SE Package Test Group`_) then the set of +enabled (consistent with its `Package Test Group`_) then the set of individual test executables and test cases that are included or not in that package depends on the ``CATEGORIES`` argument in the functions `tribits_add_executable()`_, `tribits_add_test()`_ and @@ -4676,31 +4663,31 @@ repository(s). With TriBITS, this type of testing and the following push is typically done using the `checkin-test.py`_ tool. This category of testing is described in much more detail in `Pre-push Testing using checkin-test.py`_. All of the "default builds" used with the ``checkin-test.py`` tool select -repositories, SE packages and code, and individual tests using the following +repositories, packages and code, and individual tests using the following test-related classifications: ========================= ================== ==================================== Classification Type Classification (See Reference) ========================= ================== ==================================== Repository Test Classif. ``Continuous`` (`Repository Test Continuous`_) -SE Package Test Group ``PT`` (`PT`_) +Package Test Group ``PT`` (`PT`_) Test Test Category ``BASIC`` (`Test Test Category BASIC`_) ========================= ================== ==================================== Typically a TriBITS project will define a "standard development environment" -which is comprised of a standard compiler (e.g. GCC 8.3.0), TPL versions -(e.g. OpenMPI 4.0.5, Boost 4.9, etc.), and other tools (e.g. cmake 3.17.0, git -2.10.1, etc.). This standard development environment is expected to be used -to test changes to the project's code before any push. By using a standard -development environment, if the code builds and all the tests pass for the -"default" pre-push builds for one developer, then that maximizes the -probability that the code will also build and all tests will pass for every -other developer using the same development environment. This is critical to -keep the development team maximally productive. Portability is also important -for most projects but portability testing is best done in a secondary feedback -look using `Nightly Testing`_ builds. TriBITS has some support for helping to -set up a standard software development environment as described in section -`TriBITS Development Toolset`_. +which is comprised of a standard compiler (e.g. GCC 8.3.0), external +package/TPL versions (e.g. OpenMPI 4.0.5, Boost 4.9, etc.), and other tools +(e.g. cmake 3.17.0, git 2.10.1, etc.). This standard development environment +is expected to be used to test changes to the project's code before any push. +By using a standard development environment, if the code builds and all the +tests pass for the "default" pre-push builds for one developer, then that +maximizes the probability that the code will also build and all tests will +pass for every other developer using the same development environment. This +is critical to keep the development team maximally productive. Portability is +also important for most projects but portability testing is best done in a +secondary feedback look using `Nightly Testing`_ builds. TriBITS has some +support for helping to set up a standard software development environment as +described in section `TriBITS Development Toolset`_. The basic assumption of all CI processes (including the one described here) is that if anyone pulls the project's development sources at any time, then all @@ -4722,14 +4709,14 @@ project's dashboard page). This process is driven by CTest driver code that calls `tribits_ctest_driver()`_ as described in the section `TriBITS CTest/CDash Driver`_. Various types of specific CI builds can be constructed and run (see `CTest/CDash CI Server`_) but these post-push CI builds typically -select repositories, SE packages and code, and individual tests using the +select repositories, packages and code, and individual tests using the following test-related classifications: ========================= ================== ==================================== Classification Type Classification (See Reference) ========================= ================== ==================================== Repository Test Classif. ``Continuous`` (`Repository Test Continuous`_) -SE Package Test Group ``PT`` & ``ST`` (`PT`_ and `ST`_) +Package Test Group ``PT`` & ``ST`` (`PT`_ and `ST`_) Test Test Category ``CONTINUOUS`` (`Test Test Category CONTINUOUS`_) ========================= ================== ==================================== @@ -4753,18 +4740,18 @@ project's dashboard page). Nightly builds don't run in a continuous loop but instead are run once a day (e.g. driven by a cron job) and there tends to be many different nightly build cases that test the project using different compilers (e.g. GCC, Intel, Microsoft, etc., and different versions of each), -different TPL versions (e.g. different OpenMPI versions, different MPICH -versions, etc.), different platforms (e.g. Linux, Windows, etc.), and varying -many other options and settings on these different platforms. What all -nightly builds have in common is that they tend to select repositories, SE -packages and code, and individual tests using the following test-related -classifications: +different external package/TPL versions (e.g. different OpenMPI versions, +different MPICH versions, etc.), different platforms (e.g. Linux, Windows, +etc.), and varying many other options and settings on these different +platforms. What all nightly builds have in common is that they tend to select +repositories, packages and code, and individual tests using the following +test-related classifications: ========================= ================== ==================================== Classification Type Classification (See Reference) ========================= ================== ==================================== Repository Test Classif. ``Nightly`` (`Repository Test Nightly`_) -SE Package Test Group ``PT`` & ``ST`` (`PT`_ and `ST`_) +Package Test Group ``PT`` & ``ST`` (`PT`_ and `ST`_) Test Test Category ``NIGHTLY`` (`Test Test Category NIGHTLY`_) ========================= ================== ==================================== @@ -4779,14 +4766,14 @@ that add on more expensive tests marked using the `Test Test Category HEAVY`_. For projects that define heavy tests and heavy builds, individual test cases may be allowed to take 24 hours or longer to run so they can't even be run every day in nightly testing. What standard heavy builds have in common is -that they tend to select repositories, SE packages and code, and individual +that they tend to select repositories, packages and code, and individual tests using the following test-related classifications: ========================= ================== ==================================== Classification Type Classification (See Reference) ========================= ================== ==================================== Repository Test Classif. ``Nightly`` (`Repository Test Nightly`_) -SE Package Test Group ``PT`` & ``ST`` (`PT`_ and `ST`_) +Package Test Group ``PT`` & ``ST`` (`PT`_ and `ST`_) Test Test Category ``HEAVY`` (`Test Test Category HEAVY`_) ========================= ================== ==================================== @@ -4810,14 +4797,14 @@ is to define the special `Test Test Category PERFORMANCE`_ to allow TriBITS packages to declare these tests in a consistent way so that they can be run along with performance tests defined in other TriBITS packages. From a TriBITS standpoint, all performance testing builds would tend to select -repositories, SE packages and code, and individual tests using the following +repositories, packages and code, and individual tests using the following test-related classifications: ========================= ================== ==================================== Classification Type Classification (See Reference) ========================= ================== ==================================== Repository Test Classif. ``Nightly`` (`Repository Test Nightly`_) -SE Package Test Group ``PT`` & ``ST`` (`PT`_ and `ST`_) +Package Test Group ``PT`` & ``ST`` (`PT`_ and `ST`_) Test Test Category ``PERFORMANCE`` (`Test Test Category PERFORMANCE`_) ========================= ================== ==================================== @@ -4876,7 +4863,7 @@ e) marks a set of working commits that are safe to search with ``git bisect`` When using the ``checkin-test.py`` tool, every TriBITS project defines one or more "default builds" (specified through the ``--default-builds`` argument) for pre-push CI testing that form the criteria for if it is okay to push code -changes or not. The "default builds" select repositories, SE packages and +changes or not. The "default builds" select repositories, packages and code, and individual tests as described in `Pre-Push CI Testing`_. A TriBITS project defines its default pre-push builds using the file `/project-checkin-test-config.py`_. For an example, the file @@ -4905,11 +4892,11 @@ development team should not have to test the chosen compiler's ability to generate non-optimized debug code and suffer slower test times before pushing. Note that turning on ``-DTribitsExProj_ENABLE_CHECKED_STL=ON`` as shown above -can only be used when the TPLs have no C++ code using the C++ STL or if that -particular build points to C++ TPLs also compiled with checked STL enabled. -The `TribitsExampleProject`_ default builds do not depend on any C++ TPLs that -might use the C++ STL so enabling this option adds additional positive -debug-mode checking for C++ code. +can only be used when the external packages/TPLs have no C++ code using the +C++ STL or if that particular build points to C++ TPLs also compiled with +checked STL enabled. The `TribitsExampleProject`_ default builds do not +depend on any C++ TPLs that might use the C++ STL so enabling this option adds +additional positive debug-mode checking for C++ code. The ``checkin-test.py`` tool is a fairly sophisticated piece of software that is well tested and very robust. The level of testing of this tool is likely @@ -5224,8 +5211,8 @@ Repositories`_ which contain multiple `TriBITS Packages`_ (see `How to set up multi-repository support`_). The basic configuration, build, and test of such projects requires only raw CMake/CTest, just like any other CMake project (see `TriBITS System Project Dependencies`_). Every TriBITS project automatically -supports tacking on add-on TriBITS packages and TPLs through the -`${PROJECT_NAME}_EXTRA_REPOSITORIES`_ cmake cache variable as described in +supports tacking on add-on TriBITS packages and external packages/TPLs through +the `${PROJECT_NAME}_EXTRA_REPOSITORIES`_ cmake cache variable as described in `Enabling extra repositories with add-on packages`_. In addition, a TriBITS project can be set up to pull in other TriBITS Repositories using the `/cmake/ExtraRepositoriesList.cmake`_ file. A special form of @@ -5464,9 +5451,9 @@ To add a new TriBITS package (with no subpackages), do the following: 2) Create the directory ``//`` for the new package and put in skeleton files for `/cmake/Dependencies.cmake`_ and - `/CMakeLists.txt`_. Set the desired upstream TPL and SE - package dependencies in the new ``Dependencies.cmake`` file but initially - comment out everything in the ``CMakeLists.txt`` file except for the + `/CMakeLists.txt`_. Set the desired upstream TPL and package + dependencies in the new ``Dependencies.cmake`` file but initially comment + out everything in the ``CMakeLists.txt`` file except for the `tribits_package()`_ and `tribits_package_postprocess()`_ commands. 3) Add a row for the new package to the `/PackagesList.cmake`_ file @@ -5481,7 +5468,7 @@ To add a new TriBITS package (with no subpackages), do the following: libraries, executables, tests and examples. The project should be built and tests run as new pieces are added. -Once the new package is defined, downstream SE packages can define +Once the new package is defined, downstream packages can define dependencies on this new package. .. ToDo: Expand on the above bullets a lot! @@ -5520,7 +5507,7 @@ To add a new TriBITS package with packages, do the following: Subpackage`_, filling out the various ``CMakeLists.txt`` files defining libraries, executables, tests and examples. -Once the new SE packages are defined, downstream SE packages can define +Once the new packages are defined, downstream packages can define dependencies on these. @@ -5542,13 +5529,13 @@ subpackages, do the following: 1) Chose a name ```` for the new subpackage which only has to be different than the other subpackages in the parent package. This name gets - appended to the parent package's name ```` to form the SE - package name ````. + appended to the parent package's name ```` to form the package + name ````. 2) Create the directory ``/`` for the new package and put in skeleton files for `//cmake/Dependencies.cmake`_ and `//CMakeLists.txt`_. Set the desired upstream TPL - and SE package dependencies in the new ``Dependencies.cmake`` file but + and package dependencies in the new ``Dependencies.cmake`` file but initially comment out everything in the ``CMakeLists.txt`` file except for the `tribits_subpackage()`_ and `tribits_subpackage_postprocess()`_ commands. @@ -5561,7 +5548,7 @@ subpackages, do the following: its upstream dependent subpackages, the TriBITS CMake code will catch this and issue an error. -4) Configure the TriBITS project enabling the new empty SE package +4) Configure the TriBITS project enabling the new empty package ````. This will enable the listed dependencies. 5) Incrementally fill in the subpackage's ``CMakeLists.txt`` files defining @@ -5613,20 +5600,21 @@ To add a new TriBITS TPL, do the following: `/cmake/Dependencies.cmake`_ or `//cmake/Dependencies.cmake`_ for a subpackage). -8) **[Optional] Add #cmakedefine for an optional package library TPL - dependency in the package's _config.h.in file** using:: +8) **[Optional] Add #cmakedefine for an optional package LIB TPL dependency in + the package's _config.h.in file** using:: #cmakedefine HAVE__ - so that the package's code build knows if the TPL is defined or not (see - `_config.h.in`_ and `tribits_configure_file()`_). (NOTE: Do - **not** add this for a optional test-only TPL dependency. We don't want - all of the libraries in a package to have to be rebuild when we enable or - disable tests for the package.) + so that the package's LIB code build knows if the TPL is defined or not + (see `_config.h.in`_ and `tribits_configure_file()`_). (NOTE: + Do **not** add this define for a optional test-only TPL dependency. We + don't want all of the libraries in a package to have to be rebuild when we + enable or disable tests for the package.) 9) **Use the TPL functionality in the packages** that define the dependency on the new TPL, configure, test, etc. + .. _Creating the FindTPL.cmake file: **Creating the FindTPL.cmake file** @@ -5988,17 +5976,17 @@ links. .. ToDo: Provide more detail! -How to add a new TriBITS SE Package dependency +How to add a new TriBITS Package dependency ---------------------------------------------- It is often the case where one will want to add a new dependency for an -existing `downstream`_ package to an existing `upstream`_ `TriBITS SE -Package`_. This can either be a required dependency or an optional -dependency. Here, we will refer to the downstream SE package as -```` with base directory ```` and will refer to the -upstream package as ````. +existing `downstream`_ package to an existing `upstream`_ `TriBITS Package`_. +This can either be a required dependency or an optional dependency. Here, we +will refer to the downstream package as ```` with base directory +```` and will refer to the upstream package as +````. -The process for adding a new dependency to an existing upstream SE package is +The process for adding a new dependency to an existing upstream package is as follows: 1) **Add the name of the upstream package to the downstream package's @@ -6080,15 +6068,15 @@ package library and executable links. See documentation in the functions argument to these functions, for more details. -How to add a new TriBITS TPL dependency ---------------------------------------- +How to add a new TriBITS external package/TPL dependency +-------------------------------------------------------- It is often the case where one will want to add a new dependency for an -existing `downstream`_ package to an existing `upstream`_ `TriBITS TPL`_. -This can either be a required dependency or an optional dependency. Here, we -will refer to the downstream SE package as ```` with base -directory ```` and will refer to the upstream TPL as -````. +existing `downstream`_ package to an existing `upstream`_ `TriBITS external +package/TPL`_. This can either be a required dependency or an optional +dependency. Here, we will refer to the downstream package as +```` with base directory ```` and will refer to the +upstream TPL as ````. The process for adding a new dependency to an existing upstream TPL is as follows: @@ -6112,9 +6100,9 @@ follows: typically a C/C++ processor macro will be added to the package's configured `/cmake/_config.h.in`_ file using the line:: - #cmakedefine HAVE__ + #cmakedefine HAVE__ - (see `HAVE__`_.) + (see `HAVE__`_.) **WARNING:** If this is a test-only and/or example-only dependency then please do **not** add a ``#cmakedefine`` to the package's core @@ -6132,24 +6120,31 @@ follows: #include "_config.h" - #if HAVE__ + #if HAVE__ # include "_" #endif 4) **For an optional dependency, use CMake if() statements based on - ${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_TPL_NAME}:** When a package + ${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_PACKAGE_NAME}:** When a package ``PACKAGE_NAME`` has an optional dependency on TPL - ``OPTIONAL_DEP_TPL_NAME`` and needs to put in optional logic in a + ``OPTIONAL_DEP_PACKAGE_NAME`` and needs to put in optional logic in a CMakeLists.txt file, then the if() statements should use the variable - `${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_TPL_NAME}`_ and **not** the variable - ``${PROJECT_NAME}_ENABLE_${OPTIONAL_DEP_TPL_NAME}``. For example, to - optionally enable a test that depends on the enable of the optional TPL, - one would use:: + `${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_PACKAGE_NAME}`_ and **not** the + variable ``${PROJECT_NAME}_ENABLE_${OPTIONAL_DEP_PACKAGE_NAME}``. For + example, to optionally enable a test that depends on the enable of the + optional TPL, one could use:: - if (${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_TPL_NAME}) + if (${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_PACKAGE_NAME}) tribits_add_test( ... ) endif() + or:: + + tribits_add_test( + EXCLUDE_IF_NOT_TRUE ${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_PACKAGE_NAME} + [other args] + ) + .. ToDo: Find an example to point to in TribitsExampleProject. NOTE: TriBITS will automatically add the include directories for the upstream @@ -6160,13 +6155,13 @@ library and executable links. See documentation in the functions argument to these functions, for more details. -How to tentatively enable a TPL -------------------------------- +How to tentatively enable an external package/TPL +------------------------------------------------- -A TriBITS package can request the tentative enable of any of its optional TPLs -(see `How to add a new TriBITS TPL dependency`_). This is done by calling -`tribits_tpl_tentatively_enable()`_ in the SE package's -`/cmake/Dependencies.cmake`_ file. For example:: +A TriBITS package can request the tentative enable of any of its optional +external packagse/TPLs (see `How to add a new TriBITS external package/TPL +dependency`_). This is done by calling `tribits_tpl_tentatively_enable()`_ in +the package's `/cmake/Dependencies.cmake`_ file. For example:: tribits_package_define_dependencies( ... @@ -6200,7 +6195,7 @@ be missing. This is demonstrated in `TribitsExampleProject`_ with the package :literal: In this example, ``InsertedPkg`` has a required dependency on ``SimpleCxx`` -and the SE package ``WithSubpackagesB`` has an optional dependency on +and the package ``WithSubpackagesB`` has an optional dependency on ``InsertedPkg``. Therefore, the inserted package ``InsertedPkg`` has upstream and downstream dependencies on packages in the ``TribitsExampleProject`` repo. @@ -6250,8 +6245,8 @@ one would perform the following steps: ``tribits_allow_missing_external_packages()`` as described above. -5) Flesh out the new package and use it in downstream SE packages just like it - was any other package. But note that any downstream SE package that has a +5) Flesh out the new package and use it in downstream packages just like it + was any other package. But note that any downstream package that has a required dependency on ```` will always be hard disabled when the source for ```` is missing. @@ -6338,10 +6333,11 @@ TriBITS defines a number of special ``_ENABLE_`` variables for enabling/disabling various entities that allow for a default "undefined" empty ``""`` enable status. Examples of these special variables include: -* ``${PROJECT_NAME}_ENABLE_`` ((SE) packages) -* ``TPL_ENABLE_`` (TPLs) -* ``_ENABLE_`` (Optional support - for a (SE) package or TPL in a downstream package) +* ``${PROJECT_NAME}_ENABLE_`` (Packages) +* ``TPL_ENABLE_`` (External Packages/TPLs) +* ``_ENABLE_`` (Optional support for a + package ```` in a downstream package + ````) * ``_ENABLE_TESTS`` (Package tests) * ``_ENABLE_EXAMPLES`` (Package examples) * ``${PROJECT_NAME}_ENABLE_TESTS`` (Tests for explicitly enabled packages) @@ -6420,16 +6416,17 @@ is because, as shown in `Full Processing of TriBITS Project Files`_, they get processed after all of the user input has been read (in CMake cache variables set with ``-D=`` and read in from `${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE`_ files) but before TriBITS adjusts -the SE package and TPLs enables and disables (see `Package Dependencies and -Enable/Disable Logic`_). Also, these files get processed in `Reduced Package -Dependency Processing`_ as well so they get processed in all contexts where +the package enables and disables (see `Package Dependencies and Enable/Disable +Logic`_). Also, these files get processed in `Reduced Package Dependency +Processing`_ as well so they get processed in all contexts where enable/disable logic is applied. + How to tweak downstream TriBITS "ENABLE" variables during package configuration ------------------------------------------------------------------------------- There are cases where one may need to enable or disable some feature that -TriBITS may have enabled by default (such as in "Adjust SE package and TPLs +TriBITS may have enabled by default (such as in "Adjust package and TPLs enables and disables" in `Full Processing of TriBITS Project Files`_) and that decision can only be made while processing a package's `/CMakeLists.txt`_ file. (And therefore the logic for this disable @@ -6450,7 +6447,7 @@ multiple packages). When the internal configuration of a package (i.e. while processing its ``/CMakeLists.txt`` file) determines that an optional feature ``_ENABLE_`` must be enabled or disabled with and will change the -value previously set (e.g. during the "Adjust SE package and TPLs enables and +value previously set (e.g. during the "Adjust package and TPLs enables and disables" stage), one cannot use a simple ``set()`` statement. Changing the value of an ``_ENABLE_`` variable inside a package's ``/CMakeLists.txt`` file using a raw ``set(_ENABLE_ @@ -6668,14 +6665,18 @@ The following steps describe how to submit results to a CDash site using the * Jenkins jobs can be set up to run them based on various criteria. - * Travis CI can run them to respond to GitHub pushes. + * GitHub Actions can run them to respond to GitHub pushes or to test pull + requests. + + * GitLab CI can run them to respond to GitLab pushes or the test merge + requests. * Use the legacy `TriBITS Dashboard Driver`_ system (not recommended). - The setup of Jenkins, Travis CI and other more sophisticated automated - testing systems will not be described here. What will be briefly outlined - below is the setup using cron jobs on a Linux machine. That is sufficient - for most smaller projects and provides tremendous value. + The setup of Jenkins, GitHub Actions, GitLab CI and other more sophisticated + automated testing systems will not be described here. What will be briefly + outlined below is the setup using cron jobs on a Linux machine. That is + sufficient for most smaller projects and provides tremendous value. To set up an automated build using a cron job, one will typically create a shell driver script that sets the env and then calls the ``ctest -S @@ -6942,10 +6943,10 @@ discussed here is the fact that ``FindTPL.cmake`` files create (See ``Config.cmake`` and that could potentially be found by calls to ``find_package()`` (when `` == `` like with HDF5). These TriBITS-generated ``Config.cmake`` files are primarily -meant to be included by and provide the ``::all_libs`` targets for -downstream TriBITS-compatible ``Config.cmake`` files. These -TriBITS-generated ``Config.cmake`` files will usually not behave the -same way that a more general ``Find.config`` modules or native +meant to provide the ``::all_libs`` targets for downstream +TriBITS-compatible ``Config.cmake`` files. These TriBITS-generated +``Config.cmake`` files will usually not behave the same way that a +more general ``Find.config`` modules or native ``Config.cmake`` configure files would behave as expected when found by ``find_package()`` commands called in some arbitrary downstream raw CMake project. Therefore, to avoid having an installed TriBITS-generated @@ -6962,7 +6963,7 @@ and installed into the directory under:: so they will not be found by ``find_package()`` by default when ``/cmake_packages`` and/or ````, respectively, are added -to ``CMake_PREFIX_PATH``. Also, even if +to ``CMAKE_PREFIX_PATH``. Also, even if ``/lib/external_packages`` or ``/external_packages`` do get added to the search path somehow (e.g. by appending those to ``CMAKE_INSTALL_PREFIX``), the TriBITS framework will set the variable @@ -7177,8 +7178,8 @@ configure what is left. Sometimes, what is left will actually configure and might almost build! **NOTE:** As warned in `TriBITS Package Core Files`_ and `TriBITS Subpackage -Core Files`_, SE Packages must have directories that are strictly independent -of the directories of other SE packages. If they don't, then the source +Core Files`_, Packages must have directories that are strictly independent +of the directories of other packages. If they don't, then the source directory for an enabled package will get excluded from the source distribution if its directory is under the directory of a package that is not enabled. For example, if ``PackageA`` is enabled but its package directory @@ -8409,7 +8410,7 @@ slowly evolving but some key TriBITS features that have been added to support the arbitrary case include: * `tribits_determine_if_current_package_needs_rebuilt()`_: Uses brute-force - searches for recently modified files in upstream SE packages to determine if + searches for recently modified files in upstream packages to determine if the external piece of software needs to be rebuilt. * `tribits_write_flexible_package_client_export_files()`_: Write an export diff --git a/cmake/tribits/doc/guides/TribitsSystemMacroFunctionDocTemplate.rst b/cmake/tribits/doc/guides/TribitsSystemMacroFunctionDocTemplate.rst index b3f22837197e..e42125762328 100644 --- a/cmake/tribits/doc/guides/TribitsSystemMacroFunctionDocTemplate.rst +++ b/cmake/tribits/doc/guides/TribitsSystemMacroFunctionDocTemplate.rst @@ -25,7 +25,7 @@ understand the internals of TriBITS. @FUNCTION: tribits_dump_package_dependencies_info() + @FUNCTION: tribits_print_initial_dependency_info() + @FUNCTION: tribits_print_tentatively_enabled_tpls() + -@MACRO: tribits_parse_subpackages_append_se_packages_add_options() + +@MACRO: tribits_parse_subpackages_append_packages_add_options() + @MACRO: tribits_prep_to_read_dependencies() + @MACRO: tribits_process_all_repository_deps_setup_files() + @MACRO: tribits_process_package_dependencies_lists() + diff --git a/cmake/tribits/doc/guides/maintainers_guide/TribitsMaintainersGuide.rst b/cmake/tribits/doc/guides/maintainers_guide/TribitsMaintainersGuide.rst index 8031aa31ff4a..c9c0b1b7ccaf 100644 --- a/cmake/tribits/doc/guides/maintainers_guide/TribitsMaintainersGuide.rst +++ b/cmake/tribits/doc/guides/maintainers_guide/TribitsMaintainersGuide.rst @@ -53,8 +53,8 @@ TriBITS System Maintainers Documentation This section contains more detailed information about the internal implementation of TriBITS. This information is meant to make it easier to understand and manipulate the data-structures and macros/functions that make -up internal implementation of TriBITS. - +up internal implementation of TriBITS and is important for `TriBITS System +Developers`_ and `TriBITS System Architects`_. .. include:: ../../../core/package_arch/TribitsSystemDataStructuresMacrosFunctions.rst diff --git a/cmake/tribits/doc/guides/users_guide/TribitsUsersGuide.rst b/cmake/tribits/doc/guides/users_guide/TribitsUsersGuide.rst index b938fb6fed21..96d44b9e9abe 100644 --- a/cmake/tribits/doc/guides/users_guide/TribitsUsersGuide.rst +++ b/cmake/tribits/doc/guides/users_guide/TribitsUsersGuide.rst @@ -105,4 +105,4 @@ Appendix .. _tribits_read_all_project_deps_files_create_deps_graph(): TribitsMaintainersGuide.html#tribits-read-all-project-deps-files-create-deps-graph -.. _${PACKAGE_NAME}_LIB_ALL_DEPENDENCIES: TribitsMaintainersGuide.html#package-name-lib-enabled-dependencies +.. _${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES: TribitsMaintainersGuide.html#package-name-lib-enabled-dependencies diff --git a/cmake/tribits/examples/TribitsExampleProject/packages/with_subpackages/b/tests/testlib/ShowLibErrors.cmake b/cmake/tribits/examples/TribitsExampleProject/packages/with_subpackages/b/tests/testlib/ShowLibErrors.cmake index 0ef079f0fe83..51df795f23d3 100644 --- a/cmake/tribits/examples/TribitsExampleProject/packages/with_subpackages/b/tests/testlib/ShowLibErrors.cmake +++ b/cmake/tribits/examples/TribitsExampleProject/packages/with_subpackages/b/tests/testlib/ShowLibErrors.cmake @@ -1,7 +1,7 @@ # Define these vars to see invalid usage checking and errors! -if (SPKB_SHOW_SE_PKG_LIB_IMPORTEDLIBS_ERROR) +if (SPKB_SHOW_PKG_LIB_IMPORTEDLIBS_ERROR) set(EXTRA_TAL_ARGS IMPORTEDLIBS pws_b) -elseif (SPKB_SHOW_UPSTREAM_SE_PKG_LIB_IMPORTEDLIBS_ERROR) +elseif (SPKB_SHOW_UPSTREAM_PKG_LIB_IMPORTEDLIBS_ERROR) set(EXTRA_TAL_ARGS IMPORTEDLIBS simplecxx) endif() print_nonempty_var(EXTRA_TAL_ARGS)