Update.2

.github/workflows/ci.yml

@@ -5,12 +5,15 @@ on:
     branches:
       - master
       - dev
+      - boilerplate
+      - idiomatic
+      - update
+      - update.2
       - rc1
       - rc2
       - rc3
       - rc4
       - rc5
-      - update
   pull_request:
 
 concurrency:

.sis/project_name.txt

@@ -0,0 +1 @@
+STLSoft

CHANGES.md

@@ -1,4 +1,4 @@
-# **STLSoft** Changes <!-- omit in toc -->
+# STLSoft - CHANGES <!-- omit in toc -->
 
 
 ## 1.11.1-rc5 - 9th August 2026

CMakeLists.txt

@@ -5,7 +5,7 @@
 # Purpose:  Top-level CMake lists file for STLSoft
 #
 # Created:  31st March 2021
-# Updated:  30th July 2026
+# Updated:  7th August 2026
 #
 # ######################################################################## #
 
@@ -14,6 +14,9 @@
 # CMake
 
 cmake_minimum_required(VERSION 3.20 FATAL_ERROR)
+if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.31")
+	cmake_policy(SET CMP0177 NEW)
+endif()
 
 # require out-of-source builds
 file(TO_CMAKE_PATH "${CMAKE_CURRENT_BINARY_DIR}/CMakeLists.txt" LOC_PATH)

EXAMPLES.md

@@ -1,4 +1,4 @@
-# STLSoft Examples <!-- omit in toc -->
+# STLSoft - Examples <!-- omit in toc -->
 
 | Name | Source & Description | Platform | Summary |
 | ---- | -------------------- | -------- | ------- |

KNOWN_ISSUES.md

@@ -3,8 +3,8 @@
 
 ## STLSoft 1.11 Known Issues
 
-* [ ] Deeper API documentation beyond the README Components catalogue remains incomplete (see also [**TODO.md**](./TODO.md)); further documentation work is planned for 1.12+;
-* [ ] Several `unixstl::system_traits` methods are declared but not defined, with the intention to flesh them out from Linux system calls (and provide emulations/workarounds for other architectures); pull requests are welcome;
+* [ ] Deeper API documentation beyond the README Components catalogue remains incomplete (see [**TODO.md**](./TODO.md) **1.11.11**);
+* [ ] Several `unixstl::system_traits` methods are declared but not defined, with the intention to flesh them out from Linux system calls (and provide emulations/workarounds for other architectures); see [**TODO.md**](./TODO.md) **1.11.6**; pull requests are welcome;
 
 
 ## STLSoft 1.11 Suspected Issues

build_cmake.sh

@@ -6,6 +6,8 @@ Basename=$(basename "$ScriptPath")
 CMakeDir=${SIS_CMAKE_BUILD_DIR:-$Dir/_build}
 [[ -n "$MSYSTEM" ]] && DefaultMakeCmd=mingw32-make.exe || DefaultMakeCmd=make
 MakeCmd=${SIS_CMAKE_MAKE_COMMAND:-${SIS_CMAKE_COMMAND:-$DefaultMakeCmd}}
+ProjectNameFile="$Dir/.sis/project_name.txt"
+ProjectName=$(tr -d '[:space:]' < "$ProjectNameFile")
 
 IgnoreRemainingFlagsAndOptions=0
 Targets=()
@@ -103,10 +105,10 @@ else
 
     if [ -z "$Targets" ]; then
 
-      echo "Executing build (via command \`$MakeCmd\`)"
+      echo "Executing build for ${ProjectName} (via command \`$MakeCmd\`)"
     else
 
-      echo "Executing build (via command \`$MakeCmd\`) with specific target(s) $(join_by , "${Targets[@]}")"
+      echo "Executing build for ${ProjectName} (via command \`$MakeCmd\`) with specific target(s) $(join_by , "${Targets[@]}")"
     fi
 
     $MakeCmd ${Targets[*]}

clean_cmake.sh

@@ -6,6 +6,8 @@ Basename=$(basename "$ScriptPath")
 CMakeDir=${SIS_CMAKE_BUILD_DIR:-$Dir/_build}
 [[ -n "$MSYSTEM" ]] && DefaultMakeCmd=mingw32-make.exe || DefaultMakeCmd=make
 MakeCmd=${SIS_CMAKE_MAKE_COMMAND:-${SIS_CMAKE_COMMAND:-$DefaultMakeCmd}}
