CMake fixes

.github/workflows/ci-cell.yml

@@ -39,6 +39,12 @@ jobs:
             mingw-w64-x86_64-cmake
             mingw-w64-x86_64-make
 
+      - name: Checkout STLSoft
+        shell: bash
+        run: |
+          set -euo pipefail
+          git clone --depth 1 https://github.com/synesissoftware/STLSoft "$RUNNER_TEMP/stlsoft"
+
       - name: Configure
         shell: bash
         run: |
@@ -49,9 +55,11 @@ jobs:
               -DCMAKE_BUILD_TYPE="${{ inputs.build-type }}" \
               -DCMAKE_C_COMPILER=gcc \
               -DCMAKE_CXX_COMPILER=g++ \
+              -DSTLSOFT="$RUNNER_TEMP/stlsoft" \
               -DBUILD_TESTING=OFF
           else
             cmake -B build -S . \
+              -DSTLSOFT="$RUNNER_TEMP/stlsoft" \
               -DBUILD_TESTING=OFF
           fi
 
@@ -86,4 +94,4 @@ jobs:
           set -euo pipefail
           PREFIX="${RUNNER_TEMP}/install-prefix"
           PROJECT="$(tr -d '[:space:]' < .sis/project_name.txt)"
-          "$PREFIX/bin/${PROJECT}.exe"
+          "$PREFIX/bin/${PROJECT}.exe" --version

AUTHORS.md

