feat: enhance configure logs with project/module nesting hierarchy

Track the projects/modules nesting level with a hierarchy stack updated
when we enter/exit a project/module. Most of the management is done
automatically as helper functions get called to add modules or external
packages. Some of the boilerplate (minimal) is still manual:

* In the top-level `CMakeLists.txt`, the project needs to pushed at the
beginning and popped at the end.
* In each module `CMakeLists.txt`, the module needs to be pushed at
the start and popped at the end.

Use the `ASAP_LOG_PROJECT_HIERARCHY` to get a string that contains
the nesting hierarchy.

CMakeLists.txt

@@ -22,6 +22,9 @@ if(NOT CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR
    AND EXISTS "${CMAKE_SOURCE_DIR}/cmake")
   list(PREPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 endif()
+# Include the log helpers module early so we can use early for logging the
+# project hierarchy
+include(LogHelpers)
 
 # ------------------------------------------------------------------------------
 # Project description and (meta) information
@@ -64,9 +67,9 @@ if(NOT DEFINED ${META_PROJECT_ID}_IS_MASTER_PROJECT)
   endif()
 endif()
 
-message(
-  "=> Project : ${META_NAME_VERSION} (IS_MASTER: ${${META_PROJECT_ID}_IS_MASTER_PROJECT})"
-)
+# Push the project on the hierarchy stack after we have determined if it is a
+# master or a sub-project.
+asap_push_project(${META_PROJECT_NAME})
 
 # ------------------------------------------------------------------------------
 # Project configuration options
@@ -254,3 +257,5 @@ if(${META_PROJECT_ID}_IS_MASTER_PROJECT)
   # Enable this target when the project has source files (.cpp)
   # asap_create_clang_tidy_targets()
 endif()
+
+asap_pop_project(${META_PROJECT_NAME})

cmake/AsapTargets.cmake

@@ -55,9 +55,14 @@ macro(asap_declare_module)
   set(META_MODULE_VERSION             "${META_MODULE_VERSION_MAJOR}.${META_MODULE_VERSION_MINOR}.${META_MODULE_VERSION_PATCH}")
   set(META_MODULE_NAME_VERSION        "${META_MODULE_PROJECT_NAME} v${META_MODULE_VERSION}")
   # cmake-format: on
-  message(
-    "=> [module: ${META_PROJECT_NAME}/${META_MODULE_NAME} ${META_MODULE_VERSION}]"
-  )
+
+  # Check if the module has been pushed on top of the hierarchy stack
+  if(NOT ASAP_LOG_PROJECT_HIERARCHY MATCHES "(${META_MODULE_NAME})")
+    message(
+      AUTHOR_WARNING
+        "Can't find module `${META_MODULE_NAME}` on the hierarchy stack. "
+        "Please make sure it has been pushed with asap_push_module().")
+  endif()
 
 endmacro()
 

cmake/CPM.cmake

@@ -33,3 +33,26 @@ if(NOT CURRENT_CPM_VERSION VERSION_EQUAL 0.35.6)
   endif()
   include(${CPM_DOWNLOAD_LOCATION})
 endif()
+
+# This is a wrapper function around CPM `cpmaddpackage` to automatically
+# push/pop the package on the hierarchy stack for logging. Use it instead of
+# calling CPM.
+function(asap_add_package)
+  set(options)
+  set(oneValueArgs NAME)
+  set(multiValueArgs)
+
+  cmake_parse_arguments(x "${options}" "${oneValueArgs}" "${multiValueArgs}"
+                        ${ARGN})
+
+  if(NOT DEFINED x_NAME)
+    message(
+      FATAL_ERROR
+        "Package name is required. Refer to CPM docs for the full usage.")
+    return()
+  endif()
+  asap_push_module(${x_NAME})
+  cpmaddpackage(NAME ${x_NAME} ${ARGN})
+  asap_pop_module(${x_NAME})
+
+endfunction()

cmake/LogHelpers.cmake

@@ -0,0 +1,73 @@
+# ===-----------------------------------------------------------------------===#
+# Distributed under the 3-Clause BSD License. See accompanying file LICENSE or
+# copy at https://opensource.org/licenses/BSD-3-Clause).
+# SPDX-License-Identifier: BSD-3-Clause
+# ===-----------------------------------------------------------------------===#
+
+# ------------------------------------------------------------------------------
+# Helpers to enhance progress reporting in the cmake output log.
+#
+# This module defines a global variable: `ASAP_LOG_PROJECT_HIERARCHY` that holds
+# a string with the current project/module nesting hierarchy. It can be used in
+# cmake `message` calls.
+#
+# Maintenance of the nesting hierarchy is done with the following macros:
+#
+# * asap_push_project(project_name)
+# * asap_pop_project(project_name)
+# * asap_push_module(module_name)
+# * asap_pop_module(module_name)
+#
+# They must be called at the start(push) and end(pop) of a project/module cmake
+# script to keep the hierarchy correct.
+# ------------------------------------------------------------------------------
+
+if(NOT DEFINED ASAP_LOG_PROJECT_HIERARCHY)
+  set(ASAP_LOG_PROJECT_HIERARCHY_STACK "")
+  set(ASAP_LOG_PROJECT_HIERARCHY "")
+endif()
+
+macro(asap_push_project project_name)
+  list(APPEND ASAP_LOG_PROJECT_HIERARCHY_STACK "[${project_name}]")
+  list(JOIN ASAP_LOG_PROJECT_HIERARCHY_STACK " > " ASAP_LOG_PROJECT_HIERARCHY)
+  list(LENGTH ASAP_LOG_PROJECT_HIERARCHY_STACK depth)
+  if(${META_PROJECT_ID}_IS_MASTER_PROJECT)
+    message("=> [${depth}] in project ${ASAP_LOG_PROJECT_HIERARCHY} (master)")
+  else()
+    message(
+      "=> [${depth}] in project ${ASAP_LOG_PROJECT_HIERARCHY} (sub-project)")
+  endif()
+endmacro()
+
+macro(asap_pop_project project_name)
+  list(POP_BACK ASAP_LOG_PROJECT_HIERARCHY_STACK removed)
+  if(NOT removed STREQUAL "[${project_name}]")
+    message(
+      FATAL_ERROR
+        "Project [${removed}] was pushed but not popped, please fix this")
+  endif()
+  list(JOIN ASAP_LOG_PROJECT_HIERARCHY_STACK " > " ASAP_LOG_PROJECT_HIERARCHY)
+  list(LENGTH ASAP_LOG_PROJECT_HIERARCHY_STACK depth)
+  if(NOT ${depth} EQUAL 0)
+    message(".. [${depth}] back to ${ASAP_LOG_PROJECT_HIERARCHY}")
+  endif()
+endmacro()
+
+macro(asap_push_module module_name)
+  list(APPEND ASAP_LOG_PROJECT_HIERARCHY_STACK "(${module_name})")
+  list(JOIN ASAP_LOG_PROJECT_HIERARCHY_STACK " > " ASAP_LOG_PROJECT_HIERARCHY)
+  list(LENGTH ASAP_LOG_PROJECT_HIERARCHY_STACK depth)
+  message("=> [${depth}] in module ${ASAP_LOG_PROJECT_HIERARCHY}")
+endmacro()
+
+macro(asap_pop_module module_name)
+  list(POP_BACK ASAP_LOG_PROJECT_HIERARCHY_STACK removed)
+  if(NOT removed STREQUAL "(${module_name})")
+    message(
+      FATAL_ERROR
+        "Module [${removed}] was pushed but not popped, please fix this")
+  endif()
+  list(JOIN ASAP_LOG_PROJECT_HIERARCHY_STACK " > " ASAP_LOG_PROJECT_HIERARCHY)
+  list(LENGTH ASAP_LOG_PROJECT_HIERARCHY_STACK depth)
+  message(".. [${depth}] back to ${ASAP_LOG_PROJECT_HIERARCHY}")
+endmacro()

third_party/CMakeLists.txt

@@ -4,4 +4,22 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # ===-----------------------------------------------------------------------===#
 
-message("=> [third-party modules]")
+message(STATUS "${ASAP_LOG_PROJECT_HIERARCHY} >> third-party modules")
+
+# Call `asap_add_package` to add third party packages using CPM, while
+# automatically adding/removing them to the project hierarchy stack.
+#
+# Refer to https://github.com/cpm-cmake/CPM.cmake for the full usage.
+#
+# Example:
+# ~~~
+# asap_add_package(
+#   NAME
+#   magic_enum
+#   GIT_TAG
+#   master
+#   GITHUB_REPOSITORY
+#   abdes/magic_enum
+#   OPTIONS
+#   "MAGIC_ENUM_OPT_INSTALL ON")
+# ~~~

tools/version-info/CMakeLists.txt

@@ -4,13 +4,16 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # ===------------------------------------------------------------------------===#
 
+set(my_name "version-info")
+asap_push_module("${my_name}")
+
 # ------------------------------------------------------------------------------
 # Meta information about the this module
 # ------------------------------------------------------------------------------
 
 asap_declare_module(
   MODULE_NAME
-  "version-info"
+  "${my_name}"
   DESCRIPTION
   "Print the project's version information."
   GITHUB_REPO
@@ -86,3 +89,5 @@ if(${META_PROJECT_ID}_INSTALL)
       COMPONENT ${MODULE_TARGET_NAME}_docs)
   endif()
 endif()
+
+asap_pop_module("${my_name}")