Minor docs update, code review changes, script modifications.

Author: gojimmypi

CMakeLists.txt

@@ -33,6 +33,17 @@
 
 message(STATUS "Begin [WOLFBOOT_ROOT]/CmakeLists.txt")
 
+#---------------------------------------------------------------------------------------------
+# First, ensure no in-source build occurs.
+#---------------------------------------------------------------------------------------------
+if(NOT "${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}")
+    message(FATAL_ERROR
+            "In-source builds are not allowed for wolfBoot.\
+             Run cmake from a separate directory from where CMakeLists.txt lives.\
+             Clean up any stray cache or build directories and try again. \
+             See [WOLFBOOT_ROOT]/docs/CMake.md for additional details.")
+endif()
+
 message(STATUS "wolfBoot target: ${WOLFBOOT_TARGET}")
 message(STATUS "CMake version:   ${CMAKE_VERSION}")
 message(STATUS "Generator:       ${CMAKE_GENERATOR}")
@@ -46,14 +57,6 @@ include(cmake/config_defaults.cmake)
 #---------------------------------------------------------------------------------------------
 # Initial environment checks
 #---------------------------------------------------------------------------------------------
-if("${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}")
-    message(
-        FATAL_ERROR
-            "In-source builds are not allowed for wolfBoot.\
-     Run cmake from a separate directory from where CMakeLists.txt lives.\
-     NOTE: cmake will now create CMakeCache.txt and CMakeFiles/*.\
-     You must delete them, or cmake will refuse to work.")
-endif()
 
 # This must appear before project(wolfBoot)
 if(NOT DEFINED CMAKE_TOOLCHAIN_FILE)
@@ -66,6 +69,7 @@ if(NOT DEFINED CMAKE_TOOLCHAIN_FILE)
     endif()
 endif()
 
+
 if(NOT DEFINED PREFERRED_HOST_CC_NAME_LIST OR PREFERRED_HOST_CC_NAME_LIST STREQUAL "")
     # set(PREFERRED_HOST_CC_NAME_LIST gcc clang cl)
     if(CMAKE_HOST_WIN32)

docs/CMake.md

@@ -2,6 +2,12 @@
 
 See the [`WOLFBOOT_ROOT`/cmake/README.md](../cmake/README.md) file.
 
+## Important: No in-source builds.
+
+One of the first checks in the `[WOLFBOOT_ROOT]/CMakeLists.txt` is whether `CMAKE_SOURCE_DIR` == `CMAKE_BINARY_DIR`.
+In-source builds are not supported. The provided wolfSSL presets will typically prevent this.
+Beware when integrating with existing projects or creating custom presets.
+
 ### CMake - Presets
 
 This section explains how to build wolfBoot using CMake Presets.
@@ -181,14 +187,14 @@ C:\Users\%USERNAME%\AppData\Local\CMakeTools
 
 #### Tips & Gotchas
 
-Out-of-source enforced: wolfBoot’s CMakeLists.txt blocks in-source builds;
+Out-of-source enforced: wolfBoot's CMakeLists.txt blocks in-source builds;
 presets default to `build-${presetName}` anyway.
 
 Toolchain auto-select: If `WOLFBOOT_TARGET` is not x86_64_efi or sim,
 CMAKE_TOOLCHAIN_FILE defaults to `cmake/toolchain_arm-none-eabi.cmake`.
 
 Windows host tools: When HOST_CC is `cl.exe`, CMakeLists.txt creates a
-lightweight `unistd.h` shim and adjusts flags—no manual changes needed.
+lightweight `unistd.h` shim and adjusts flags-no manual changes needed.
 
 `$penv` vs `$env`: Use `$penv{VAR}` in environment to append to the existing
 process environment (keeps your PATH). `$env{VAR}` replaces it.

tools/keytools/README.md