@@ -0,0 +1,17 @@
+# ReadDebugString - Authors <!-- omit in toc -->
+
+
+## Major Contributors
+
+* Matthew Wilson ([mwsis](https://github.com/mwsis));
+
+
+## Defect reports, fixes and suggestions (for which we are very grateful)
+
+* \<none> (yet);
+
+
+Contributions are welcomed.
+
+
+<!-- ########################### end of file ########################### -->

CHANGES.md

@@ -0,0 +1,19 @@
+# ReadDebugString - Changes <!-- omit in toc -->
+
+
+## 0.0.1 - 23rd August 2026
+
+* Improved CMake flexibility for uninstalled **STLSoft** source trees supplied via **STLSOFT**;
+* Added validation and an imported **STLSoft::STLSoft** target for local STLSoft source trees;
+* Added Windows **cl** and MinGW CI configuration with STLSoft source checkout;
+* Added an installation smoke test using **--version** so the long-running reader is not started;
+
+
+## 0.0.0 - 16th August 2026
+
+* Added the initial Windows-only **ReadDebugString** executable scaffold;
+* Added **--help** and **--version** command-line handling;
+* Added CMake configuration, helper scripts, and editor settings;
+
+
+<!-- ########################### end of file ########################### -->

CMakeLists.txt

@@ -144,17 +144,34 @@ endif()
 
 # ############################
 # STLSoft
+#
+# NOTE: This is resolved before other dependencies because imported targets
+# may reference STLSoft::STLSoft in their link interfaces.
 
 if(DEFINED STLSOFT)
 
 	message("-- STLSOFT provided as CMake variable with value '${STLSOFT}'")
-
-	set(STLSOFT_INCLUDE_DIR ${STLSOFT}/include)
+	set(STLSOFT_INCLUDE_DIR "${STLSOFT}/include")
 elseif(DEFINED ENV{STLSOFT})
 
 	message("-- STLSOFT provided as environment variable with value '$ENV{STLSOFT}'")
+	set(STLSOFT_INCLUDE_DIR "$ENV{STLSOFT}/include")
+endif()
+
+if(DEFINED STLSOFT_INCLUDE_DIR)
+
+	if(NOT IS_DIRECTORY "${STLSOFT_INCLUDE_DIR}")
+
+		message(FATAL_ERROR "STLSoft include directory not found: ${STLSOFT_INCLUDE_DIR}")
+	endif()
 
-	set(STLSOFT_INCLUDE_DIR $ENV{STLSOFT}/include)
+	if(NOT TARGET STLSoft::STLSoft)
+
+		add_library(STLSoft::STLSoft INTERFACE IMPORTED GLOBAL)
+		set_target_properties(STLSoft::STLSoft PROPERTIES
+			INTERFACE_INCLUDE_DIRECTORIES "${STLSOFT_INCLUDE_DIR}"
+		)
+	endif()
 else()
 
 	set(STLSoft_REQUIRED_VERSION_ 1.11.1)
@@ -166,7 +183,7 @@ endif()
 
 if(DEFINED STLSOFT_INCLUDE_DIR)
 
-	include_directories(${STLSOFT_INCLUDE_DIR})
+	include_directories("${STLSOFT_INCLUDE_DIR}")
 endif()
 
 
@@ -190,18 +207,24 @@ add_executable(${PROJECT_NAME}
 
 target_compile_options(${PROJECT_NAME}
 	PRIVATE
-		$<$<OR:$<C_COMPILER_ID:Clang>,$<C_COMPILER_ID:AppleClang>,$<C_COMPILER_ID:GNU>>:
+		$<$<OR:$<CXX_COMPILER_ID:Clang>,$<CXX_COMPILER_ID:AppleClang>,$<CXX_COMPILER_ID:GNU>>:
 			-Werror -Wall -Wextra -pedantic
-
-			-Wno-ignored-qualifiers
-			-Wno-incompatible-pointer-types-discards-qualifiers
-			-Wno-unused-parameter
 		>
-		$<$<C_COMPILER_ID:MSVC>:
+		$<$<OR:$<CXX_COMPILER_ID:Clang>,$<CXX_COMPILER_ID:AppleClang>>:
+			-Wno-anonymous-structs
+		>
+		$<$<CXX_COMPILER_ID:MSVC>:
 			/WX /W4
+
+			/wd4201
 		>
 )
 
+target_link_options(${PROJECT_NAME}
+	PRIVATE
+		$<$<CXX_COMPILER_ID:GNU>:-municode>
+)
+
 target_link_libraries(${PROJECT_NAME}
 	$<$<STREQUAL:${STLSOFT_INCLUDE_DIR},>:STLSoft::STLSoft>
 )

INSTALL.md

@@ -0,0 +1,41 @@
+# ReadDebugString - Installation and Use <!-- omit in toc -->
+
+
+## Building
+
+The primary build method is **CMake**. From a Visual Studio developer
+environment:
+
+```powershell
+cmake -S . -B _build
+cmake --build _build --config Release
+```
+
+If **STLSoft** is not installed as a CMake package, provide its source-tree
+root:
+
+```powershell
+cmake -S . -B _build -DSTLSOFT=C:\path\to\STLSoft
+cmake --build _build --config Release
+```
+
+The resulting executable is installed with:
+
+```powershell
+cmake --install _build --config Release
+```
+
+
+## Command-line use
+
+The program is intended to remain running while it reads messages from the
+Windows debugger. Use `--help` or `--version` for commands that terminate
+immediately:
+
+```powershell
+ReadDebugString.exe --help
+ReadDebugString.exe --version
+```
+
+
+<!-- ########################### end of file ########################### -->

NEWS.md

@@ -0,0 +1,10 @@
+# ReadDebugString - News <!-- omit in toc -->
+
+
+| Date                | News Item |
+| ------------------- | --------- |
+| 23rd August 2026    | [0.0.1 released](https://github.com/sistools/ReadDebugString/releases/tag/0.0.1) |
+| 16th August 2026    | [0.0.0 released](https://github.com/sistools/ReadDebugString/releases/tag/0.0.0) |
+
+
+<!-- ########################### end of file ########################### -->

README.md

@@ -42,6 +42,8 @@ cmake -S . -B _build
 cmake --build _build --config Release
 ```
 
+Detailed installation and usage instructions are in [INSTALL.md](./INSTALL.md).
+
 
 ## Components
 
@@ -50,8 +52,8 @@ The project creates a single executable program, **ReadDebugString**.
 
 ## Examples
 
-The current scaffold does not yet expose command-line options or produce
-debugger output.
+The program supports `--help` and `--version`. Its debugger message-reading
+behaviour is still being developed.
 
 
 ## Project Information

REQUISITES.md

@@ -0,0 +1,26 @@
+# ReadDebugString - Requisites <!-- omit in toc -->
+
+
+## Introduction
+
+Building **ReadDebugString** requires **CMake** 3.20 or later and a Windows
+C++ toolchain supporting C++17.
+
+
+## Required dependencies
+
+**ReadDebugString** depends on:
+
+* [**STLSoft**](https://github.com/synesissoftware/STLSoft) 1.11.1 or later;
+
+An installed **STLSoft** CMake package is used by default. An uninstalled
+source tree may be supplied through the **STLSOFT** CMake variable, the
+**STLSOFT** environment variable, or **prepare_cmake.sh --stlsoft-root-dir**.
+
+
+## Operating system
+
+The program targets Microsoft Windows and uses the Windows debugger APIs.
+
+
+<!-- ########################### end of file ########################### -->

main.cpp

@@ -34,6 +34,9 @@
 
 union Payload
 {
+#if defined(__GNUC__) && !defined(__clang__)
+    __extension__
+#endif
     struct
     {
         DWORD   pid;
@@ -90,7 +93,7 @@ void run()
     winstl::event   ev_buffer_ready(L"DBWIN_BUFFER_READY", false, false);
     winstl::event   ev_data_ready(L"DBWIN_DATA_READY", false, false);
 
-    HANDLE          hFileMap    =   CreateFileMappingA(INVALID_HANDLE_VALUE, NULL, PAGE_READWRITE, 0, sizeof(Payload), "DBWIN_BUFFER");
+    HANDLE const    hFileMap    =   CreateFileMappingA(INVALID_HANDLE_VALUE, NULL, PAGE_READWRITE, 0, sizeof(Payload), "DBWIN_BUFFER");
 
     if (NULL == hFileMap)
     {
@@ -149,7 +152,7 @@ void run()
             }
             else
             {
-                if (r > STLSOFT_NUM_ELEMENTS(msg) - 3)
+                if (r > int(STLSOFT_NUM_ELEMENTS(msg) - 3))
                 {
                     msg[STLSOFT_NUM_ELEMENTS(msg) - 3] = '\r';
                     msg[STLSOFT_NUM_ELEMENTS(msg) - 2] = '\n';
@@ -220,6 +223,8 @@ int wmain(int argc, wchar_t* argv[])
 
             run();
 
+#ifndef NDEBUG
+
             fwprintf(
                 stderr
             ,   L"%.*s: %s:%d: UNEXPECTED\n"
@@ -230,6 +235,7 @@ int wmain(int argc, wchar_t* argv[])
             ::DebugBreak();
 
             return EXIT_FAILURE;
+#endif
         default:
 
             std::wcerr

prepare_cmake.sh

@@ -17,7 +17,7 @@ ProjectNameFile="$Dir/.sis/project_name.txt"
 ProjectName=$(tr -d '[:space:]' < "$ProjectNameFile")
 
 Configuration=Release
-CStandard=
+CxxStandard=
 MSVC_MT=0
 MinGW="${MinGW:=0}"
 RunMake=0
@@ -50,16 +50,16 @@ fi
 while [[ $# -gt 0 ]]; do
 
   case $1 in
-    --c-standard)
+    --cxx-standard)
 
       shift
-      CStandard=$1
-      case $CStandard in
-        99|11|17|23)
+      CxxStandard=$1
+      case $CxxStandard in
+        98|11|14|17|20|23)
           ;;
         *)
 
-          >&2 echo "$ScriptPath: ${SisClr_Red}${SisClr_Bold}invalid C standard '$CStandard'${SisClr_None}; expected 99, 11, 17, or 23"
+          >&2 echo "$ScriptPath: ${SisClr_Red}${SisClr_Bold}invalid C++ standard '$CxxStandard'${SisClr_None}; expected 98, 11, 14, 17, 20, or 23"
 
           exit 1
           ;;
@@ -172,7 +172,7 @@ cd $CMakeDir
 
 echo "Executing CMake for ${SisClr_Blue}${SisClr_Bold}${ProjectName}${SisClr_None} (in ${SisClr_Blue}${SisClr_Bold}${CMakeDir}${SisClr_None})"
 
-if [ -z "$CStandard" ]; then CMakeCStandardVariable="" ; else CMakeCStandardVariable="-DCMAKE_C_STANDARD=$CStandard" ; fi
+if [ -z "$CxxStandard" ]; then CMakeCStandardVariable="" ; else CMakeCStandardVariable="-DCMAKE_C_STANDARD=$CxxStandard" ; fi
 if [ $MSVC_MT -eq 0 ]; then CMakeMsvcMtFlag="OFF" ; else CMakeMsvcMtFlag="ON" ; fi
 if [ -z "$STLSoftDirGiven" ]; then CMakeSTLSoftVariable="" ; else CMakeSTLSoftVariable="-DSTLSOFT=$STLSoftDirGiven/" ; fi
 if [ $TestingDisabled -eq 0 ]; then CMakeBuildTestingFlag="ON" ; else CMakeBuildTestingFlag="OFF" ; fi