improve Visual Studio generator handling and add tests for version mapping

hanniavalera · hanniavalera · commit d36ebc90e3d6 · 2026-04-17T16:00:00.000-05:00
- Modify kit scanning logic to derive preferred generators for Visual Studio kits lacking a predefined generator.
- Introduce utility functions for mapping Visual Studio versions to CMake generators.
- Add unit tests to verify correct generator mapping for various Visual Studio versions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,7 +8,7 @@ Bug Fixes:
 ## 1.23.51
 
 Bug Fixes:
-- Fix regression where VS kits with existing Ninja cache would fail due to generator mismatch after update. [#4890](https://github.com/microsoft/vscode-cmake-tools/issues/4890)
+- Fix regression where Visual Studio kits with an existing Ninja-based build cache would fail after updating CMake Tools, due to a generator mismatch. Ninja is now preferred again when available. For stale VS kits missing `preferredGenerator`, the VS generator is derived at runtime as a last-resort fallback. A safety net auto-cleans the build directory when a generator mismatch with `CMakeCache.txt` is detected. [#4890](https://github.com/microsoft/vscode-cmake-tools/issues/4890)
 
 ## 1.23
 
diff --git a/docs/kits.md b/docs/kits.md
@@ -6,10 +6,10 @@ A _kit_ defines project-agnostic and configuration-agnostic info about how to bu
 - A Visual Studio installation: building for Visual Studio involves more than just finding the necessary compiler executable. Visual C++ requires certain environment variables to be set to tell it how to find and link to the Visual C++ toolchain headers and libraries.
 - A toolchain file: The low-level way to instruct CMake how to compile and link for a target. CMake Tools handles toolchain files using kits.
 
-Kits are mostly CMake-generator-agnostic (a CMake generator writes the input files for the native build system). The exception is Visual Studio kits: when you [scan for kits](#scan-for-kits), CMake Tools looks up the VS version and sets `preferredGenerator` on the kit to the matching CMake generator (e.g., `"Visual Studio 18 2026"` for VS 2026). This only happens at scan time. If a kit was scanned before CMake Tools knew about that VS version, the kit won't have a `preferredGenerator` and will fall through to whatever default generator is available (usually Ninja).
+Kits are mostly CMake-generator-agnostic (a CMake generator writes the input files for the native build system). The exception is Visual Studio kits: when you [scan for kits](#scan-for-kits), CMake Tools looks up the VS version and sets `preferredGenerator` on the kit to the matching CMake generator (e.g., `"Visual Studio 18 2026"` for VS 2026). If a kit was scanned before CMake Tools added support for that VS version, the extension derives the correct VS generator at runtime as a last-resort fallback — it is tried only after other generators like Ninja. If the version can't be determined, the kit falls through to default generators.
 
 > **Note:**
-> * If you use the [Ninja](https://ninja-build.org/) build system, don't worry about Visual Studio CMake Generators. CMake Tools will prefer Ninja if it is present, unless configured otherwise. A Visual Studio kit without `preferredGenerator` will just use Ninja.
+> * If you use the [Ninja](https://ninja-build.org/) build system, don't worry about Visual Studio CMake Generators. CMake Tools will prefer Ninja if it is present, unless configured otherwise or the kit has a `preferredGenerator` set at scan time. To explicitly use a specific generator, set `cmake.generator` in your settings.
 > * If you change the active kit while a project is configured, the project configuration will be re-generated with the chosen kit.
 > * When the selected generator doesn't match what's already in an existing `CMakeCache.txt`, CMake Tools cleans the prior configuration instead of letting CMake error out.
 > * Using a kit is recommended but optional. If you don't use a kit, CMake will perform its own automatic detection.
@@ -53,7 +53,7 @@ Update [user-local kits](#user-local-kits) by running **Scan for Kits** from the
 
 - CMake tools includes `vswhere.exe`, which it uses to find Visual Studio instances installed on the system.
  
-- For each of `x86`, `amd64`, `x86_amd64`, `x86_arm`, `x86_arm64`, `amd64_x86`, `amd64_arm`, and `amd64_arm64`, CMake Tools checks for installed Visual C++ environments. A kit is generated for each existing MSVC toolchain that is found. For known VS versions (2019, 2022, 2026, etc.), the kit gets a `preferredGenerator` pointing at the right CMake generator, like `"Visual Studio 18 2026"`. If CMake Tools doesn't recognize the VS version yet, `preferredGenerator` is left unset and the kit will use Ninja or whatever default is available.
+- For each of `x86`, `amd64`, `x86_amd64`, `x86_arm`, `x86_arm64`, `amd64_x86`, `amd64_arm`, and `amd64_arm64`, CMake Tools checks for installed Visual C++ environments. A kit is generated for each existing MSVC toolchain that is found. For known VS versions (2019, 2022, 2026, etc.), the kit gets a `preferredGenerator` pointing at the right CMake generator, like `"Visual Studio 18 2026"`. If the VS version wasn't recognized at scan time, CMake Tools derives the correct generator at runtime as a last-resort fallback. Re-running **Scan for Kits** will set `preferredGenerator` permanently.
 
 **3. Save results to the user-local kits file**
 
@@ -154,8 +154,9 @@ The following additional options may be specified:
 > 2. `cmake.preferredGenerators` from your settings
 > 3. The kit's `preferredGenerator` (set at scan time for VS kits)
 > 4. Fallback: Ninja, then Unix Makefiles
+> 5. For VS kits without `preferredGenerator`: the derived VS generator (last-resort fallback)
 >
-> If your kit doesn't have a `preferredGenerator` (maybe it was scanned before CMake Tools added support for that VS version), it will just use the fallback. Re-running **Scan for Kits** will pick up the correct generator.
+> If a VS kit was scanned before the VS version mapping existed, CMake Tools derives the correct generator at runtime but only as a last resort — Ninja and Unix Makefiles are tried first. To use the VS generator by default, re-run **Scan for Kits** or set `cmake.generator` in your settings.
 
 `cmakeSettings`
 
diff --git a/src/drivers/cmakeDriver.ts b/src/drivers/cmakeDriver.ts
@@ -16,7 +16,7 @@ import { CMakeOutputConsumer } from '@cmt/diagnostics/cmake';
 import { RawDiagnosticParser } from '@cmt/diagnostics/util';
 import { ProgressMessage } from '@cmt/drivers/drivers';
 import * as expand from '@cmt/expand';
-import { CMakeGenerator, effectiveKitEnvironment, Kit, kitChangeNeedsClean, KitDetect, getKitDetect, getVSKitEnvironment } from '@cmt/kits/kit';
+import { CMakeGenerator, effectiveKitEnvironment, Kit, kitChangeNeedsClean, KitDetect, getKitDetect, getVSKitEnvironment, getVsKitPreferredGenerator } from '@cmt/kits/kit';
 import * as logging from '@cmt/logging';
 import paths from '@cmt/paths';
 import { fs } from '@cmt/pr';
@@ -624,22 +624,22 @@ export abstract class CMakeDriver implements vscode.Disposable {
 
     /**
      * Check if the generator to be used differs from what is cached in CMakeCache.txt.
-     * If so, auto-clean the prior configuration to prevent CMake errors.
      */
-    protected async _cleanIfGeneratorChanged(newGeneratorName: string | undefined): Promise<void> {
+    protected async _hasGeneratorChanged(newGeneratorName: string | undefined): Promise<boolean> {
         if (!newGeneratorName) {
-            return;
+            return false;
         }
         const cachePath = this.cachePath;
         if (!await fs.exists(cachePath)) {
-            return;
+            return false;
         }
         const cache = await CMakeCache.fromPath(cachePath);
         const cachedGenerator = cache.get('CMAKE_GENERATOR');
         if (cachedGenerator && cachedGenerator.value !== newGeneratorName) {
             log.info(localize('generator.changed', 'Generator changed from {0} to {1}; cleaning prior configuration', cachedGenerator.value, newGeneratorName));
-            await this._cleanPriorConfiguration();
+            return true;
         }
+        return false;
     }
 
     /**
@@ -819,10 +819,10 @@ export abstract class CMakeDriver implements vscode.Disposable {
             await this._refreshExpansions();
             const scope = this.workspaceFolder ? vscode.Uri.file(this.workspaceFolder) : undefined;
             const newBinaryDir = util.lightNormalizePath(await expand.expandString(this.config.buildDirectory(this.isMultiProject, scope), this.expansionOptions));
-            if (needsCleanIfKitChange && (newBinaryDir === oldBinaryDir)) {
+            const generatorChanged = await this._hasGeneratorChanged(this._generator?.name);
+            if ((needsCleanIfKitChange || generatorChanged) && (newBinaryDir === oldBinaryDir)) {
                 await this._cleanPriorConfiguration();
             }
-            await this._cleanIfGeneratorChanged(this._generator?.name);
         });
     }
 
@@ -832,7 +832,7 @@ export abstract class CMakeDriver implements vscode.Disposable {
         log.debug(localize('cmakedriver.kit.set.to', 'CMakeDriver Kit set to {0}', kit.name));
         this._kitEnvironmentVariables = await effectiveKitEnvironment(kit, this.expansionOptions);
 
-        // Place a kit preferred generator at the front of the list
+        // Place a kit preferred generator at the front of the list.
         if (kit.preferredGenerator) {
             preferredGenerators.unshift(kit.preferredGenerator);
         }
@@ -848,6 +848,16 @@ export abstract class CMakeDriver implements vscode.Disposable {
             preferredGenerators.push({ name: "Unix Makefiles" });
         }
 
+        // For VS kits that don't have preferredGenerator (e.g., scanned before
+        // a VS version was added), derive the VS generator as a last-resort
+        // fallback so it is tried only after Ninja / Unix Makefiles.
+        if (!kit.preferredGenerator && kit.visualStudio) {
+            const derived = await getVsKitPreferredGenerator(kit);
+            if (derived) {
+                preferredGenerators.push(derived);
+            }
+        }
+
         // Use the "best generator" logic only if the user did not define a particular
         // generator to be used via the `cmake.generator` setting.
         if (this.config.generator) {
diff --git a/src/kits/kit.ts b/src/kits/kit.ts
@@ -800,6 +800,58 @@ const VsGenerators: { [key: string]: string } = {
     18: 'Visual Studio 18 2026'
 };
 
+/**
+ * Get the CMake generator name for a given Visual Studio major version.
+ * @param version The major version string (e.g., '17', '18')
+ * @returns The CMake generator name, or undefined if the version is not recognized
+ */
+export function vsGeneratorForVersion(version: string): string | undefined {
+    return VsGenerators[version];
+}
+
+/**
+ * Get the preferred CMake generator for a Visual Studio kit.
+ * This is useful for kits that were scanned before a VS version was added to the VsGenerators mapping.
+ * @param kit The Visual Studio kit
+ * @returns The preferred generator, or undefined if the kit is not a VS kit or the VS version is not recognized
+ */
+export async function getVsKitPreferredGenerator(kit: Kit): Promise<CMakeGenerator | undefined> {
+    if (!kit.visualStudio || !kit.visualStudioArchitecture) {
+        return undefined;
+    }
+
+    // If the kit already has a preferredGenerator, return it
+    if (kit.preferredGenerator) {
+        return kit.preferredGenerator;
+    }
+
+    // Try to derive the preferredGenerator from the VS installation
+    const vsInstall = await getVSInstallForKit(kit);
+    if (!vsInstall) {
+        return undefined;
+    }
+
+    const version = /^(\d+)+./.exec(vsInstall.installationVersion);
+    if (!version) {
+        return undefined;
+    }
+
+    const generatorName = VsGenerators[version[1]];
+    if (!generatorName) {
+        return undefined;
+    }
+
+    const majorVersion = parseInt(vsInstall.installationVersion);
+    const hostArch = kit.visualStudioArchitecture;
+    const host: string = hostArch.toLowerCase().replace(/ /g, "").startsWith("host=") ? hostArch : "host=" + hostArch;
+
+    return {
+        name: generatorName,
+        platform: generatorPlatformFromVSArch[hostArch] as string || hostArch,
+        toolset: majorVersion < 15 ? undefined : host
+    };
+}
+
 /**
  * Try to get a VSKit from a VS installation and architecture
  * @param inst A VS installation from vswhere
diff --git a/test/unit-tests/kit-scan.test.ts b/test/unit-tests/kit-scan.test.ts
@@ -240,6 +240,28 @@ suite('Kits scan test', () => {
         }).timeout(10000);
     });
 
+    suite('VS Generator mapping', () => {
+        test('returns correct generator for VS 2022', () => {
+            expect(kit.vsGeneratorForVersion('17')).to.eq('Visual Studio 17 2022');
+        });
+
+        test('returns correct generator for VS 2026', () => {
+            expect(kit.vsGeneratorForVersion('18')).to.eq('Visual Studio 18 2026');
+        });
+
+        test('returns correct generator for VS 2019', () => {
+            expect(kit.vsGeneratorForVersion('16')).to.eq('Visual Studio 16 2019');
+        });
+
+        test('returns undefined for unknown version', () => {
+            expect(kit.vsGeneratorForVersion('99')).to.be.undefined;
+        });
+
+        test('returns correct generator for legacy VS120COMNTOOLS', () => {
+            expect(kit.vsGeneratorForVersion('VS120COMNTOOLS')).to.eq('Visual Studio 12 2013');
+        });
+    });
+
     suite('Kit change detection for generator regression (#4890)', () => {
         // These tests verify kitChangeNeedsClean correctly detects generator-related
         // kit changes, which is the safety net for the regression fixed in #4890.