@@ -39,6 +39,13 @@ make wolfboot_signing_private_key.der SIGN=ED25519
 ./tools/keytools/keygen --ed25519 -g wolfboot_signing_private_key.der
 ```
 
+Note the above example is a basic case where a single key is generated.
+The tool supports multiple keys both with `[-g privkey]` and `[-i pubkey]` parameters.
+
+See the local docs [docs/keystore.md](../../docs/keystore.md)
+and the [wolfBoot Keystore section of the manual](https://www.wolfssl.com/documentation/manuals/wolfboot/appendix04.html)
+for additional details.
+
 ## Debugging and Development
 
 ### `DEBUG_SIGNTOOL`
@@ -48,12 +55,3 @@ Enables additional diagnostic messages that may be useful during development and
 ### `WOLFBOOT_SHOW_INCLUDE`
 
 Enables compile-time verbosity to indicate which `user_settings.h` file is being used.
-
-Unless otherwise specified the `keygen` app will create:
-
-1. `./wolfboot_signing_private_key.der` - the private key used for signing.
-2. `./keystore.der` - the public key.
-3. `src/keystore.c` - the public key, converted to c array.
-
-Common pitfalls: mismatched keystore files in different directories. There should be exactly one
-instance of each of the above files in the build tree.

tools/scripts/cmake_test.bat

@@ -6,9 +6,104 @@
 :: This test manually sets paths to cmake and include files (also assumes VS 2022 is installed, but can be any suitable path)
 cls
 
-set "Path=C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\bin\HostX86\x86;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\VC\VCPackages;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TestWindow;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\bin\Roslyn;C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools\;C:\Program Files (x86)\HTML Help Workshop;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\FSharp\Tools;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Team Tools\DiagnosticsHub\Collector;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\Extensions\Microsoft\CodeCoverage.Console;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\\x86;C:\Program Files (x86)\Windows Kits\10\bin\\x86;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\\MSBuild\Current\Bin\amd64;C:\Windows\Microsoft.NET\Framework\v4.0.30319;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\;C:\Program Files (x86)\VMware\VMware Workstation\bin\;C:\Program Files\Microsoft\jdk-11.0.16.101-hotspot\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\WINDOWS\System32\WindowsPowerShell\v1.0\;C:\WINDOWS\System32\OpenSSH\;C:\Program Files\dotnet\;C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn\;C:\Program Files\Microsoft SQL Server\150\Tools\Binn\;C:\Program Files\Git\cmd;C:\SysGCC\esp32-master\tools\riscv32-esp-elf\esp-15.2.0_20250920\riscv32-esp-elf\bin;C:\SysGCC\esp32-master\tools\xtensa-esp-elf\esp-15.2.0_20250920\xtensa-esp-elf\bin;C:\Program Files (x86)\VMware\VMware Workstation\bin\;C:\Program Files\Microsoft\jdk-11.0.16.101-hotspot\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\WINDOWS\System32\WindowsPowerShell\v1.0\;C:\WINDOWS\System32\OpenSSH\;C:\Program Files\dotnet\;C:\Program Files\Git\cmd;C:\Users\gojimmypi\AppData\Local\Microsoft\WindowsApps;C:\Users\gojimmypi\AppData\Local\Programs\Microsoft VS Code\bin;C:\ST\STM32CubeIDE_1.14.1\STM32CubeIDE\plugins\com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.win32_2.1.100.202311100844\tools\bin;C:\Program Files\Git\usr\bin\;C:\Users\gojimmypi\.dotnet\tools;C:\SysGCC\esp32-master\tools\riscv32-esp-elf\esp-13.2.0_20240530\riscv32-esp-elf\bin;C:\Users\gojimmypi\AppData\Local\Microsoft\WinGet\Packages\Ninja-build.Ninja_Microsoft.Winget.Source_8wekyb3d8bbwe;;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\CMake\Ninja;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\VC\Linux\bin\ConnectionManagerExe"
-set "INCLUDE=C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\include;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\ATLMFC\include;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\VS\include;C:\Program Files (x86)\Windows Kits\10\include\10.0.26100.0\ucrt;C:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\um;C:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\shared;C:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\winrt;C:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\cppwinrt;C:\Program Files (x86)\Windows Kits\NETFXSDK\4.8\include\um"
-set "LIB=C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\ATLMFC\lib\x86;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\lib\x86;C:\Program Files (x86)\Windows Kits\NETFXSDK\4.8\lib\um\x86;C:\Program Files (x86)\Windows Kits\10\lib\10.0.26100.0\ucrt\x86;C:\Program Files (x86)\Windows Kits\10\\lib\10.0.26100.0\\um\x86"
+:: Optionally hard code your paths like this:
+:: set "Path=C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\bin\HostX86\x86;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\VC\VCPackages;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TestWindow;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\bin\Roslyn;C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools\;C:\Program Files (x86)\HTML Help Workshop;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\FSharp\Tools;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Team Tools\DiagnosticsHub\Collector;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\Extensions\Microsoft\CodeCoverage.Console;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\\x86;C:\Program Files (x86)\Windows Kits\10\bin\\x86;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\\MSBuild\Current\Bin\amd64;C:\Windows\Microsoft.NET\Framework\v4.0.30319;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\;C:\Program Files (x86)\VMware\VMware Workstation\bin\;C:\Program Files\Microsoft\jdk-11.0.16.101-hotspot\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\WINDOWS\System32\WindowsPowerShell\v1.0\;C:\WINDOWS\System32\OpenSSH\;C:\Program Files\dotnet\;C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn\;C:\Program Files\Microsoft SQL Server\150\Tools\Binn\;C:\Program Files\Git\cmd;C:\SysGCC\esp32-master\tools\riscv32-esp-elf\esp-15.2.0_20250920\riscv32-esp-elf\bin;C:\SysGCC\esp32-master\tools\xtensa-esp-elf\esp-15.2.0_20250920\xtensa-esp-elf\bin;C:\Program Files (x86)\VMware\VMware Workstation\bin\;C:\Program Files\Microsoft\jdk-11.0.16.101-hotspot\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\WINDOWS\System32\WindowsPowerShell\v1.0\;C:\WINDOWS\System32\OpenSSH\;C:\Program Files\dotnet\;C:\Program Files\Git\cmd;C:\Users\gojimmypi\AppData\Local\Microsoft\WindowsApps;C:\Users\gojimmypi\AppData\Local\Programs\Microsoft VS Code\bin;C:\ST\STM32CubeIDE_1.14.1\STM32CubeIDE\plugins\com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.win32_2.1.100.202311100844\tools\bin;C:\Program Files\Git\usr\bin\;C:\Users\gojimmypi\.dotnet\tools;C:\SysGCC\esp32-master\tools\riscv32-esp-elf\esp-13.2.0_20240530\riscv32-esp-elf\bin;C:\Users\gojimmypi\AppData\Local\Microsoft\WinGet\Packages\Ninja-build.Ninja_Microsoft.Winget.Source_8wekyb3d8bbwe;;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\CMake\Ninja;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\VC\Linux\bin\ConnectionManagerExe"
+:: set "INCLUDE=C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\include;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\ATLMFC\include;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\VS\include;C:\Program Files (x86)\Windows Kits\10\include\10.0.26100.0\ucrt;C:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\um;C:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\shared;C:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\winrt;C:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\cppwinrt;C:\Program Files (x86)\Windows Kits\NETFXSDK\4.8\include\um"
+:: set "LIB=C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\ATLMFC\lib\x86;C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\lib\x86;C:\Program Files (x86)\Windows Kits\NETFXSDK\4.8\lib\um\x86;C:\Program Files (x86)\Windows Kits\10\lib\10.0.26100.0\ucrt\x86;C:\Program Files (x86)\Windows Kits\10\\lib\10.0.26100.0\\um\x86"
+
+@echo off
+setlocal
+
+echo [INFO] Checking Visual Studio / MSVC environment...
+
+REM -------------------------------------------------------------------
+REM 1) Check whether Visual Studio is already on PATH
+REM -------------------------------------------------------------------
+echo %PATH% | findstr /I "Microsoft Visual Studio" >nul
+if errorlevel 1 (
+    echo [WARN] Visual Studio not obviously found in PATH.
+    echo [WARN] This test is expected to run from a Visual Studio Developer Command Prompt.
+) else (
+    echo [INFO] Visual Studio paths detected in PATH.
+)
+
+REM -------------------------------------------------------------------
+REM 2) Check VCToolsInstallDir
+REM -------------------------------------------------------------------
+if "%VCToolsInstallDir%"=="" (
+    echo [WARN] VCToolsInstallDir is not defined.
+    echo [WARN] You may not be running from a proper Developer Command Prompt.
+) else (
+    echo [INFO] VCToolsInstallDir = "%VCToolsInstallDir%"
+)
+
+REM -------------------------------------------------------------------
+REM 3) Check INCLUDE
+REM -------------------------------------------------------------------
+if "%INCLUDE%"=="" goto NO_INCLUDE
+
+echo %INCLUDE% | findstr /I "VC\\Tools\\MSVC\\" >nul
+if errorlevel 1 goto INCLUDE_WARN
+
+echo [INFO] INCLUDE contains VC\Tools\MSVC\ (looks OK).
+goto AFTER_INCLUDE
+
+:NO_INCLUDE
+echo [ERROR] INCLUDE is not defined.
+echo [ERROR] Please run this test from a Visual Studio Developer Command Prompt.
+set VS_ENV_ERROR=1
+goto AFTER_INCLUDE
+
+:INCLUDE_WARN
+echo [WARN] INCLUDE does not contain "VC\Tools\MSVC\".
+echo [WARN] Current INCLUDE is:
+echo   %INCLUDE%
+set VS_ENV_WARN=1
+
+:AFTER_INCLUDE
+
+REM -------------------------------------------------------------------
+REM 4) Check LIB
+REM -------------------------------------------------------------------
+if "%LIB%"=="" goto NO_LIB
+
+echo %LIB% | findstr /I "VC\\Tools\\MSVC\\" >nul
+if errorlevel 1 goto LIB_WARN
+
+echo [INFO] LIB contains VC\Tools\MSVC\ (looks OK).
+goto AFTER_LIB
+
+:NO_LIB
+echo [ERROR] LIB is not defined.
+echo [ERROR] Please run this test from a Visual Studio Developer Command Prompt.
+set VS_ENV_ERROR=1
+goto AFTER_LIB
+
+:LIB_WARN
+echo [WARN] LIB does not contain "VC\Tools\MSVC\".
+echo [WARN] Current LIB is:
+echo   %LIB%
+set VS_ENV_WARN=1
+
+:AFTER_LIB
+
+REM -------------------------------------------------------------------
+REM 5) Decide exit code (for CTest)
+REM -------------------------------------------------------------------
+if defined VS_ENV_ERROR (
+    echo [ERROR] Visual Studio environment is incomplete. Failing test.
+    endlocal & exit /b 1
+)
+
+if defined VS_ENV_WARN (
+    echo [WARN] Visual Studio environment has potential issues, but continuing.
+    endlocal
+)
+
+echo [INFO] Visual Studio environment looks good.
+endlocal
+
+exit /b 0
 
 :: We start in /tools/scripts, but build two directories up: from wolfBoot root
 
@@ -49,6 +144,10 @@ echo Starting %~nx0 from %CD%
 :: End common start directory detection
 
 
+::------------------------------------------------------------------------------------
+:: CMake test
+::------------------------------------------------------------------------------------
+
 :: Is CMake installed?
 where cmake >nul 2>&1
 if errorlevel 1 (
@@ -58,12 +157,11 @@ if errorlevel 1 (
 )
 
 
-
 rmdir /s /q build-stm32l4
 
 cmake --preset stm32l4
 
-
+:: Optional parallel build specification:
 :: cmake --build --preset stm32l4 --parallel 4 -v
 
 cmake --build --preset stm32l4

tools/scripts/config2presets.py

@@ -396,6 +396,19 @@ def run_cmake_and_report_unused(preset_name: str, repo_root: Path):
             combined += "\n"
         combined += proc.stderr
 
+    # If CMake failed, show the full output first so the error is visible.
+    if proc.returncode != 0:
+        print("")
+        print("CMake configure for preset '{}' failed with exit code {}.".format(
+            preset_name, proc.returncode
+        ))
+        print("Full CMake output follows:")
+        print("==============================================")
+        print("============= BEGIN CMAKE OUTPUT =============")
+        print(combined)
+        print("============= END CMAKE OUTPUT =============")
+        print("==============================================")
+
     unused = extract_unused_vars(combined)
 
     if unused: