diff --git a/.github/workflows/ci-cell.yml b/.github/workflows/ci-cell.yml index 2cf3270..e8c9e48 100644 --- a/.github/workflows/ci-cell.yml +++ b/.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 diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..b5b0893 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,17 @@ +# ReadDebugString - Authors + + +## Major Contributors + +* Matthew Wilson ([mwsis](https://github.com/mwsis)); + + +## Defect reports, fixes and suggestions (for which we are very grateful) + +* \ (yet); + + +Contributions are welcomed. + + + diff --git a/CHANGES.md b/CHANGES.md index e69de29..adf5fe4 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -0,0 +1,19 @@ +# ReadDebugString - Changes + + +## 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; + + + diff --git a/CMakeLists.txt b/CMakeLists.txt index 83d7b93..e35b7ab 100644 --- a/CMakeLists.txt +++ b/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 - $<$,$,$>: + $<$,$,$>: -Werror -Wall -Wextra -pedantic - - -Wno-ignored-qualifiers - -Wno-incompatible-pointer-types-discards-qualifiers - -Wno-unused-parameter > - $<$: + $<$,$>: + -Wno-anonymous-structs + > + $<$: /WX /W4 + + /wd4201 > ) +target_link_options(${PROJECT_NAME} + PRIVATE + $<$:-municode> +) + target_link_libraries(${PROJECT_NAME} $<$:STLSoft::STLSoft> ) diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..539479d --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,41 @@ +# ReadDebugString - Installation and Use + + +## 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 +``` + + + diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000..23ab42d --- /dev/null +++ b/NEWS.md @@ -0,0 +1,10 @@ +# ReadDebugString - News + + +| 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) | + + + diff --git a/README.md b/README.md index ad74804..045c7e6 100644 --- a/README.md +++ b/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 diff --git a/REQUISITES.md b/REQUISITES.md new file mode 100644 index 0000000..bbabb58 --- /dev/null +++ b/REQUISITES.md @@ -0,0 +1,26 @@ +# ReadDebugString - Requisites + + +## 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. + + + diff --git a/main.cpp b/main.cpp index 9760bca..17e2567 100644 --- a/main.cpp +++ b/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 diff --git a/prepare_cmake.sh b/prepare_cmake.sh index 6529aa9..287b129 100755 --- a/prepare_cmake.sh +++ b/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