1.11.1-rc8

.gitattributes

@@ -3,6 +3,11 @@
 # Sources: GitHub Docs (line endings), git-scm gitattributes (diff=cpp),
 # gitattributes/gitattributes C++.gitattributes + Common.gitattributes,
 # github-linguist overrides.
+#
+# Linguist language-bar policy (Synesis): classify public C API headers as C
+# and *.cmake as CMake scripts; keep helper scripts, IDE project files, and
+# CMakeLists.txt config out of the advertised language mix. Prefer
+# -linguist-detectable over linguist-detectable=false.
 
 # Default: detect text, normalize to LF in the repository
 * text=auto
@@ -97,3 +102,25 @@ TODO text
 # --- GitHub Linguist ---
 **/build/** linguist-generated
 **/cmake-build-*/** linguist-generated
+
+# Classification (C-primary / C API with C++ tests; *.cmake as CMake scripts)
+*.c linguist-language=C
+*.cmake linguist-language=CMake
+*.cpp linguist-language=C++
+*.cxx linguist-language=C++
+*.h linguist-language=C
+*.hpp linguist-language=C++
+*.hxx linguist-language=C++
+
+# Keep the bar on library languages (helpers / legacy IDE / docs /
+# CMakeLists.txt config; leave *.cmake detectable as CMake)
+*.cmd -linguist-detectable
+*.dsp -linguist-detectable
+*.dsw -linguist-detectable
+*.html -linguist-detectable
+*.sh -linguist-detectable
+*.sln -linguist-detectable
+*.vcxproj -linguist-detectable
+*.vimrc -linguist-detectable
+CMakeLists.txt -linguist-detectable
+makefile -linguist-detectable

.github/workflows/ci-cell.yml

@@ -478,7 +478,7 @@ jobs:
           if [ "${{ inputs.c-compiler }}" = "mingw" ]; then
             export PATH="/mingw64/bin:$PATH"
           fi
-          SIS_CMAKE_BUILD_DIR="${{ github.workspace }}/build" ./run_all_unit_tests.sh -M --component-only
+          SIS_CMAKE_BUILD_DIR="${{ github.workspace }}/build" ./run_all_component_tests.sh -M
 
   test-scratch:
     name: Scratch tests (${{ inputs.cell-id }})

CHANGES.md

@@ -1,6 +1,39 @@
 # STLSoft - CHANGES <!-- omit in toc -->
 
 
+## 1.11.1-rc8 - 10th October 2026
+
+* additions:
+  * Added `stlsoft_C_environment_variable_strtoll_m()` and `stlsoft::environment_variable_strtoll()`, with UNIX `getenv()` / `strtoll()` and Windows `getenv_s()` / `STLSOFT_C_AUTO_BUFFER` support; added component tests;
+  * Added `unixstl_C_get_current_process_id()` (**unixstl/process/functions.h**, new), `winstl_C_get_current_process_id()` (**winstl/process/functions.h**), and `platformstl_C_get_current_process_id()` (**platformstl/process/functions.h**, new), in terms of `getpid()` / `_getpid()`;
+  * **unixstl::filesystem_traits** — added `rewind_dir()` (wrapping `rewinddir()`) to complement `open_dir()`, `read_dir()`, and `close_dir()`, so that a directory search may be restarted from its first entry without closing and reopening the handle;
+* fixes:
+  * Fixed `stlsoft_C_environment_variable_exists_m()` when `getenv_s()` reports an existing empty variable; added component tests for `stlsoft::environment_variable_exists()`;
+  * **unixstl::filesystem_traits** — `class_type` is now defined in terms of `char_type` (the wide-character specialisation previously named the narrow specialisation);
+  * **unixstl** / **winstl** `system_traits` and `filesystem_traits` — canonicalised the conditional-compilation guards (no behavioural change);
+* testing:
+  * Component tests for `unixstl::filesystem_traits` (**test/component/unixstl/filesystem/filesystem_traits/opendir**) cover `open_dir()`, `read_dir()`, `rewind_dir()` (before any read, after a partial read, after exhaustion, on an empty directory, and repeatedly), and `close_dir()`;
+  * Scratch test **test/scratch/unixstl/filesystem/rewind_dir** — exercises `rewind_dir()` over a directory given on the command-line;
+  * Example **examples/by_project/unixstl/filesystem/rewind_dir** — enumerates a directory in two passes (count, then collect), using `rewind_dir()` between them;
+  * **test.unit.versions** — aligned with **1.11.1-rc8** (**_STLSOFT_VER_1_11_1_RC8**);
+* version:
+  * **unixstl** — **1.8.6 beta 7** (**_UNIXSTL_VER_1_8_6_B07**), with **STLSoft 1.11.1-rc8**;
+  * **winstl** — **1.13.0 beta 4** (**_WINSTL_VER_1_13_0_B04**), with **STLSoft 1.11.1-rc8**;
+  * **inetstl** — **1.5.0 alpha 3** (**_INETSTL_VER_1_5_0_A03**), with **STLSoft 1.11.1-rc8**;
+* boilerplate:
+  * Added **run_all_component_tests.sh** / **.cmd**, **run_all_performance_tests.sh** / **.cmd** (with `--gap-groups`), and **run_all_automated_tests.sh** / **.cmd** (unit then component; `--unit-only` / `--component-only`);
+  * Added **generate_doxygen.sh**, **Doxyfile**, and **doc/mainpage.md** — HTML API documentation generated from the public headers into **_build/doxygen/html**;
+  * **remove_cmake_artefacts.sh** — no longer removes **docs** or **Doxyfile**; iterates arrays safely;
+  * **batch_compile_check**, **execute_performance_tests.sh** — quote the `$(dirname ...)` directory resolution;
+  * Scripts — **build_cmake.sh**, **clean_cmake.sh**, **ctest_cmake.sh**, **prepare_cmake.sh**, **remove_cmake_artefacts.sh**, **run_all_examples.sh**, and **run_all_scratch_tests.sh** rewritten to the common Synesis helper-script layout: builds go through `cmake --build` (with `--config` selected from `SIS_CMAKE_CONFIG` for multi-config generators) rather than `make` / `mingw32-make`; coloured output (`-A` / `--always-use-colours`, `SIS_CMAKE_ALWAYS_USE_COLOURS`, `NO_COLOR`); quoted paths and arguments; `.sis/project_name.txt` used in all status messages;
+  * **prepare_cmake.sh** — added `--build-shared-libs` and `-s` / `--stlsoft-root-dir`; honours `SIS_CMAKE_GENERATOR` and `SIS_CMAKE_MINGW`; every `-D` option is passed on all generator paths;
+  * **run_all_unit_tests.sh** / **.cmd** — now run unit-test programs only (`--unit-only` accepted for compatibility; `--component-only` removed);
+  * **run_all_examples.sh** — retains `--skip-interactive` (**.github/ci_skip_interactive_examples.txt**, which prevents headless CI hanging on GUI examples) and its discovery of every executable under the **examples** tree, and now exports `SIS_EXAMPLE_SMOKE=1`; **run_all_scratch_tests.sh** / **.cmd** — removed `--verbosity`;
+  * **.gitattributes** — Linguist language-bar policy: public C headers and sources are classified as C, C++ headers and sources as C++, and `*.cmake` as CMake; helper scripts, IDE project files, **CMakeLists.txt**, and **makefile** are excluded from the advertised language mix (`-linguist-detectable`);
+  * CI — **ci-cell.yml** runs component tests via **run_all_component_tests.sh**;
+  * **INSTALL.md** — documented **run_all_component_tests.sh**, **run_all_automated_tests.sh**, and **generate_doxygen.sh**; corrected the unit-test discovery patterns;
+
+
 ## 1.11.1-rc7 - 30th September 2026
 
 * **simple_string** — counted construction, `assign`, `append`, `push_back`, and concatenation keep an embedded NUL, including assignment of a single `'\0'`;

CMakeLists.txt

@@ -5,7 +5,7 @@
 # Purpose:  Top-level CMake lists file for STLSoft
 #
 # Created:  31st March 2021
-# Updated:  30th September 2026
+# Updated:  10th October 2026
 #
 # ######################################################################## #
 

Doxyfile

@@ -0,0 +1,72 @@
+# Doxyfile for STLSoft (C/C++ API; 100% header-only)
+
+PROJECT_NAME           = "STLSoft"
+PROJECT_BRIEF          = "Robust, lightweight, cross-platform, template software"
+PROJECT_NUMBER         = 1.11.1-rc8
+
+# Overridden at generation time by generate_doxygen.sh (respects
+# SIS_CMAKE_BUILD_DIR).
+OUTPUT_DIRECTORY       = _build/doxygen
+CREATE_SUBDIRS         = NO
+
+OUTPUT_LANGUAGE        = English
+TAB_SIZE               = 4
+# Many header names recur across sub-projects (e.g. **functions.h**), so
+# retain the path relative to include/.
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = include
+STRIP_FROM_INC_PATH    = include
+TIMESTAMP              = NO
+
+INPUT                  = include \
+                         doc
+FILE_PATTERNS          = *.h \
+                         *.hpp \
+                         *.md
+RECURSIVE              = YES
+
+USE_MDFILE_AS_MAINPAGE = doc/mainpage.md
+
+EXAMPLE_PATH           = examples
+EXAMPLE_RECURSIVE      = YES
+
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+
+GENERATE_HTML          = YES
+GENERATE_LATEX         = NO
+HTML_OUTPUT            = html
+
+GENERATE_TREEVIEW      = YES
+DISABLE_INDEX          = NO
+SEARCHENGINE           = YES
+SOURCE_BROWSER         = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+VERBATIM_HEADERS       = YES
+
+MARKDOWN_SUPPORT       = YES
+JAVADOC_AUTOBRIEF      = YES
+QUIET                  = YES
+
+# Undocumented-member and parameter warnings are disabled (unlike the
+# smaller C libraries) because the very large template corpus would bury
+# genuine documentation errors.
+WARN_IF_UNDOCUMENTED   = NO
+WARN_NO_PARAMDOC       = NO
+WARN_IF_DOC_ERROR      = YES
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+SKIP_FUNCTION_MACROS   = YES
+# Skip internal version/edit noise.
+PREDEFINED             = STLSOFT_DOCUMENTATION_SKIP_SECTION
+
+HAVE_DOT               = NO
+
+
+# ########################### end of file ########################### #

EXAMPLES.md

@@ -15,6 +15,7 @@
 | **glob_sequence** | [by_project/unixstl/filesystem/glob_sequence](./examples/by_project/unixstl/filesystem/glob_sequence/main.cpp) | Unix | List selected filesystem entries with `unixstl::glob_sequence` |
 | **home_directory** | [by_project/unixstl/system/home_directory](./examples/by_project/unixstl/system/home_directory/main.cpp) | Unix | Illustrates use of `unixstl::home_directory` |
 | **readdir_sequence** | [by_project/unixstl/filesystem/readdir_sequence](./examples/by_project/unixstl/filesystem/readdir_sequence/main.cpp) | Unix | List filesystem entries with `unixstl::readdir_sequence` |
+| **rewind_dir** | [by_project/unixstl/filesystem/rewind_dir](./examples/by_project/unixstl/filesystem/rewind_dir/main.cpp) | Unix | Enumerate a directory twice with `unixstl::filesystem_traits<>::rewind_dir()` |
 | | | | |
 | **C.output_debug_line** | [by_project/winstl/diagnostics/C.output_debug_line](./examples/by_project/winstl/diagnostics/C.output_debug_line/main.c) | Windows | Emit debug strings with the C API `winstl_C_diagnostics_output_debug_line_*` |
 | **codepages** | [by_project/winstl/i18n/codepages](./examples/by_project/winstl/i18n/codepages/main.cpp) | Windows | Enumerate system code pages with `winstl::codepage_sequence` |

INSTALL.md

@@ -23,17 +23,17 @@ There are three options for installing **STLSoft**, depending on how you obtain
 
 If you obtain the latest release as an archive from the [**STLSoft** GitHub Releases](https://github.com/synesissoftware/STLSoft/releases) page (legacy archives may also still appear on [SourceForge](https://sourceforge.net/projects/stlsoft/)):
 
-1. Download the latest distribution, e.g. [**STLSoft-1.11.1-rc7.zip**](https://github.com/synesissoftware/STLSoft/archive/refs/tags/1.11.1-rc7.zip);
+1. Download the latest distribution, e.g. [**STLSoft-1.11.1-rc8.zip**](https://github.com/synesissoftware/STLSoft/archive/refs/tags/1.11.1-rc8.zip);
 
 2. Unzip it to a directory of your choice, as in:
 
 ```bash
 $ mkdir -p ~/open-source
 $ cd ~/open-source
-$ unzip STLSoft-1.11.1-rc7.zip
+$ unzip STLSoft-1.11.1-rc8.zip
 ```
 
-3. Define an environment variable `STLSOFT`, whose value is the directory in which you unzipped it, e.g. `STLSOFT=~/open-source/STLSoft-1.11.1-rc7`, and then specify `$(STLSOFT)/include` (**UNIX**) or `%STLSOFT%\include` (**Windows**) in your project files and makefiles;
+3. Define an environment variable `STLSOFT`, whose value is the directory in which you unzipped it, e.g. `STLSOFT=~/open-source/STLSoft-1.11.1-rc8`, and then specify `$(STLSOFT)/include` (**UNIX**) or `%STLSOFT%\include` (**Windows**) in your project files and makefiles;
 
 
 ### Cloning project, using environment variables
@@ -100,16 +100,16 @@ $ sudo cmake --install ${SIS_CMAKE_BUILD_DIR:-./_build} --config Release
 Unless you are certain that your projects, and all the projects upon which they depend, all use **STLSoft** via **CMake** then it is recommended that you define an `STLSOFT` environment variable.
 
 For example, if you're using **UNIX** and you install to
-**/usr/local/stlsoft/STLSoft-1.11.1-rc7**
+**/usr/local/stlsoft/STLSoft-1.11.1-rc8**
 then you should set the environment variable `STLSOFT` to
