Add option <Project>_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES (#63)

See updated documentation

test/core/ExamplesUnitTests/TribitsExampleProject_Tests.cmake

@@ -3236,7 +3236,7 @@ tribits_add_advanced_test( TribitsExampleProject_SimpleCxx_External
       -DTribitsExProj_ENABLE_SECONDARY_TESTED_CODE=ON
       -DTribitsExProj_ENABLE_SimpleCxx=ON
       -DCMAKE_INSTALL_PREFIX=../install/simple_cxx
-      # ToDo: Add option to stop install of TribitsExProjConfig.cmake ...
+      -DTribitsExProj_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES=TRUE
       -DTPL_ENABLE_MPI=OFF
       -DTPL_ENABLE_SimpleTpl=ON
       -DSimpleTpl_INCLUDE_DIRS=${SimpleTpl_install_STATIC_DIR}/install/include
@@ -3259,17 +3259,26 @@ tribits_add_advanced_test( TribitsExampleProject_SimpleCxx_External
     SKIP_CLEAN_WORKING_DIRECTORY
 
   TEST_4
+    MESSAGE "Make sure only SimpleCxxConfig.cmake was installed"
+    CMND ls ARGS install/simple_cxx/lib/cmake
+    PASS_REGULAR_EXPRESSION_ALL
+      "SimpleCxx"
+    FAIL_REGULAR_EXPRESSION
+      "TribitsExProj"
+    ALWAYS_FAIL_ON_NONZERO_RETURN
+
+  TEST_5
     MESSAGE "Remove the build directory for SimpleCxx"
     CMND ${CMAKE_COMMAND} ARGS -E rm -R Build_SimpleCxx
 
-  TEST_5
+  TEST_6
     MESSAGE "Remove the source directory for SimpleCxx"
     CMND ${CMAKE_COMMAND} ARGS -E rm -R
       TribitsExampleProject/packages/simple_cxx/CMakeLists.txt
       TribitsExampleProject/packages/simple_cxx/src
       TribitsExampleProject/packages/simple_cxx/test
 
-  TEST_6
+  TEST_7
     MESSAGE "Configure rest of TribitsExampleProject against pre-installed SimpleCxx"
     CMND ${CMAKE_COMMAND}
     WORKING_DIRECTORY Build
@@ -3293,13 +3302,13 @@ tribits_add_advanced_test( TribitsExampleProject_SimpleCxx_External
       "Configuring done"
     ALWAYS_FAIL_ON_NONZERO_RETURN
 
-  TEST_7
+  TEST_8
     MESSAGE "Build TribitsExampleProject"
     CMND make ARGS ${CTEST_BUILD_FLAGS}
     WORKING_DIRECTORY Build
     SKIP_CLEAN_WORKING_DIRECTORY
 
-  TEST_8
+  TEST_9
     MESSAGE "Run all the tests with ctest"
     WORKING_DIRECTORY Build
     SKIP_CLEAN_WORKING_DIRECTORY
@@ -3313,8 +3322,11 @@ tribits_add_advanced_test( TribitsExampleProject_SimpleCxx_External
 # NOTE: The above test is a strong check that SimpleCxx is built and installed
 # first and then is used in the later build of the rest of
 # TribitsExampleProject.  If you comment out -DTPL_ENABLE_SimpleCxx=ON, then
-# it will not build!
-
+# it will not build!  This test also uniquely tests a few other TriBITS features:
+#
+# * <Project>_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES (ensures the directory
+# * install/simple_cxx/lib/cmake/TribitsExProj does not get created and
+# * therefore the file TribitsExProjConfig.cmake does not get installed).
 
 if (TribitsExampleProject_SimpleCxx_External_NAME)
   set_tests_properties(${TribitsExampleProject_SimpleCxx_External_NAME}

tribits/CHANGELOG.md

@@ -4,6 +4,11 @@ ChangeLog for TriBITS
 
 ## 2023-10-25:
 
+* **Added:** New option `<Project>_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES`
+  skips the install of the project-level `<Project>Config.cmake` file.  The
+  default value is ``FALSE`` so as to maintain backward compatibility.  (The
+  project can change the default.)
+
 * **Changed:** External packages/TPLs are now processed at the base project
   scope level.  This allows simple `set()` statements in package module files
   or config files included by `find_package()` to have project-level scope for

tribits/core/installation/add_project_install_commands/CMakeLists.txt

@@ -2,7 +2,8 @@ set(tribits_install_src
   "${${PROJECT_NAME}_TRIBITS_DIR}/${TRIBITS_CMAKE_INSTALLATION_FILES_DIR}")
 
 if ( ${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES
-     AND NOT ${PROJECT_NAME}_ENABLE_INSTALLATION_TESTING
+    AND (NOT ${PROJECT_NAME}_ENABLE_INSTALLATION_TESTING)
+    AND (NOT ${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES)
   )
 
   include(TribitsWriteClientExportFiles)

tribits/core/package_arch/TribitsGlobalMacros.cmake

@@ -597,13 +597,21 @@ macro(tribits_define_global_options_and_define_extra_repos)
   if ("${${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES_DEFAULT}" STREQUAL "")
     set(${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES_DEFAULT OFF)
   endif()
-
   advanced_set(${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES
     ${${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES_DEFAULT}
     CACHE BOOL
     "Determines if ${PROJECT_NAME}Config.cmake and <PACKAGE>Config.cmake files are created or not."
     )
 
+  if ("${${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES_DEFAULT}" STREQUAL "")
+    set(${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES_DEFAULT OFF)
+  endif()
+  advanced_set(${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES
+    ${${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES_DEFAULT}
+    CACHE BOOL
+    "Skip installing the file ${PROJECT_NAME}Config.cmake."
+    )
+
   if (NOT ${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES_DEFAULT)
     # We need to generate the dependency logic for export dependency files if
     # asked.

tribits/doc/build_ref/TribitsBuildReferenceBody.rst

@@ -2816,13 +2816,26 @@ of packages the files are requested for with::
 
   -D <Project>_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_PACKAGES="<pkg0>;<pkg1>"
 
+To only install the package ``<Package>Config.cmake`` files and **not** the
+project-level ``<Project>Config.cmake`` file, configure with::
+
+   -D <Project>_ENABLE_INSTALL_CMAKE_CONFIG_FILES=ON \
+   -D <Project>_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES
+
 NOTES:
 
 * Only enabled packages will have their export files generated.
 
 * One would only want to limit the export files generated for very large
   projects where the cost my be high for doing so.
 
+* One would want to skip the installation of the project-level
+  ``<Project>Config.cmake`` file in cases where the TriBITS project's packages
+  may be built in smaller subsets of packages in different individual CMake
+  project builds where there is no clear completion to the installation of the
+  packages for a given TriBITS project containing a larger collection of
+  packages.
+
 
 Generating a project repo version file
 --------------------------------------

tribits/doc/guides/TribitsCoreDetailedReference.rst

@@ -89,6 +89,7 @@ a given TriBITS project are:
 * `${PROJECT_NAME}_REQUIRES_PYTHON`_
 * `${PROJECT_NAME}_SET_INSTALL_RPATH`_
 * `${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME`_
+* `${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES`_
 * `${PROJECT_NAME}_TEST_CATEGORIES`_
 * `${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS`_
 * `${PROJECT_NAME}_TRACE_ADD_TEST`_
@@ -671,6 +672,19 @@ These options are described below.
   date/time for regular tests added with `tribits_add_test()`_ (which uses a
   raw command with ``add_test()``).
 
+.. _${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES:
+
+**${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES**
+
+  To change the default value of the
+  ``${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES`` to ``TRUE``, for
+  example, for a TriBITS project, set::
+
+    set(${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES_DEFAULT TRUE)
+
+  in the project's `<projectDir>/CMakeLists.txt`_ or
+  `<projectDir>/ProjectName.cmake`_ files.
+
 .. _${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE:
 
 **${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE**