diff --git a/AGENTS.md b/AGENTS.md index b2d513f..cf100da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,6 +35,7 @@ complexity or limiting improvements. Do not transliterate the legacy code. | Path | Contents | |---|---| +| `CMakeLists.txt`, `CMakePresets.json`, `cmake/` | Primary native CMake build and reusable modules | | `src/MapWinGIS.Core/` | Core engine. Public headers in `include/mapwingis/`, implementation in `src/`, grouped by area (`core`, `gdal`, `vector`, ...) | | `tests/MapWinGIS.Core.Tests/` | Core GoogleTest unit tests and shared fixtures in `TestData.h/.cpp` | | `tests/MapWinGIS.ActiveX.Tests/` | ActiveX implementation and COM-hosting GoogleTest unit tests | @@ -45,14 +46,25 @@ complexity or limiting improvements. Do not transliterate the legacy code. ```powershell pwsh -File build\scripts\bootstrap-vcpkg.ps1 +cmake --preset x64-debug +cmake --build --preset x64-debug +ctest --preset x64-debug +``` + +Until CMake registers the ActiveX tests, also build the legacy solution and run +its ActiveX suite: + +```powershell msbuild MapWinGIS6.slnx -restore -p:Configuration=Debug -p:Platform=x64 -m -bin\Debug\x64\MapWinGIS.Core.Tests.exe bin\Debug\x64\MapWinGIS.ActiveX.Tests.exe ``` -Every task must leave the tree in this state: `Debug | x64` builds with no -new Level 4 warnings and all tests pass. Full build details, vcpkg features -and switches: [docs/BUILDING.md](docs/BUILDING.md). +Every task must leave the tree in this state: CMake `Debug | x64` builds with +no new Level 4 warnings and all non-interactive tests pass. The legacy +`.slnx`/MSBuild build remains available during the transition; use it when +changing or validating that build integration. Full build details, CLion and +Visual Studio setup, vcpkg features, and switches: +[docs/BUILDING.md](docs/BUILDING.md). ## Ground rules diff --git a/README.md b/README.md index 9fc98a4..ce59397 100644 --- a/README.md +++ b/README.md @@ -39,62 +39,76 @@ release the loaded datasets before switching or refreshing them. ### Prerequisites - Windows -- Visual Studio 2026 (18.10 or later) with the **Desktop development with C++** workload, including MSVC v145 and Windows SDK 10.0.28000.0 -- CMake 3.28 or later; use the CMake version bundled with Visual Studio 2026 for its `Visual Studio 18 2026` generator -- .NET 10 SDK to build the C# ActiveX test host -- Git and PowerShell 7 (`pwsh`) +- Visual Studio 2026 (18.10 or later) with the **Desktop development with C++** workload, MSVC v145, and Windows SDK 10.0.28000.0 +- The **C++ ATL for latest v145 build tools** component for each architecture to build (x64 and/or x86) +- CMake 3.28 or later; use Visual Studio 2026's bundled CMake for the `Visual Studio 18 2026` generator +- Ninja for the CLion and command-line presets +- .NET 10 SDK and PowerShell 7 (`pwsh`) to build and run the C# ActiveX test host +- Git - About 15 GB of free disk space for dependencies and build outputs -### First build +### First build with CMake -From the repository root, bootstrap vcpkg and build the solution: +From a Visual Studio 2026 Developer PowerShell in the repository root, +bootstrap vcpkg and build and test the x64 Debug preset. The Ninja generator +uses the compiler and Windows SDK environment from the Developer shell: ```powershell pwsh -File build\scripts\bootstrap-vcpkg.ps1 -msbuild MapWinGIS6.slnx -restore -p:Configuration=Debug -p:Platform=x64 -m +cmake --preset x64-debug +cmake --build --preset x64-debug +ctest --preset x64-debug ``` -The bootstrap script clones and initializes vcpkg in a sibling `vcpkg` folder -unless an existing vcpkg installation is configured. The first build uses -vcpkg to compile GDAL and its dependencies, so it can take a while; subsequent -builds use the local binary cache. No dependency downloads or environment -configuration are needed by hand. +The first configure installs GDAL and its dependencies through vcpkg and can +take a while; later builds reuse the local binary cache. CMake outputs go under +`out\b`, separate from the legacy MSBuild output. + +The `.slnx` and `.vcxproj` projects remain available during the build-system +transition. To use the legacy MSBuild build, bootstrap vcpkg and run: -Alternatively, after bootstrapping vcpkg, open `MapWinGIS6.slnx` in Visual -Studio and build the `Debug | x64` configuration. +```powershell +msbuild MapWinGIS6.slnx -restore -p:Configuration=Debug -p:Platform=x64 -m +``` -Visual Studio 2026 can also open the repository folder as a CMake project. -Select the `vs2026-x64` configure preset, then build and test with the matching -`vs2026-x64-debug` preset. The existing `.slnx` remains available during the -transition; both build systems keep their outputs separate. See -[docs/BUILDING.md](docs/BUILDING.md#using-cmake-in-visual-studio) for details. +Visual Studio 2026 can open the repository folder as a CMake project. Select +the `vs2026-x64` configure preset and the matching `vs2026-x64-debug` build +preset. See [docs/BUILDING.md](docs/BUILDING.md) for Visual Studio, CLion, +command-line, and legacy MSBuild setup. ### Run the C++ tests -The solution build includes both GoogleTest projects by default. After -building, run the test executables from the repository root: +CTest runs the CMake-built test cases: + +```powershell +ctest --preset x64-debug +``` + +For the legacy MSBuild build, run its test executables from the repository root: ```powershell bin\Debug\x64\MapWinGIS.Core.Tests.exe bin\Debug\x64\MapWinGIS.ActiveX.Tests.exe ``` -You can also run the tests through Visual Studio's Test Explorer. For the -Release configuration, build with `-p:Configuration=Release` and run +Visual Studio's CMake project exposes discovered tests in Test Explorer. The +legacy `.slnx` tests also remain available through Test Explorer. For a legacy +Release build, run `bin\Release\x64\MapWinGIS.Core.Tests.exe` and `bin\Release\x64\MapWinGIS.ActiveX.Tests.exe`. For additional configurations, dependency features, and troubleshooting, see [docs/BUILDING.md](docs/BUILDING.md). -The CMake build also provides the native `translate` sample and targets for -building and running the C# ActiveX test host. See the CMake section in the -build guide for target names and commands. +The CMake build can also include the native `translate` sample and targets for +building and running the C# ActiveX test host. Configure with +`-DMWG_BUILD_SAMPLES=ON` to enable them; see the CMake section in the build +guide for target names and commands. CI Release artifacts use the `full-drivers` feature. Their tests require HDF5, NetCDF, KML, SpatiaLite, and PostgreSQL support. -Pull requests build and test both Debug and full-driver Release for x64. -Each CI build has a 180-minute timeout. +Pull requests build and test Debug and full-driver Release for x64 using both +CMake and MSBuild. Each CI build has a 180-minute timeout. After vector geometry edits, call `VectorDataset::Flush()` before closing to persist exact Shapefile and GeoPackage bounds. The flush batches stored-extent diff --git a/docs/BUILDING.md b/docs/BUILDING.md index ac3c5f9..df91671 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -5,28 +5,45 @@ | Requirement | Version | Notes | |---|---|---| | Visual Studio 2026 | 18.10 or later | Workload **Desktop development with C++** | -| CMake | 3.28 or later | Bundled with Visual Studio 2026 | +| CMake | 3.28 or later | Use the Visual Studio 2026-bundled version for its generator | +| Ninja | Current | Required by the Ninja presets and CLion profiles | | MSVC toolset | v145 (14.51 or later) | Installed with the workload | | Windows SDK | 10.0.28000.0 | Override with `/p:MwgWindowsSdk=10.0` to use the newest installed instead | +| ATL | C++ ATL for latest v145 build tools | Install for each architecture used (x64 and/or x86); MFC is not required | | Git | any recent version | Needed to clone vcpkg | +| .NET SDK | 10 | Required for the C# ActiveX test host | +| PowerShell | 7 (`pwsh`) | Required by the bootstrap and host scripts | | Disk space | about 15 GB | vcpkg sources, build trees and binaries | -The ActiveX project uses ATL and statically links it. MFC is not required. -The C# test host requires the .NET 10 SDK and the Windows Forms desktop -runtime. +The ActiveX project uses ATL and statically links it. -## First build +## First build with CMake ```powershell -# 1. Get vcpkg. Clones into ..\vcpkg next to this repository by default. +# From a VS 2026 Developer PowerShell: bootstrap, configure, build, and test x64 Debug. pwsh -File build\scripts\bootstrap-vcpkg.ps1 +cmake --preset x64-debug +cmake --build --preset x64-debug +ctest --preset x64-debug +``` + +The first configure installs GDAL and its dependencies and can take a while; +later builds reuse the vcpkg binary cache. See [Building with CMake](#building-with-cmake) +for other presets, Visual Studio, and CLion. -# 2. Build. The first build compiles GDAL and its dependencies from source and -# takes a while; later builds reuse the vcpkg binary cache. +## Legacy MSBuild build + +The `.slnx` and `.vcxproj` files remain supported during the CMake transition +and are built in parallel in CI. After bootstrapping vcpkg, use: + +```powershell msbuild MapWinGIS6.slnx -restore -p:Configuration=Debug -p:Platform=x64 -m ``` -Or just open `MapWinGIS6.slnx` in Visual Studio after step 1 and build. +Or open `MapWinGIS6.slnx` in Visual Studio. The legacy build writes to +`bin\\`; CMake writes under `out\b`, so their outputs +do not overwrite one another. If `msbuild` is not on `PATH`, see +[Finding MSBuild](#finding-msbuild-for-the-legacy-build). ### ActiveX activation @@ -142,7 +159,7 @@ paths can contain spaces. | Configurations | `Debug` (`/MDd`, `_DEBUG`), `Release` (`/MD`, `/O2`) | | Platforms | `x64`, `Win32` | | Triplets | `x64-windows-v145`, `x86-windows-v145` (in `build/triplets`, pinned to v145) | -| Output | `bin\\\` | +| Output | MSBuild: `bin\\\`; CMake build tree: `out\b\\` (runtime files under `bin\`) | | Intermediates | `obj\\\\` | Nothing is written outside the repository and no environment variables are @@ -170,8 +187,8 @@ CI uses this feature set for Release artifacts. Core tests built with `full-drivers` require HDF5, NetCDF, LIBKML, PostgreSQL, and SpatiaLite support. The SpatiaLite test creates a spatial database without an external server. Pull requests and pushes to `development` build and test Debug and full-driver -Release for x64. Pushes to `main` also cover Win32. Each job has a -180-minute timeout. +Release for x64 with both CMake and MSBuild. Pushes to `main` also cover Win32. +Each job has a 180-minute timeout. ### Runtime data @@ -195,7 +212,9 @@ rebuild or a second platform is fast. To share a cache across machines, set $env:VCPKG_BINARY_SOURCES = 'clear;files,\\server\share\vcpkg-cache,readwrite' ``` -## Running the tests +## Running the legacy MSBuild tests + +These commands run the MSBuild test executables: ```powershell bin\Debug\x64\MapWinGIS.Core.Tests.exe @@ -224,47 +243,89 @@ bin\Release\x64\MapWinGIS.ActiveX.Tests.exe --gtest_output=xml:activex-testresul ## CMake migration -CMake is being introduced as the primary native build. Until it is complete, -the MSBuild solution above stays the supported build. The audit of the current -MSBuild settings and the decisions the CMake build follows are in +CMake is the primary native build. The `.slnx` and `.vcxproj` files remain +supported during the transition, and CI validates both build systems. The +audit of the MSBuild settings and the decisions followed by CMake are in [CMAKE-MIGRATION.md](CMAKE-MIGRATION.md). To measure flag and binary parity, `build\scripts\Compare-CompileCommands.ps1` records a detailed MSBuild log and writes a normalised report to `out\parity\`. -It finds MSBuild through `MWG_MSBUILD`, `PATH` or `vswhere`, so it also works -when Visual Studio is not on `PATH` or not installed on `C:`. +It finds MSBuild through `MWG_MSBUILD`, `PATH`, or `vswhere`, including Visual +Studio installations outside the default `C:\Program Files` location. + +### Finding MSBuild for the legacy build + +MSBuild is not normally on `PATH` in a plain PowerShell or CLion terminal. Use +a Visual Studio Developer PowerShell, set `MWG_MSBUILD` for the parity script, +or locate the executable with `vswhere`: + +```powershell +$vswhere = Join-Path ${env:ProgramFiles(x86)} 'Microsoft Visual Studio\Installer\vswhere.exe' +$msbuild = & $vswhere -latest -products '*' -requires Microsoft.Component.MSBuild ` + -find 'MSBuild\**\Bin\MSBuild.exe' | Select-Object -First 1 +if (-not $msbuild) { throw 'MSBuild was not found. Install the Visual Studio MSBuild component.' } +& $msbuild MapWinGIS6.slnx -restore -p:Configuration=Debug -p:Platform=x64 -m +``` + +The parity script checks `MWG_MSBUILD`, then `PATH`, then `vswhere`. Do not +hardcode a Visual Studio installation path in repository files. ### Building with CMake -The CMake build covers `MapWinGIS.Core.dll`, `MapWinGIS.ocx`, the native -GoogleTest suite, and the `translate` sample. When `dotnet` and PowerShell 7 -are installed, it also provides targets to build and launch the C# ActiveX -test host. The OCX needs the **C++ ATL for latest v145 build tools** component -for each architecture you build. For Ninja, `midl.exe` needs `cl.exe` on -`PATH`, so use a Visual Studio toolchain (CLion) or a Developer PowerShell. -The Visual Studio generator uses the selected SDK's MIDL compiler and the -compiler environment supplied by MSBuild. CMake 3.28 or later is required; -use the CMake version bundled with Visual Studio 2026 for its Visual Studio 18 -2026 generator. Both CMake and Ninja ship with Visual Studio 2026 and CLion. -Run the bootstrap script first. For Ninja presets, configure from a VS 2026 -Developer PowerShell or any shell after `vcvarsall.bat x64`: +The CMake build covers `MapWinGIS.Core.dll`, `MapWinGIS.ocx`, and the Core +GoogleTest suite. It does not yet build the ActiveX-specific test executable; +run the legacy ActiveX tests until CMake registers that suite. Set +`MWG_BUILD_SAMPLES=ON` to add the `translate` sample and, when .NET and +PowerShell 7 are installed, targets to build and launch the C# ActiveX test +host. The OCX needs the **C++ ATL for latest v145 build tools** component for +each architecture you build. CMake 3.28 or later is required; use the Visual +Studio 2026-bundled CMake for the Visual Studio 18 2026 generator. Run the +vcpkg bootstrap first. Ninja presets need an MSVC environment: use a Visual +Studio toolchain in CLion or configure from a VS 2026 Developer PowerShell. +With the Ninja generator, MIDL also needs `cl.exe` on `PATH`. ```powershell pwsh -File build\scripts\bootstrap-vcpkg.ps1 cmake --preset x64-debug cmake --build --preset x64-debug -ctest --preset x64-debug --output-on-failure +ctest --preset x64-debug +``` + +The root `CMakeLists.txt` resolves the vcpkg root before `project()` in this +order: `MWG_VCPKG_ROOT` (cache variable or environment variable), the sibling +`..\vcpkg` directory, then `VCPKG_ROOT`. Set `MWG_VCPKG_ROOT` to override the +location. A `CMAKE_TOOLCHAIN_FILE` supplied by a preset or command line takes +precedence over automatic resolution. If no root is found, run the bootstrap +script above. + +The CMake build uses a separate vcpkg install tree per platform under +`vcpkg_installed\cmake-x64` or `vcpkg_installed\cmake-Win32`. Debug and Release +share the platform tree; it is separate from the MSBuild install. vcpkg +reconfigures the tree using `VCPKG_MANIFEST_FEATURES` on every CMake configure. +Feature changes take effect after reconfiguring. In CLion, use **Tools | CMake +| Reset Cache and Reload Project** if a cached preset value is stale. + +Sample and C# host targets are optional. Enable them when configuring: + +```powershell +cmake --preset x64-debug -DMWG_BUILD_SAMPLES=ON ``` -Build the sample or C# host by target: +Then build individual targets: ```powershell +cmake --build --preset x64-debug --target MapWinGIS.Core +cmake --build --preset x64-debug --target MapWinGIS.ActiveX cmake --build --preset x64-debug --target MapWinGIS.Samples.Translate cmake --build --preset x64-debug --target build_activex_host cmake --build --preset x64-debug --target run_activex_host cmake --build --preset x64-debug --target run_activex_host_automated ``` +The sample executable is `out\b\x64d\bin\translate.exe`. The C# host targets +need .NET 10; the two run targets also need PowerShell 7 and an interactive +desktop session. + The last two targets launch the host from an interactive Windows session; the automated target runs the visible host checks. CMake directs the native sample, host, OCX, Core DLL and deployed runtime dependencies into the selected build @@ -287,9 +348,9 @@ For a Core-only build that does not require MIDL or ATL, configure with - To register the CMake-built control for the current user: `regsvr32 /n /i:user out\b\x64d\bin\MapWinGIS.ocx` (use `%WINDIR%\SysWOW64\regsvr32.exe` for Win32; add `/u` to unregister). -- The vcpkg root is found in the same order as above. CMake uses its own install - tree, `vcpkg_installed\cmake-`, shared by Debug and Release; the - binary cache makes it cheap. +- CMake uses its own install tree, `vcpkg_installed\cmake-`, shared + by Debug and Release and separate from the MSBuild tree; the binary cache + makes it cheap. - Manifest features come from `VCPKG_MANIFEST_FEATURES` (presets: `tests`). A change takes effect on the next configure; in CLion use **Tools | CMake | Reset Cache and Reload Project** when a cached value is stale. @@ -303,15 +364,24 @@ For a Core-only build that does not require MIDL or ATL, configure with (`amd64` for x64, `x86` or `amd64_x86` for x86); a mismatch stops configure with an explanation. -| CMake option | Default | MSBuild equivalent | +| CMake setting | Default / unset behavior | MSBuild equivalent | |---|---|---| -| `MWG_WINDOWS_SDK` | `10.0.28000.0` | `MwgWindowsSdk` (`10.0` = newest) | +| `MWG_WINDOWS_SDK` | `10.0.28000.0` | `MwgWindowsSdk` (`10.0` selects newest) | | `MWG_VCPKG_ROOT` | resolved | `MwgVcpkgRoot` | | `VCPKG_MANIFEST_FEATURES` | `tests` | `MwgVcpkgFeatures` | | `MWG_ENABLE_ASAN` | `OFF` | `MwgEnableAsan` | | `MWG_DEPLOY_RUNTIME_DATA` | `ON` | `MwgDeployRuntimeData` | | `MWG_BUILD_TESTS` | `ON` | — (adds the `tests` feature) | | `MWG_BUILD_ACTIVEX` | `ON` | — (set `OFF` for a Core-only build) | +| `MWG_BUILD_SAMPLES` | unset (false in `if()`) | — | + +`MWG_BUILD_SAMPLES` is read by CMake but is not declared with `option()`. +Passing `-DMWG_BUILD_SAMPLES=ON` sets it for that configure; because there is +no declared option, it has no default cache entry and typos are not checked. + +With the CMake Visual Studio generator, `MWG_WINDOWS_SDK=10.0` selects the +newest installed SDK. With Ninja, `10.0` accepts the SDK already selected by +`vcvars`; Ninja cannot select or pin an SDK. Machine-specific settings belong in an uncommitted `CMakeUserPresets.json` that inherits from the presets, for example: @@ -325,6 +395,44 @@ that inherits from the presets, for example: } ``` +### Using CMake in CLion + +1. Install CLion with CMake and Ninja available. Bootstrap vcpkg and run one + command-line configure before the first CLion reload: + + ```powershell + pwsh -File build\scripts\bootstrap-vcpkg.ps1 + cmake --preset x64-debug + ``` + + This starts the first GDAL build in a visible command window instead of + leaving CLion apparently idle during its reload. +2. Open the repository root folder in CLion as a CMake project. Select the + root `CMakeLists.txt`; do not open `.mscppls\compile_commands.json` as the + project. That database is produced by the legacy MSBuild tooling and is not + the CMake project. +3. In **Settings | Build, Execution, Deployment | Toolchains**, add a Visual + Studio toolchain for each architecture. Use `amd64` for x64 and `x86` or + `amd64_x86` for Win32. The toolchain must provide the MSVC compiler + environment and `cl.exe` on `PATH` for MIDL. +4. In **Settings | Build, Execution, Deployment | CMake**, use the configure + profiles imported from `CMakePresets.json`. Assign the matching Visual + Studio toolchain to each profile. The preset's `architecture` field informs + Visual Studio but does not select CLion's toolchain architecture. Disable + CLion's extra default profiles, such as `RelWithDebInfo` and `MinSizeRel`; + only Debug and Release are supported. +5. Reload the project and select the profile for the desired architecture and + configuration. For x86, use `x86-debug` or `x86-release` with the matching + x86 toolchain. + +Build `MapWinGIS.Core`, `MapWinGIS.ActiveX`, and `MapWinGIS.Core.Tests` from +CLion's CMake targets. To expose the sample and C# host targets, set +`MWG_BUILD_SAMPLES=ON` in the selected CMake profile. CLion's GoogleTest +integration can run, filter, and debug individual cases. The C# host can be +built and launched through `build_activex_host` and `run_activex_host`; +CLion's native debugger does not debug the managed C# code. See +[Testing](TESTING.md#cmake-and-clion) for test-running details. + ### Using CMake in Visual Studio The CMake presets support Visual Studio 2026's **Open Folder** workflow. First @@ -357,3 +465,35 @@ off. Rebuild after running the bootstrap script. The triplets pin `VCPKG_PLATFORM_TOOLSET v145`. If an older Visual Studio is still selected, check that the VS 2026 C++ workload is installed and delete `vcpkg_installed\` before rebuilding. + +**CMake reports a stale preset value or missing manifest feature** +Reconfigure after changing `VCPKG_MANIFEST_FEATURES` or another cached value. +In CLion, select **Tools | CMake | Reset Cache and Reload Project**. + +**vcpkg fails because a build path is too long** +Use the short preset build directories under `out\b`. If Windows still rejects +long paths, enable the Windows `LongPathsEnabled` policy and restart the +terminal before configuring again. + +**MIDL cannot find `cl.exe`** +Ninja needs an MSVC environment. Assign the matching Visual Studio toolchain +to the CLion profile, or configure from a VS 2026 Developer PowerShell. Ensure +`cl.exe` is on `PATH` before rerunning CMake. + +**ATL headers or libraries are missing** +Install **C++ ATL for latest v145 build tools** in Visual Studio Installer for +each target architecture. The x86 ATL component is needed for Win32 builds; +the x64 component alone is not enough. + +**Ninja reports a Windows SDK mismatch** +Ninja takes the SDK from the vcvars environment and cannot pin it. Set the +Visual Studio toolchain's Windows SDK version to `MWG_WINDOWS_SDK`, or use +`-DMWG_WINDOWS_SDK=10.0` to accept the SDK already selected by vcvars. For the +Visual Studio generator, `10.0` selects the newest installed SDK. + +**The C# ActiveX test host cannot find the OCX or executable** +The CMake `run_activex_host` targets pass the runtime directory automatically. +When launching the C# host script directly, pass that directory with +`-BinDirectory`, for example `-BinDirectory out\b\x64d\bin`. This directory +override does not enable native ActiveX hosting verification: that check +requires the legacy `MapWinGIS.ActiveX.Tests.exe` and its hosting test. diff --git a/docs/CMAKE-MIGRATION.md b/docs/CMAKE-MIGRATION.md index 81efd73..6d5177a 100644 --- a/docs/CMAKE-MIGRATION.md +++ b/docs/CMAKE-MIGRATION.md @@ -389,3 +389,32 @@ Measured for Debug and Release, x64 and Win32 (Ninja presets): passed all 14 checks. The legacy MSBuild host project also built. - CLion's host run configuration and launching the sample from CLion were not checked interactively. + +## Legacy build decision gate + +**Decision:** retain the `.slnx` and `.vcxproj` files during the transition. +Do not remove them automatically when Phase 6 documentation is complete. + +**Target review date:** 2027-01-15. Revisit this date if the required CI +observation period has not finished by then. + +Review removal only after all of the following are true: + +- Phase 1–5 acceptance criteria are met and their results are recorded. +- Both CMake and MSBuild CI jobs have been green for at least four consecutive + weeks. +- No open issues remain that are tagged or identified as CMake parity gaps. +- The build and test documentation reflects the supported workflows and the + limitations that remain. + +The gate is not met yet. The Phase 5 pull request's GitHub Actions results and +interactive Visual Studio checks (IntelliSense, debugging, and Test Explorer) +remain unverified. CLion's preset loading, individual-test debugging, and +sample/host launching also need interactive verification. Ninja cannot pin the +MSVC toolset or Windows SDK, and CLion's native debugger does not debug the +managed C# host. GUI and registry-changing checks require an interactive +Windows session and remain excluded from headless CI. + +At the review, record the decision, review date, evidence, and any remaining +limitations. Removing the legacy project files requires a separate, +deliberate change after the gate passes. diff --git a/docs/TESTING.md b/docs/TESTING.md index 27ed7ae..661c823 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -6,6 +6,7 @@ - Core test project: `tests/MapWinGIS.Core.Tests`, built with the solution or CMake. - ActiveX test project: `tests/MapWinGIS.ActiveX.Tests`, built with the solution. +- CMake currently registers the Core suite, not the ActiveX-specific tests. - ActiveX implementation units shared by the OCX and its tests are built as `MapWinGIS.ActiveX.Impl.lib`. - Shared fixtures and helpers live in `TestData.h/.cpp` (`TempDirectory`, @@ -14,7 +15,9 @@ `MakeRectanglesDataset` writes one rectangle per given extent, so map tests can place layers at chosen coordinates or create an empty layer. -## Running +## Running the legacy MSBuild tests + +Run the MSBuild test executables from the repository root: ```powershell bin\Debug\x64\MapWinGIS.Core.Tests.exe @@ -28,56 +31,74 @@ up automatically). ### CMake and CTest -The CMake test target uses the same GoogleTest sources and fixtures: +The CMake target registers the Core GoogleTest sources and fixtures; the +ActiveX-specific tests remain MSBuild-only: ```powershell cmake --preset x64-debug cmake --build --preset x64-debug -ctest --preset x64-debug --output-on-failure +ctest --preset x64-debug ``` -`gtest_discover_tests()` discovers individual cases before CTest runs them. -Each test runs from the build's runtime directory, which contains the OCX, -dependent DLLs, and GDAL/PROJ data. GoogleTest writes per-test XML files under -`test-results` in the build directory. CTest can also write a single JUnit -report with `ctest --test-dir out/b/x64d --output-junit out/b/x64d/ctest.xml`. +`gtest_discover_tests()` registers individual cases for CTest. Each test runs +from the build's runtime directory, which contains the OCX, dependent DLLs, +and GDAL/PROJ data. GoogleTest writes per-test XML files under `test-results` +in the build directory. The `x64-debug` test preset already shows output on +failure and excludes tests labelled `interactive`, which change per-user COM +registration or require a desktop. CTest can also write a single JUnit report: + +```powershell +ctest --test-dir out\b\x64d --output-on-failure -LE interactive ` + --output-junit out\b\x64d\ctest.xml +``` To run one case from CTest, match its fully qualified GoogleTest name: ```powershell -ctest --test-dir out/b/x64d -R 'VectorDatasetTest.ReportsTheDriverAndPath' --output-on-failure +ctest --test-dir out\b\x64d -R 'VectorDatasetTest.ReportsTheDriverAndPath' --output-on-failure ``` -## ActiveX host integration checks +### CMake and CLion -### Registered native control check +Use the imported `CMakePresets.json` profile for the desired +architecture/configuration. CMake registers individual GoogleTest cases for +IDE discovery; CLion's GoogleTest integration can display them after reload. +Run or debug a test from the test tree, and use the GoogleTest filter field to +run a subset. The executable and its runtime dependencies are colocated, so +CLion can launch it directly without a CTest environment setting. -The native verification script registers the control for the current user, -creates it through its ProgID, checks the automation boundary, and removes -the per-user registration. It checks both per-user registry views first and -refuses to run if the control's CLSID or either ProgID is already registered. -Run it from a PowerShell process that matches the target architecture: +From the command line, CTest can run a GoogleTest filter by selecting matching +registered test names with `-R`. To pass a GoogleTest filter directly to the +test executable, run it from its CMake runtime directory: ```powershell -pwsh -File tests\MapWinGIS.ActiveX.Tests\Verify-ActiveXActivation.ps1 -Configuration Debug -Platform x64 +Push-Location out\b\x64d\bin +.\MapWinGIS.Core.Tests.exe '--gtest_filter=VectorDatasetTest.*' +Pop-Location ``` -For a CMake build, pass its runtime directory: +## ActiveX host integration checks -```powershell -pwsh -File tests\MapWinGIS.ActiveX.Tests\Verify-ActiveXActivation.ps1 ` - -Platform x64 -BinDirectory out\b\x64d\bin -TestExecutable MapWinGIS.Core.Tests.exe -``` +### Registered native control check -CTest registers this registration-based check with the `interactive` label -when a matching PowerShell process is available. It changes the per-user COM -registration and is excluded from the CTest presets and CI; run it explicitly -from an interactive desktop when needed: +The native verification script registers the control for the current user, +creates it through its ProgID, checks the automation boundary, and runs the +registered-control hosting test. It checks both per-user registry views first +and refuses to run if the control's CLSID or either ProgID is already +registered. Run it from a PowerShell process that matches the target +architecture: ```powershell -ctest --test-dir out/b/x64d -R '^Verify-ActiveXActivation$' --output-on-failure +pwsh -File tests\MapWinGIS.ActiveX.Tests\Verify-ActiveXActivation.ps1 -Configuration Debug -Platform x64 ``` +The native script requires `MapWinGIS.ActiveX.Tests.exe` and its +`ActiveXHosting.ResizesRepaintsAndRecreatesControl` test, which CMake does not +currently build. Use the MSBuild output for this verification until CMake +registers the ActiveX test suite. CMake's `Verify-ActiveXActivation` CTest +entry currently uses `MapWinGIS.Core.Tests.exe`, which does not contain that +hosting test and is not a substitute for this check. + ## Build configuration tests ```powershell @@ -152,6 +173,9 @@ are not currently part of CI. The host executable accepts `--automated`, `--results `, and `--timeout-seconds <5-300>`. The PowerShell launcher supplies these options and starts the host without changing COM registration. +For CMake output, the C# launcher accepts `-BinDirectory out\b\x64d\bin`; +this override applies to the C# host and does not change the native +verification script's test executable. For build and manual-use instructions, see the [ActiveX Test Host README](../samples/CSharp/ActiveXTestHost/README.md).