-**/usr/local/stlsoft/STLSoft-1.11.1-rc7**
-in which case the file `stlsoft/stlsoft.h`, for example, will be located in `/usr/local/stlsoft/STLSoft-1.11.1-rc7/include/stlsoft/stlsoft.h`.
+**/usr/local/stlsoft/STLSoft-1.11.1-rc8**
+in which case the file `stlsoft/stlsoft.h`, for example, will be located in `/usr/local/stlsoft/STLSoft-1.11.1-rc8/include/stlsoft/stlsoft.h`.
 
 Conversely, if you're using **Windows** and you install to
-**C:\3pty\STLSoft\STLSoft-1.11.1-rc7**
+**C:\3pty\STLSoft\STLSoft-1.11.1-rc8**
 then you should set the environment variable `STLSOFT` to
-**C:\3pty\STLSoft\STLSoft-1.11.1-rc7**
-in which case the file `stlsoft/stlsoft.h`, for example, will be located in `C:\3pty\STLSoft\STLSoft-1.11.1-rc7\include\stlsoft\stlsoft.h`.
+**C:\3pty\STLSoft\STLSoft-1.11.1-rc8**
+in which case the file `stlsoft/stlsoft.h`, for example, will be located in `C:\3pty\STLSoft\STLSoft-1.11.1-rc8\include\stlsoft\stlsoft.h`.
 
 The makefiles / project files of several other open-source projects expect this symbol, including:
 