+ProjectNameFile="$Dir/.sis/project_name.txt"
+ProjectName=$(tr -d '[:space:]' < "$ProjectNameFile")
 
 
 # ##########################################################
@@ -69,7 +71,7 @@ else
     exit 1
   else
 
-    echo "Cleaning build (via command \`$MakeCmd clean\`)"
+    echo "Cleaning ${ProjectName} build (via command \`$MakeCmd clean\`)"
 
     $MakeCmd clean
     status=$?

cmake/BuildType.cmake

@@ -5,7 +5,7 @@
 # Purpose:  CMake module file (for BuildType)
 #
 # Created:  16th October 2019
-# Updated:  28th October 2024
+# Updated:  7th August 2026
 #
 # ######################################################################## #
 
@@ -35,7 +35,7 @@ include(BuildType)
 ]========]
 
 
-if(EXISTS "${CMAKE_SOURCE_DIR}/.git")
+if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/../.git")
 
 	set(DEFAULT_BUILD_TYPE "Debug")
 else()
@@ -47,8 +47,8 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
 
 	message(STATUS "Setting build type to '${DEFAULT_BUILD_TYPE}' as none was specified.")
 
-	set(CACHE CMAKE_BUILD_TYPE "${DEFAULT_BUILD_TYPE}"
-		STRING "Choose the type of build." FORCE
+	set(CMAKE_BUILD_TYPE "${DEFAULT_BUILD_TYPE}" CACHE STRING
+		"Choose the type of build." FORCE
 	)
 
 	# Set the possible values of build type for cmake-gui
@@ -58,4 +58,3 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
 endif()
 
 # ############################## end of file ############################# #
-

cmake/TargetMacros.cmake

@@ -6,6 +6,15 @@ function(define_automated_test_program program_name entry_point_source_name)
 		${entry_point_source_name}
 	)
 
+	# Prefer this tree's headers over any installed STLSoft. On Apple Clang,
+	# /usr/local/include is searched before -isystem paths, so includes that
+	# arrive only via imported deps (e.g. xTests) can otherwise shadow us.
+	set_property(TARGET ${program_name} PROPERTY NO_SYSTEM_FROM_IMPORTED TRUE)
+	target_include_directories(${program_name}
+		BEFORE PRIVATE
+			${CMAKE_SOURCE_DIR}/include
+	)
+
 	target_link_libraries(${program_name}
 		$<$<BOOL:${cstring_FOUND}>:cstring::core>
 		$<$<BOOL:${shwild_FOUND}>:shwild::core>
@@ -65,6 +74,15 @@ function(define_example_program program_name entry_point_source_name)
 		${entry_point_source_name}
 	)
 
