measur-tools-suite 1.0.13-beta.134 → 1.0.13-beta.136

package/BUILD.md

@@ -76,18 +76,20 @@ Install only what you need for the scenario you plan to use.
 Mutually influential behavior:
 - When `BUILD_WASM=ON` the build disables `BUILD_TESTING` & `BUILD_PACKAGE` internally (see `CMakeLists.txt`). Toggle intentionally—do not expect tests with WASM in a single configure.
 
+> **Tip:** Use dedicated build directories (for example, `build-cpp` and `build-wasm`) instead of reconfiguring the same directory when you switch scenarios. This avoids stale cache entries and conflicting options.
+
 ---
 
 ## 5. Common Build Scenarios
 
-| Scenario                     | Commands (summary)                                                                                                  |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| Standard C++ (library + CLI) | `mkdir build-cpp && cd build-cpp && cmake .. && cmake --build .`                                                    |
-| C++ Tests                    | (after standard build) run `./bin/cpp_tests` (Linux/macOS) or `./cpp_tests` inside `Debug/` or `Release/` (Windows) |
-| WASM Module                  | `emcmake cmake -DBUILD_WASM=ON ..` then `emmake make`                                                               |
-| WASM Tests (browser)         | `npm install && npm run test:browser`                                                                               |
-| Documentation                | `doxygen Doxyfile`                                                                                                  |
-| Package                      | `cmake -DBUILD_PACKAGE=ON -DBUILD_TESTING=OFF .. && cmake --build . --target package`                               |
+| Scenario                     | Commands (summary)                                                                                                                            |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Standard C++ (library + CLI) | `cmake -S . -B build-cpp && cmake --build build-cpp` (Windows: add `--config Release` or desired configuration)                               |
+| C++ Tests                    | (after standard build) run `./build-cpp/bin/cpp_tests` (Linux/macOS) or `./build-cpp/Debug/cpp_tests.exe` (Windows; use `Release/` as needed) |
+| WASM Module                  | `emcmake cmake -S . -B build-wasm -DBUILD_WASM=ON` then `emmake make -C build-wasm`                                                           |
+| WASM Tests (browser)         | `npm install && npm run test:browser`                                                                                                         |
+| Documentation                | `doxygen Doxyfile`                                                                                                                            |
+| Package                      | `cmake -S . -B build-pkg -DBUILD_PACKAGE=ON -DBUILD_TESTING=OFF && cmake --build build-pkg --target package`                                  |
 
 ---
 
@@ -98,33 +100,31 @@ Mutually influential behavior:
 ```bash
 git clone <repo-url> MEASUR-Tools-Suite
 cd MEASUR-Tools-Suite
-mkdir build-cpp
-cd build-cpp
-cmake ..            # add -G "Ninja" or other generator if desired
-cmake --build .     # builds library + CLI + tests (if enabled)
+cmake -S . -B build-cpp  # add -G "Ninja" or other generator if desired
+cmake --build build-cpp  # builds library + CLI + tests (if enabled)
 ```
-Artifacts:
-- Library: `build-cpp/lib/libmeasur_tools_suite.a` (Linux/macOS) or `.lib` (Windows)
-- CLI executable: `build-cpp/bin/measur_tools_suite` (Linux/macOS) or `measur_tools_suite.exe` (Windows under `Debug/` or `Release/` if multi-config)
+(On Windows multi-config generators (e.g., Visual Studio), specify a configuration: `cmake --build build-cpp --config Release` (or `Debug`).)
+
+Artifacts appear under `build-cpp/bin/` or on Windows `build-cpp/Debug/` or `build-cpp/Release/`.
 
 ### 6.2 Running the CLI
 
 ```bash
-./bin/measur_tools_suite --help
+./build-cpp/bin/measur_tools_suite --help
 ```
