feat: add the version-info tool to print the project info

This tool uses the generated `version.h` file in a small C++ program
to print the project's info, as defined in the project's master
`CMakeLists.txt`.

It also constitutes an example of how to use the `version.h` file and
a simple test to check that the `asap` infrastructure for defining and
building targets is working.

.github/workflows/cmake-build.yml

@@ -215,7 +215,7 @@ jobs:
           execute_process(COMMAND ccache -z)
 
           execute_process(
-            COMMAND cmake --build build --target gtest
+            COMMAND cmake --build build --target all
             RESULT_VARIABLE result
             OUTPUT_VARIABLE output
             ERROR_VARIABLE output

CMakeLists.txt

@@ -233,6 +233,8 @@ endif()
 # Project modules
 # ------------------------------------------------------------------------------
 
+add_subdirectory(tools/version-info)
+
 # Add project modules here
 
 # ------------------------------------------------------------------------------

doc/index.rst

@@ -23,6 +23,7 @@ Last Updated on |date|
    project-development/index
    documentation/index
    library-modules/index
+   tools/index
    license
    changelog.md
    version
@@ -63,6 +64,13 @@ is structured and built from source using `doxygen` and `sphinx`.*
 there, you can also jump to the detailed API documentation of each of those
 modules.*
 
+:doc:`Project Tools <tools/index>`
+----------------------------------
+*get an introduction to the programs and scripts under the `tools` folder,
+specifically made for the `asap` project. These can simplify recurring tasks and
+provide additional insights into the project, and sometimes examples of how to
+use the project artifacts.*
+
 Acknowledgements
 ================
 

doc/tools/index.rst

@@ -0,0 +1,27 @@
+.. Structure conventions
+     # with overline, for parts
+     * with overline, for chapters
+     = for sections
+     - for subsections
+     ^ for sub-subsections
+     " for paragraphs
+
+#############
+Project Tools
+#############
+
+.. |date| date::
+
+Last Updated on |date|
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :hidden:
+
+The `tools` directory under the project root holds project-specific tools.
+Currently we have:
+
+  * Project version info tool: a simple executable written as a C++ program,
+    using the generated `version.h` include file to print the project meta-data
+    defined in the project's cmake file.

tools/version-info/.gitignore

@@ -0,0 +1,2 @@
+# Generated files inside source tree
+src/main.cpp

tools/version-info/CMakeLists.txt

@@ -0,0 +1,88 @@
+# ===------------------------------------------------------------------------===#
+# 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
+# ===------------------------------------------------------------------------===#
+
+# ------------------------------------------------------------------------------
+# Meta information about the this module
+# ------------------------------------------------------------------------------
+
+asap_declare_module(
+  MODULE_NAME
+  "version-info"
+  DESCRIPTION
+  "Print the project's version information."
+  GITHUB_REPO
+  "${META_GITHUB_REPO}"
+  AUTHOR_MAINTAINER
+  "${META_AUTHOR_MAINTAINER}"
+  VERSION_MAJOR
+  "1"
+  VERSION_MINOR
+  "0"
+  VERSION_PATCH
+  "0")
+
+# ==============================================================================
+# Build instructions
+# ==============================================================================
+
+# ------------------------------------------------------------------------------
+# Code generation
+# ------------------------------------------------------------------------------
+
+# Generate version-header
+configure_file(src/main.cpp.in ${CMAKE_CURRENT_SOURCE_DIR}/src/main.cpp)
+
+# ------------------------------------------------------------------------------
+# Main module target
+# ------------------------------------------------------------------------------
+
+set(MODULE_TARGET_NAME "${META_PROJECT_NAME}-${META_MODULE_NAME}")
+
+asap_add_executable(${MODULE_TARGET_NAME} WARNING SOURCES "src/main.cpp")
+
+target_compile_features(${MODULE_TARGET_NAME} PUBLIC cxx_constexpr)
+
+target_include_directories(
+  ${MODULE_TARGET_NAME}
+  PUBLIC $<INSTALL_INTERFACE:include>
+         $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/include>
+  PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+
+# ------------------------------------------------------------------------------
+# Run executable test
+# ------------------------------------------------------------------------------
+
+add_test(
+  NAME version-info
+  COMMAND ${MODULE_TARGET_NAME}
+  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
+
+# ==============================================================================
+# Deployment instructions
+# ==============================================================================
+
+if(${META_PROJECT_ID}_INSTALL)
+  set(TARGETS_EXPORT_NAME "${MODULE_TARGET_NAME}Targets")
+  set(runtime "${MODULE_TARGET_NAME}_runtime")
+  set(dev "${MODULE_TARGET_NAME}_dev")
+
+  # Binaries
+  install(
+    TARGETS ${MODULE_TARGET_NAME}
+    EXPORT "${TARGETS_EXPORT_NAME}"
+    COMPONENT runtime
+    RUNTIME DESTINATION ${ASAP_INSTALL_BIN} COMPONENT ${runtime}
+    LIBRARY DESTINATION ${ASAP_INSTALL_SHARED} COMPONENT ${runtime}
+    ARCHIVE DESTINATION ${ASAP_INSTALL_LIB} COMPONENT ${dev})
+
+  # Docs
+  if(EXISTS ${SPHINX_BUILD_DIR}/${MODULE_TARGET_NAME})
+    install(
+      DIRECTORY ${SPHINX_BUILD_DIR}/${MODULE_TARGET_NAME}
+      DESTINATION ${ASAP_INSTALL_DOC}
+      COMPONENT ${MODULE_TARGET_NAME}_docs)
+  endif()
+endif()

tools/version-info/README.md

@@ -0,0 +1,9 @@
+# Project version information
+
+This is a small executable tool that uses the generated `version.h` C++ include
+file to print the project meta data on the standard output.
+
+Here is an example output:
+
+```
+```

tools/version-info/src/main.cpp.in

@@ -0,0 +1,24 @@
+//===----------------------------------------------------------------------===//
+// 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
+//===----------------------------------------------------------------------===//
+
+#include <iostream>
+
+#include <@META_PROJECT_ID_LOWER@/version.h>
+
+// clang-format off
+using namespace @META_PROJECT_ID_LOWER@::info;
+// clang-format on
+
+auto main(int /*argc*/, char ** /*argv*/) -> int {
+  std::cout << cNameVersion << "\n"
+            << "By " << cAuthor << " @ " << cAuthorOrganization << " ("
+            << cAuthorDomain << ").\n"
+            << std::endl;
+
+  std::cout << cProjectDescription << "\n" << std::endl;
+
+  return 0;
+}