+	# Prefer this tree's headers over any installed STLSoft. On Apple Clang,
+	# /usr/local/include is searched before -isystem paths, so includes that
+	# arrive only via imported deps (e.g. xTests) can otherwise shadow us.
+	set_property(TARGET ${program_name} PROPERTY NO_SYSTEM_FROM_IMPORTED TRUE)
+	target_include_directories(${program_name}
+		BEFORE PRIVATE
+			${CMAKE_SOURCE_DIR}/include
+	)
+
 	target_link_libraries(${program_name}
 		$<$<BOOL:${shwild_FOUND}>:shwild::core>
 		$<$<BOOL:${cstring_FOUND}>:cstring::core>

ctest_cmake.sh

@@ -0,0 +1,108 @@
+#! /bin/bash
+
+ScriptPath=$0
+Dir=$(cd $(dirname "$ScriptPath"); pwd)
+Basename=$(basename "$ScriptPath")
+CMakeDir=${SIS_CMAKE_BUILD_DIR:-$Dir/_build}
+[[ -n "$MSYSTEM" ]] && DefaultMakeCmd=mingw32-make.exe || DefaultMakeCmd=make
+MakeCmd=${SIS_CMAKE_MAKE_COMMAND:-${SIS_CMAKE_COMMAND:-$DefaultMakeCmd}}
+ProjectNameFile="$Dir/.sis/project_name.txt"
+ProjectName=$(tr -d '[:space:]' < "$ProjectNameFile")
+
+CMakeVerbose=
+RunMake=1
+
+
+# ##########################################################
+# command-line handling
+
+while [[ $# -gt 0 ]]; do
+
+  case $1 in
+    --no-make|-M)
+
+      RunMake=0
+      ;;
+    --verbose|-V)
+
+      CMakeVerbose=--verbose
+      ;;
+    --help)
+
+      [ -f "$Dir/.sis/script_info_lines.txt" ] && cat "$Dir/.sis/script_info_lines.txt"
+      cat << EOF
+Runs CMake's CTest test program(s)
+
+$ScriptPath [ ... flags/options ... ]
+
+Flags/options:
+
+    behaviour:
+
+    -M
+    --no-make
+        does not execute CMake and make before running tests
+
+    -V
+    --verbose
+        verbose test output
+
+
+    standard flags:
+
+    --help
+        displays this help and terminates
+
+EOF
+
+      exit 0
+      ;;
+    *)
+
+      >&2 echo "$ScriptPath: unrecognised argument '$1'; use --help for usage"
+
+      exit 1
+      ;;
+  esac
+
+  shift
+done
+
+
+# ##########################################################
+# main()
+
+status=0
+
+if [ $RunMake -ne 0 ]; then
+
+  echo "Executing build for ${ProjectName} (via command \`$MakeCmd\`) and then running all component and unit test programs"
+
+  mkdir -p $CMakeDir || exit 1
+
+  cd $CMakeDir
+
+  $MakeCmd
+  status=$?
+
+  cd ->/dev/null
+else
+
+  if [ ! -d "$CMakeDir" ] || [ ! -f "$CMakeDir/CMakeCache.txt" ] || [ ! -d "$CMakeDir/CMakeFiles" ]; then
+
+    >&2 echo "$ScriptPath: cannot run in '--no-make' mode without a previous successful build step"
+  fi
+fi
+
+if [ $status -eq 0 ]; then
+
+  echo "Running CMake tests"
+
+  ctest --test-dir $CMakeDir $CMakeVerbose
+  status=$?
+fi
+
+exit $status
+
+
+# ############################## end of file ############################# #

examples/CMakeLists.txt

@@ -1,5 +1,5 @@
 
-include_directories(${CMAKE_SOURCE_DIR}/include)
+include_directories(BEFORE ${CMAKE_SOURCE_DIR}/include)
 
 if(_BUILD_AS_UNIX)
 

execute_performance_tests.sh

@@ -6,6 +6,8 @@ Basename=$(basename "$ScriptPath")
 CMakeDir=${SIS_CMAKE_BUILD_DIR:-$Dir/_build}
 [[ -n "$MSYSTEM" ]] && DefaultMakeCmd=mingw32-make.exe || DefaultMakeCmd=make
 MakeCmd=${SIS_CMAKE_MAKE_COMMAND:-${SIS_CMAKE_COMMAND:-$DefaultMakeCmd}}
+ProjectNameFile="$Dir/.sis/project_name.txt"
+ProjectName=$(tr -d '[:space:]' < "$ProjectNameFile")
 
 ExpandWidth=0
 ListOnly=0
@@ -85,7 +87,7 @@ status=0
 if [ $RunMake -ne 0 ]; then
 
   if [ $ListOnly -eq 0 ]; then
-    echo "Executing make and then running all performance test programs"
+    echo "Executing build (via command \`$MakeCmd\`) and then running all ${ProjectName} performance test programs"
 
     mkdir -p $CMakeDir || exit 1
 
@@ -110,10 +112,10 @@ if [ $status -eq 0 ]; then
 
   if [ $ListOnly -ne 0 ]; then
 
-    echo "Listing all performance test programs"
+    echo "Listing all ${ProjectName} performance test programs"
   else
 
-    echo "Running all performance test programs"
+    echo "Running all ${ProjectName} performance test programs"
   fi
 
   for f in $(find "$CMakeDir" -type f '(' -name 'test_performance*' -o -name 'test.performance.*' ')' -exec test -x {} \; -print | sort)

prepare_cmake.sh

