Merge branch 'main' into refactor-types

Author: aedart

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Project's root `CMakeLists.txt`.
 * `dependencies.cmake` and `dev-dependencies.cmake` scripts.
 * `CPM.cmake` script that downloads specified version of [CPM](https://github.com/cpm-cmake/CPM.cmake).
-* `fail_in_source_build()`, `extract_value()`, `requires_arguments()` and `safeguard_properties()` utils functions, in `helpers.cmake`.
+* `fail_in_source_build()`, `extract_value()`, `requires_arguments()` and `safeguard_properties()` utils, in `helpers.cmake`.
 * `dump()`, `dd()` and `var_dump()` in `debug.cmake`.
 * ANSI utils, in `output.cmake`
 * `semver_parse()`, `write_version_file` and `version_from_file()` utils, in `version.cmake`.

CMakeLists.txt

@@ -12,8 +12,8 @@ option(RSP_ENABLE_ANSI "Enable ANSI output" false)
 # -------------------------------------------------------------------------------------------------------------- #
 
 # Append this package's cmake scripts in module path
-list(FIND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" hasModulePath)
-if(${hasModulePath} STREQUAL "-1")
+list(FIND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" has_cmake_scripts_module_path)
+if(has_cmake_scripts_module_path EQUAL -1)
     list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 endif()
 
@@ -48,12 +48,14 @@ project(rsp-cmake-scripts
     HOMEPAGE_URL "https://github.com/rsps/cmake-scripts"
     LANGUAGES NONE
 )
+set("${PROJECT_NAME}_VERSION" "${PROJECT_VERSION}")
+set("${PROJECT_NAME}_SEMVER" "${version_SEMVER}")
 
 # Ensure parent project has modules and other properties available.
-if(NOT CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+if(NOT PROJECT_IS_TOP_LEVEL)
     set(CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH}" PARENT_SCOPE)
-    set("${PROJECT_NAME}_VERSION" "${PROJECT_VERSION}" PARENT_SCOPE)
-    set("${PROJECT_NAME}_SEMVER" "${version_SEMVER}" PARENT_SCOPE)
+    set("${PROJECT_NAME}_VERSION" "${${PROJECT_NAME}_VERSION}" PARENT_SCOPE)
+    set("${PROJECT_NAME}_SEMVER" "${${PROJECT_NAME}_SEMVER}" PARENT_SCOPE)
 endif()
 
 # -------------------------------------------------------------------------------------------------------------- #
@@ -62,7 +64,7 @@ endif()
 
 include("dependencies.cmake")
 
-if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+if(PROJECT_IS_TOP_LEVEL)
     include("dev-dependencies.cmake")
 endif()
 
@@ -82,7 +84,7 @@ endif ()
 # Post-dependencies project setup
 # -------------------------------------------------------------------------------------------------------------- #
 
-if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+if(PROJECT_IS_TOP_LEVEL)
     include("rsp/debug")
     include("rsp/logging")
 endif()

cmake/rsp/helpers.cmake

@@ -90,45 +90,28 @@ if (NOT COMMAND "safeguard_properties")
 
     #! safeguard_properties : Invoke a "risky" callback whilst "safeguarding" properties
     #
-    # Function copies the values of the specified properties, invokes the callback, and
-    # restores the properties' values.
+    # Macro copies the values of the specified properties, invokes the callback, and
+    # restores the properties' original values.
     #
-    # Caution: This function does NOT prevent properties from being force-cached.
+    # Caution: This macro does NOT prevent properties from being force-cached.
     # Environment variables are NOT prevented changed.
     #
-    # Alternatively, consider using cmake's `block()`.
+    # Alternatively, consider using cmake's `block()` or a function with its own variable
+    # scope.
     #
     # @see https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#variables
     # @see https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#environment-variables
     # @see https://cmake.org/cmake/help/latest/command/block.html#block
     #
-    # @param [CALLBACK <command>]           Risky command or macro to be invoked.
-    # @param [PROPERTIES <variable>...]     One or more properties to safeguard.
+    # @param <command> callback     Risky command or macro to be invoked.
+    # @param <list> properties      List of variable names - variables to safeguard from
+    #                               undesired value changes.
     #
-    # @return
-    #       [PROPERTIES <variable>...]      Restored properties
-    #
-    function(safeguard_properties)
-        set(options "") # N/A
-        set(oneValueArgs CALLBACK)
-        set(multiValueArgs PROPERTIES)
-
-        cmake_parse_arguments(INPUT "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
-        requires_arguments("CALLBACK;PROPERTIES" INPUT)
-
-        # ---------------------------------------------------------------------------------------------- #
-
-        # Abort if callback not defined
-        if (NOT COMMAND "${INPUT_CALLBACK}")
-            message(FATAL_ERROR "Callback \"${INPUT_CALLBACK}()\" does not exist")
-        endif ()
-
-        # ---------------------------------------------------------------------------------------------- #
-
+    macro(safeguard_properties callback properties)
         set(prefix "original_")
 
         # Copy each provided property
-        foreach (prop ${INPUT_PROPERTIES})
+        foreach (prop ${properties})
             message(VERBOSE "Safeguarding: ${prop}, original value: ${${prop}}")
 
             set("${prefix}${prop}" "${${prop}}")
@@ -137,17 +120,17 @@ if (NOT COMMAND "safeguard_properties")
         # ---------------------------------------------------------------------------------------------- #
 
         # Invoke the risky callback
-        message(VERBOSE "Invoking risky callback: ${INPUT_CALLBACK}")
-        cmake_language(CALL "${INPUT_CALLBACK}")
+        message(VERBOSE "Invoking risky callback: ${callback}")
+        cmake_language(CALL "${callback}")
 
         # ---------------------------------------------------------------------------------------------- #
 
         # Restore each provided property
-        foreach (prop ${INPUT_PROPERTIES})
+        foreach (prop ${properties})
             message(VERBOSE "Restoring: ${prop} from: ${${prop}}, to original value: ${${prefix}${prop}}")
 
-            # Ensure that property is set on parent scope
-            set("${prop}" "${${prefix}${prop}}" PARENT_SCOPE)
+            # Restore property's original value
+            set("${prop}" "${${prefix}${prop}}")
         endforeach ()
-    endfunction()
+    endmacro()
 endif ()

dependencies.cmake

@@ -4,14 +4,13 @@
 
 include_guard()
 
-function(install_dependencies)
-    message(STATUS "Installing Dependencies for ${PROJECT_NAME}")
+macro(install_dependencies)
+    message(VERBOSE "Installing Dependencies for ${PROJECT_NAME}")
 
     # Avoid building tests for dependencies...
     set(BUILD_TESTING off)
 
     # Add dependencies here...
-    message(STATUS "    N/A")
-
-endfunction()
-safeguard_properties(CALLBACK "install_dependencies" PROPERTIES BUILD_TESTING)
+    message(VERBOSE "    N/A")
+endmacro()
+safeguard_properties("install_dependencies" "BUILD_TESTING")

dev-dependencies.cmake

@@ -7,14 +7,13 @@ include_guard()
 # Include regular dependencies
 include("dependencies.cmake")
 
-function(install_dev_dependencies)
-    message(STATUS "Installing Development Dependencies for ${PROJECT_NAME}")
+macro(install_dev_dependencies)
+    message(VERBOSE "Installing Development Dependencies for ${PROJECT_NAME}")
 
     # Avoid building tests for dependencies...
     set(BUILD_TESTING off)
 
     # Add dev-dependencies here...
-    message(STATUS "    N/A")
-
-endfunction()
-safeguard_properties(CALLBACK "install_dev_dependencies" PROPERTIES BUILD_TESTING)
+    message(VERBOSE "    N/A")
+endmacro()
+safeguard_properties("install_dev_dependencies" "BUILD_TESTING")

docs/+current/index.md

@@ -17,4 +17,44 @@ author: RSP Systems A/S
 
 ## How to install
 
-_TODO: ...incomplete, please review documentation at a later point_
+### Via CPM
+
+If you are using [CPM](https://github.com/cpm-cmake/CPM.cmake), then you can install "CMake Scripts" using the following:
+
+```cmake
+set(RSP_CMAKE_SCRIPTS_VERSION "0.1.0")
+
+CPMAddPackage(
+    NAME "rsp-cmake-scripts"
+    VERSION "${RSP_CMAKE_SCRIPTS_VERSION}"
+    GITHUB_REPOSITORY "rsps/cmake-scripts"
+)
+
+# IMPORTANT: Enable "rsp/*" modules in your project,...
+list(APPEND CMAKE_MODULE_PATH "${rsp-cmake-scripts_SOURCE_DIR}/cmake")
+```
+
+!!! info "`CMAKE_MODULE_PATH`"
+    At the time of this writing, CPM does not automatically support paths appended to `CMAKE_MODULE_PATH`.
+    To make use of this package's cmake modules, via CPM, you **MUST** manually append
+    this package's module path in your top-level `CMakeLists.txt`, as shown in the above install example.
+
+### Via Fetch Content
+
+Alternatively, you can also use cmake's [`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html) module:
+
+```cmake
+set(RSP_CMAKE_SCRIPTS_VERSION "0.1.0")
+
+include(FetchContent)
+FetchContent_Declare(
+    "rsp-cmake-scripts"
+    GIT_REPOSITORY "https://github.com/rsps/cmake-scripts"
+    GIT_TAG "${RSP_CMAKE_SCRIPTS_VERSION}"
+)
+FetchContent_MakeAvailable("rsp-cmake-scripts")
+```
+
+!!! note "Note"
+    "CMake Scripts" depends on [CPM](https://github.com/cpm-cmake/CPM.cmake) for its dependencies. It will
+    automatically be included, even when you install this project using cmake's `FetchContent` module. 

tests/unit/helpers/safeguard_properties_test.cmake

@@ -1,5 +1,6 @@
 include("rsp/testing")
 include("rsp/helpers")
+include("rsp/debug")
 
 define_test_case(
     "Safeguard Properties Test"
@@ -13,18 +14,14 @@ function(can_safeguard_properties)
     set(c "ccc")
 
     function(risky_callback)
+        message(VERBOSE "risky callback invoked (function)")
+
         set(a "1" PARENT_SCOPE)
         set(b "2" PARENT_SCOPE)
         set(c "3" PARENT_SCOPE)
     endfunction()
 
-    safeguard_properties(
-        CALLBACK "risky_callback"
-        PROPERTIES
-            a
-            b
-            c
-    )
+    safeguard_properties("risky_callback" "a;b;c")
 
     # Debug
     #risky_callback()
@@ -33,3 +30,28 @@ function(can_safeguard_properties)
     assert_string_equals("bbb" ${b} MESSAGE "Property b was modified")
     assert_string_equals("ccc" ${c} MESSAGE "Property c was modified")
 endfunction()
+
+define_test("unguarded properties can be changed" "unguarded_properties_can_be_changed")
+function(unguarded_properties_can_be_changed)
+    set(a "aaa")
+    set(b "bbb")
+    set(c "ccc")
+
+    macro(risky_callback)
+        message(NOTICE "risky callback invoked (macro)")
+
+        set(a "1")
+        set(b "2")
+        set(c "3")
+    endmacro()
+
+    # Note: "c" is NOT safeguarded here
+    safeguard_properties("risky_callback" "a;b")
+
+    # Debug
+    #risky_callback()
+
+    assert_string_equals("aaa" ${a} MESSAGE "Property a was modified")
+    assert_string_equals("bbb" ${b} MESSAGE "Property b was modified")
+    assert_string_equals("3" ${c} MESSAGE "Property c SHOULD had been modified")
+endfunction()