@@ -143,7 +143,10 @@ This project comes with a number of scripts useful for building with **CMake**,
 | **build_cmake.sh** | Executes **CMake**-generated artefacts to (re)build the project.<br/><br/>Meaningful only once `prepare_cmake.sh` has been run to generate the **CMake** build artefacts.<br/><br/>Use `./build_cmake.sh --help` for further information. |
 | **clean_cmake.sh** | Executes **CMake**-generated artefacts to clean the project.<br/><br/>Meaningful only once `prepare_cmake.sh` has been run and a build has been run.<br/><br/>Use `./clean_cmake.sh --help` for further information. |
 | **run_all_examples.sh** | Runs all (matching) example programs.<br/><br/>Performs a build and then recursively runs executables under the examples tree. See also [**EXAMPLES.md**](./EXAMPLES.md).<br/><br/>Use `./run_all_examples.sh --help` for further information. |
-| **run_all_unit_tests.sh** | Runs all (matching) unit-test programs.<br/><br/>Performs a build and then recursively runs executable programs matching the shell patterns `test_*` and `test.*`.<br/><br/>Use `./run_all_unit_tests.sh --help` for further information. |
+| **run_all_unit_tests.sh** | Runs all (matching) unit-test programs.<br/><br/>Performs a build and then recursively runs executable programs matching the shell patterns `test_unit*` and `test.unit.*`.<br/><br/>Use `./run_all_unit_tests.sh --help` for further information. |
+| **run_all_component_tests.sh** | Runs all (matching) component-test programs.<br/><br/>Performs a build and then recursively runs executable programs matching the shell patterns `test_component*` and `test.component.*`.<br/><br/>Use `./run_all_component_tests.sh --help` for further information. |
+| **run_all_automated_tests.sh** | Runs all (matching) automated test programs: unit tests followed by component tests.<br/><br/>Use `./run_all_automated_tests.sh --help` for further information. |
+| **generate_doxygen.sh** | Generates HTML API documentation from the public headers via **Doxygen**.<br/><br/>Writes to `./_build/doxygen/html/` (see **SIS_CMAKE_BUILD_DIR**); requires `doxygen` on the `PATH`.<br/><br/>Use `./generate_doxygen.sh --help` for further information. |
 | **remove_cmake_artefacts.sh** | Removes all known **CMake** artefacts.<br/><br/>Removes known **CMake** build artefacts from the build directory (currently `./_build`) to prepare for complete regeneration using `prepare_cmake.sh`.<br/><br/>Use `./remove_cmake_artefacts.sh --help` for further information. |
 
 

NEWS.md

@@ -3,6 +3,7 @@
 
 | Date                | News Item                           | Details |
 | ------------------- | ----------------------------------- | ------- |
+| 10th October 2026   | Release of [STLSoft 1.11.1-rc8](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc8) | environment_variable_strtoll()`; `unixstl::filesystem_traits<>::rewind_dir()`; `class_type` and `getenv_s()` empty-variable fixes; component tests; `cmake --build` helper scripts; **run_all_component_tests.sh** / **run_all_automated_tests.sh**; **generate_doxygen.sh**; Linguist classification |
 | 30th September 2026 | Release of [STLSoft 1.11.1-rc7](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc7) | counted NULs; `wchar_t` `string_begins_with`; bit intrinsics; `write_binary()`; `file_lines` mmap (~10–20× vs `fgetc`); compare and allocator units; MinGW static runtime; short test directories; nested **test/performance** |
 | 21st September 2026 | Release of [STLSoft 1.11.1-rc6](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc6) | ACE/ATL/MFC CI; Clang/macOS `stricmp` aliases |
 | 4th August 2026     | Release of [STLSoft 1.11.1-rc5](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc5) | `basic_simple_string<>#resize()`; **CHANGES.md**; docs |