@@ -4,8 +4,17 @@ ScriptPath=$0
 Dir=$(cd $(dirname "$ScriptPath"); pwd)
 Basename=$(basename "$ScriptPath")
 CMakeDir=${SIS_CMAKE_BUILD_DIR:-$Dir/_build}
-[[ -n "$MSYSTEM" ]] && DefaultMakeCmd=mingw32-make.exe || DefaultMakeCmd=make
+if [[ -n "$MSYSTEM" ]]; then
+
+  DefaultMakeCmd=mingw32-make.exe
+  MinGW=1
+else
+
+  DefaultMakeCmd=make
+fi
 MakeCmd=${SIS_CMAKE_MAKE_COMMAND:-${SIS_CMAKE_COMMAND:-$DefaultMakeCmd}}
+ProjectNameFile="$Dir/.sis/project_name.txt"
+ProjectName=$(tr -d '[:space:]' < "$ProjectNameFile")
 
 
 Configuration=Release
@@ -152,7 +161,7 @@ mkdir -p $CMakeDir || exit 1
 
 cd $CMakeDir
 
-echo "Executing CMake (in ${CMakeDir})"
+echo "Executing CMake for ${ProjectName} (in ${CMakeDir})"
 
 if [ $ExamplesDisabled -eq 0 ]; then CMakeBuildExamplesFlag="ON" ; else CMakeBuildExamplesFlag="OFF" ; fi
 if [ $MSVC_MT -eq 0 ]; then CMakeMsvcMtFlag="OFF" ; else CMakeMsvcMtFlag="ON" ; fi
@@ -195,7 +204,7 @@ status=0
 
 if [ $RunMake -ne 0 ]; then
 
-  echo "Executing build (via command \`$MakeCmd\`)"
+  echo "Executing build for ${ProjectName} (via command \`$MakeCmd\`)"
 
   $MakeCmd
   status=$?

remove_cmake_artefacts.sh

@@ -4,6 +4,8 @@ ScriptPath=$0
 Dir=$(cd $(dirname "$ScriptPath"); pwd)
 Basename=$(basename "$ScriptPath")
 CMakeDir=${SIS_CMAKE_BUILD_DIR:-$Dir/_build}
+ProjectNameFile="$Dir/.sis/project_name.txt"
+ProjectName=$(tr -d '[:space:]' < "$ProjectNameFile")
 
 Directories=(
   CMakeFiles
@@ -100,7 +102,7 @@ if [ ! -d "$CMakeDir" ]; then
   exit 0
 else
 
-  echo "Removing all cmake artefacts in '$CMakeDir'"
+  echo "Removing all ${ProjectName} cmake artefacts in '$CMakeDir'"
 
   num_dirs_removed=0
   num_files_removed=0

run_all_examples.sh

@@ -6,6 +6,8 @@ Basename=$(basename "$ScriptPath")
 CMakeDir=${SIS_CMAKE_BUILD_DIR:-$Dir/_build}
 [[ -n "$MSYSTEM" ]] && DefaultMakeCmd=mingw32-make.exe || DefaultMakeCmd=make
 MakeCmd=${SIS_CMAKE_MAKE_COMMAND:-${SIS_CMAKE_COMMAND:-$DefaultMakeCmd}}
+ProjectNameFile="$Dir/.sis/project_name.txt"
+ProjectName=$(tr -d '[:space:]' < "$ProjectNameFile")
 
 ListOnly=0
 RunMake=1
@@ -148,7 +150,7 @@ if [ $RunMake -ne 0 ]; then
 
   if [ $ListOnly -eq 0 ]; then
 
-    echo "Executing build (via command \`$MakeCmd\`) and then running all example programs"
+    echo "Executing build (via command \`$MakeCmd\`) and then running all ${ProjectName} example programs"
 
     mkdir -p $CMakeDir || exit 1
 
@@ -180,10 +182,10 @@ if [ $status -eq 0 ]; then
 
   if [ $ListOnly -ne 0 ]; then
 
-    echo "Listing all example programs"
+    echo "Listing all ${ProjectName} example programs"
   else
 
-    echo "Running all example programs"
+    echo "Running all ${ProjectName} example programs"
   fi
 
   for f in $(find "$CMakeDir/examples" -type f -exec test -x {} \; -print | sort)