-(Adjust path for Windows: `./Debug/measur_tools_suite.exe` or `./Release/measur_tools_suite.exe`.)
+(Adjust path for Windows: `./build-cpp/Debug/measur_tools_suite.exe` or `./build-cpp/Release/measur_tools_suite.exe`.)
 
 ### 6.3 C++ Unit Tests
 
 If `BUILD_TESTING=ON` (default in non-WASM builds):
 ```bash
-cd build-cpp/bin
-./cpp_tests
+./build-cpp/bin/cpp_tests
 ```
 Windows (multi-config):
 ```bash
-cd build-cpp/Debug
-./cpp_tests.exe
+./build-cpp/Debug/cpp_tests.exe
+# or
+./build-cpp/Release/cpp_tests.exe
 ```
 
 ### 6.4 WebAssembly Build
@@ -171,15 +171,13 @@ emcc --version  # should show Emscripten version
 
 With emsdk activated, configure and build:
 ```bash
-mkdir build-wasm
-cd build-wasm
-emcmake cmake -DBUILD_WASM=ON ..
-emmake make
+emcmake cmake -S . -B build-wasm -DBUILD_WASM=ON
+emmake make -C build-wasm
+```
+Artifacts appear under `build-wasm/bin/`. Copy them to `bin/` for standard access:
+```bash
+cp -a build-wasm/bin ./bin
 ```
-
-Artifacts appear under `build-wasm/bin/`:
-- `client.js` (glue / loader)
-- `client.wasm` (compiled module)
 
 ### 6.5 WebAssembly Usage Example
 
@@ -203,7 +201,7 @@ Run from repository root (uses mocha):
 npm install
 npm run test:browser
 ```
-Mocha tests reside in `tests/wasm-mocha/`. Re-running tests after editing JS/WASM test files does not require a rebuild unless C++ sources changed.
+Mocha tests reside in `tests/wasm-mocha/`. Re-running tests after editing JS/WASM test files does not require a rebuild unless C++ sources changed. Rerun `npm install` only when dependencies change or the lockfile updates.
 
 ### 6.7 Documentation Generation
 
@@ -216,13 +214,12 @@ Output: `docs/html/index.html`.
 
 Single-config (Linux/macOS):
 ```bash
-mkdir build-pkg && cd build-pkg
-cmake -DBUILD_PACKAGE=ON -DBUILD_TESTING=OFF ..
-cmake --build . --target package
+cmake -S . -B build-pkg -DBUILD_PACKAGE=ON -DBUILD_TESTING=OFF
+cmake --build build-pkg --target package
 ```
 Windows (multi-config):
 ```bash
-cmake -B build-pkg -DBUILD_PACKAGE=ON -DBUILD_TESTING=OFF .
+cmake -S . -B build-pkg -DBUILD_PACKAGE=ON -DBUILD_TESTING=OFF
 cmake --build build-pkg --config Release --target package
 ```
 Resulting archives appear in the build directory (`.tar.gz` / `.zip`).
@@ -281,7 +278,7 @@ Build outputs appear in host directories (via volume mounts):
 - `build-cpp/bin/cpp_tests` - Native C++ test executable
 - `build-cpp/bin/measur_tools_suite` - Native CLI executable
 - `build-cpp/lib/libmeasur_tools_suite.a` - Static library
-- `build-wasm/bin/client.js` + `client.wasm` - WebAssembly module
+- `bin/client.js` + `client.wasm` - WebAssembly module
 
 Run C++ tests on host:
 ```bash
@@ -305,17 +302,11 @@ Inside container, source tree is at `/home/MEASUR-Tools-Suite/`:
 ```bash
 # Run C++ tests
 ./build-cpp/bin/cpp_tests
+# Windows: ./build-cpp/Debug/cpp_tests.exe (or Release)
 
 # Run WASM tests
 npm run tests
 
-# Incremental rebuild (native)
-cmake --build build-cpp -j 8
-
-# Incremental rebuild (WASM)
-source /home/emsdk/emsdk_env.sh
-emmake make -C build-wasm -j 8
-
 # Exit container
 exit
 ```
@@ -343,6 +334,7 @@ docker compose up -d
 
 The `docker-compose.yml` mounts host directories into the container:
 - `../MEASUR-Tools-Suite:/home/MEASUR-Tools-Suite` - Source code (editable from host)
+- `./bin:/home/MEASUR-Tools-Suite/bin` - WASM build outputs
 - `./build-cpp:/home/MEASUR-Tools-Suite/build-cpp` - Native build outputs
 - `./build-wasm:/home/MEASUR-Tools-Suite/build-wasm` - WASM build outputs
 
@@ -356,8 +348,10 @@ The container executes the following sequence:
 3. Builds native targets: `cmake --build . -j 8`
 4. Configures WASM build: `cd build-wasm && emcmake cmake -DBUILD_WASM=ON ..`
 5. Builds WASM targets: `emmake make -j 8`
-6. Installs Node dependencies: `npm install`
-7. Sleeps indefinitely to keep container accessible
+6. Copies WASM artifacts to mounted `bin/` directory
+7. Installs Node dependencies: `npm install`
+8. Runs browser-based WASM tests using headless Chrome: `npm run tests`
+9. Sleeps indefinitely to keep container accessible
 
 ### 7.9 Docker Troubleshooting
 
@@ -404,22 +398,24 @@ emcc --version  # verify Emscripten is active
 
 ```bash
 # Native build (library + CLI + tests)
-mkdir build-cpp && cd build-cpp && cmake .. && cmake --build .
+cmake -S . -B build-cpp && cmake --build build-cpp
+# Windows multi-config generators: cmake --build build-cpp --config Release
 
 # Run C++ tests
-./bin/cpp_tests
+./build-cpp/bin/cpp_tests
 
 # WASM build
-mkdir build-wasm && cd build-wasm && emcmake cmake -DBUILD_WASM=ON .. && emmake make
+emcmake cmake -S . -B build-wasm -DBUILD_WASM=ON && emmake make -C build-wasm
 
 # WASM browser tests
-npm install && npm run test:browser
+npm install && npm run test:browser  # install needed only on first run
 
 # Docs
 doxygen Doxyfile
 
 # Package
-cmake -DBUILD_PACKAGE=ON -DBUILD_TESTING=OFF .. && cmake --build . --target package
+cmake -S . -B build-pkg -DBUILD_PACKAGE=ON -DBUILD_TESTING=OFF && cmake --build build-pkg --target package
+# Windows multi-config generators: cmake --build build-pkg --config Release --target package
 ```
 
 ### Docker Builds

package/CONTRIBUTING.md

@@ -2,18 +2,18 @@
 
 This guide provides clear standards and best practices for contributing to this project. It covers coding style, documentation, formatting, and workflow expectations to help maintain high code quality, ensure long-term maintainability, and foster smooth collaboration among all contributors.
 
-[<h2> Style Guide </h2>](/contributing/style-guide.md)
+## [Style Guide](/contributing/style-guide.md)
 
 Follow this guide to make sure your contributions align with the project's coding standards. This will help ensure that your code is readable, maintainable, and consistent with the rest of the codebase.
 
-[<h2> Formatting </h2>](/contributing/formatting.md)
+## [Formatting](/contributing/formatting.md)
 
 Follow the formatting standards using clang-format to ensure a consistent code style across all C++ files. This helps maintain readability and reduces merge conflicts.
 
-[<h2> Documentation </h2>](/contributing/documentation.md)
+## [Documentation](/contributing/documentation.md)
 
 Follow these guidelines to document your code effectively using Doxygen. Proper documentation is crucial for understanding the codebase and facilitating collaboration.
 
-[<h2> Conventional Commits </h2>](/contributing/conventional-commits.md)
+## [Conventional Commits](/contributing/conventional-commits.md)
 
 Use Conventional Commits to structure your commit messages. This helps maintain a clear project history and makes it easier to understand the purpose of each change.

package/README.md

@@ -32,14 +32,16 @@ const measurTools = require('measur-tools-suite');
 
 ```bash
 # Native C++ build
-mkdir build-cpp && cd build-cpp
-cmake ..
-cmake --build .
+cmake -S . -B build-cpp
+cmake --build build-cpp
 
 # WebAssembly build (requires Emscripten)
-mkdir build-wasm && cd build-wasm
-emcmake cmake -DBUILD_WASM=ON ..
-emmake make
+emcmake cmake -S . -B build-wasm -DBUILD_WASM=ON
+emmake make -C build-wasm
+
+# Packaging
+cmake -S . -B build-pkg -DBUILD_PACKAGE=ON -DBUILD_TESTING=OFF
+cmake --build build-pkg --target package
 ```
 
 See [BUILD.md](BUILD.md) for detailed build instructions, testing, and Docker workflows.
@@ -64,9 +66,9 @@ See [BUILD.md](BUILD.md) for detailed build instructions, testing, and Docker wo
 
 Contributions are welcome! Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for:
 - Code style guidelines ([contributing/style-guide.md](contributing/style-guide.md))
+- Formatting standards ([contributing/formatting.md](contributing/formatting.md))
 - Documentation standards ([contributing/documentation.md](contributing/documentation.md))
 - Commit message conventions ([contributing/conventional-commits.md](contributing/conventional-commits.md))
-- Pull request process
 
 ## License
 

package/bin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "measur-tools-suite",
-  "version": "1.0.13-beta.134",
+  "version": "1.0.13-beta.136",
   "engines": {
     "node": "20.19.4",
     "npm": "10.8.2"

package/contributing/conventional-commits.md

@@ -1,8 +1,8 @@
-# Conventional Commits <!-- omit in toc -->
+# Conventional Commits
 
 This project follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages to ensure clarity, consistency, and automation in version control. This helps in generating changelogs, automating releases, and improving collaboration among contributors.
 
-## Table of Contents <!-- omit in toc -->
+## Table of Contents
 
 - [Commit Format](#commit-format)
 - [Commit Types](#commit-types)

package/contributing/documentation.md

@@ -1,8 +1,8 @@
-# Documentation <!-- omit in toc -->
+# Documentation
 
 This project uses [Doxygen](https://www.doxygen.nl/) to generate documentation from annotated source code. Doxygen comments are used to describe the purpose, behavior, and usage of classes, functions, and other entities in the codebase. Follow these guidelines to ensure your code is well-documented and easy to understand. Always use `@` for Doxygen commands.
 
-## Table of Contents <!-- omit in toc -->
+## Table of Contents
 
 - [Doxygen Commands](#doxygen-commands)
 - [Doxygen Aliases](#doxygen-aliases)

package/contributing/formatting.md

@@ -1,9 +1,8 @@
-
-# Formatting <!-- omit in toc -->
+# Formatting
 
 This project uses [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to ensure a consistent code style across all C++ files.
 
-## Table of Contents <!-- omit in toc -->
+## Table of Contents
 
 - [Configuration](#configuration)
 - [How to Format Code](#how-to-format-code)

package/contributing/style-guide.md

@@ -1,8 +1,8 @@
-# Style Guide <!-- omit in toc -->
+# Style Guide
 
 Use this guide to ensure your contributions align with the project's coding standards. It is loosely based on the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) and the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines), with some modifications to suit this project's needs.
 
-## Table of Contents <!-- omit in toc -->
+## Table of Contents
 
 - [Header Files](#header-files)
   - [Include Guards](#include-guards)

package/karma.conf.js

@@ -10,8 +10,8 @@ module.exports = function (config) {
         frameworks: ['mocha'],
         files: [
             // All browser-based WASM Mocha tests
-            { pattern: 'build-wasm/bin/client.js', included: false, served: true, watched: false },
-            { pattern: 'build-wasm/bin/client.wasm', included: false, served: true, watched: false },
+            { pattern: 'bin/client.js', included: false, served: true, watched: false },
+            { pattern: 'bin/client.wasm', included: false, served: true, watched: false },
             'tests/wasm-mocha/**/*.test.js',
             // Add any additional files or patterns as needed
         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "measur-tools-suite",
-  "version": "1.0.13-beta.134",
+  "version": "1.0.13-beta.136",
   "engines": {
     "node": "20.19.4",
     "npm": "10.8.2"