Support kit environment variables in cmake.cmakePath resolution (#4475) (#4867)

* Enable environmentsetupscript for kits

* cache calls to avoid redundant calls

* remove popup and log event instead

---------

Co-authored-by: Hannia Valera <[email protected]>

Author: Omotola

CHANGELOG.md

@@ -42,6 +42,7 @@ Improvements:
 - Set the `VSCODE_CMAKE_TOOLS` environment variable for all spawned subprocesses so that `CMakeLists.txt` can detect when CMake is run from VS Code. [#4233](https://github.com/microsoft/vscode-cmake-tools/issues/4233)
 - Ensure kit `environmentVariables` expansions (for example, `${env:PATH}` or `${env.PATH}`) use the environment produced by `environmentSetupScript`, so script-updated values are preserved during expansion. [#4091](https://github.com/microsoft/vscode-cmake-tools/issues/4091)
 - Honor `debugger.workingDirectory` from the CMake File API when debugging a target, so that the `DEBUGGER_WORKING_DIRECTORY` target property is used as the debugger working directory. [#4595](https://github.com/microsoft/vscode-cmake-tools/issues/4595)
+- Honor the active kit environment (including `environmentSetupScript` and kit-defined environment variables) when resolving `cmake.cmakePath` in kits mode, enabling `auto`/`cmake` mode discovery and `${env:...}` substitutions to use kit-provided environment values. [#4475](https://github.com/microsoft/vscode-cmake-tools/issues/4475)
 - Add `cmake.removeStaleKitsOnScan` setting to optionally remove stale compiler kits from the kit picker after a "Scan for Kits" when they are no longer rediscovered. This is useful after compiler upgrades that leave older versions outside `PATH`. Set `"keep": true` in a kit entry to prevent automatic removal. [#3852](https://github.com/microsoft/vscode-cmake-tools/issues/3852)
 - Add `pr-readiness` Copilot skill to verify PRs have a descriptive title, meaningful description, and a properly formatted CHANGELOG entry. [#4862](https://github.com/microsoft/vscode-cmake-tools/pull/4862)
 

docs/kits.md

@@ -190,6 +190,40 @@ The following additional options may be specified:
 > The absolute path to a script or a string in form of `"script path" [arg ...]`that modifies/adds environment variables for the kit. 
 Uses `call` on Windows and `source` in `bash` otherwise.
 
+### Kit environment and CMake executable resolution
+
+When using kits mode (not CMake Presets), the active kit's environment—including variables set via `environmentSetupScript` and `environmentVariables`—influences how CMake Tools resolves the CMake executable path:
+
+1. **Auto discovery (`cmake.cmakePath: auto` or `cmake`):**  
+   The active kit's `PATH` is searched first before falling back to the system `PATH`. This allows a kit's setup script to prepend a custom directory containing a CMake binary, and that binary will be discovered and used.
+
+2. **Environment variable substitution:**  
+   If `cmake.cmakePath` uses `${env:VARIABLE_NAME}` syntax, the substitution resolves to values from the active kit's environment. For example, if a kit defines `MY_CMAKE_PATH` via `environmentVariables` or `environmentSetupScript`, you can set `"cmake.cmakePath": "${env:MY_CMAKE_PATH}/cmake"` and it will resolve using the kit-provided value.
+
+**Example:**
+
+In `.vscode/cmake-kits.json`, define the environment variable in the kit:
+```json
+[
+  {
+    "name": "Cross-Compile Kit",
+    "environmentSetupScript": "${workspaceFolder}/scripts/setup.sh",
+    "environmentVariables": {
+      "MY_CMAKE_PATH": "/custom/cmake/path"
+    }
+  }
+]
+```
+
+In `.vscode/settings.json`, reference the variable (do not define it here):
+```json
+{
+  "cmake.cmakePath": "${env:MY_CMAKE_PATH}/cmake"
+}
+```
+
+When this kit is selected, `cmake.cmakePath` will resolve to `/custom/cmake/path/cmake` using the kit's environment variable. Environment variables are resolved from the active kit's context, not from workspace settings.
+
 `description`
 
 > A short description of the kit, which will appear next to its name in the selection menu.

src/cmakeProject.ts

@@ -30,7 +30,7 @@ import { CMakeBuildConsumer } from '@cmt/diagnostics/build';
 import { CMakeOutputConsumer } from '@cmt/diagnostics/cmake';
 import { addDiagnosticToCollection, diagnosticSeverity, populateCollection } from '@cmt/diagnostics/util';
 import { expandStrings, expandString, ExpansionOptions } from '@cmt/expand';
-import { CMakeGenerator, Kit, SpecialKits } from '@cmt/kits/kit';
+import { CMakeGenerator, Kit, SpecialKits, effectiveKitEnvironment } from '@cmt/kits/kit';
 import * as logging from '@cmt/logging';
 import { fs } from '@cmt/pr';
 import { buildCmdStr, DebuggerEnvironmentVariable, ExecutionResult, ExecutionOptions } from './proc';
@@ -843,7 +843,9 @@ export class CMakeProject {
         // Force re-reading of cmake exe, this will ensure that the debugger capabilities are updated.
         const cmakeInfo = await this.getCMakeExecutable();
         if (!cmakeInfo.isPresent) {
-            void vscode.window.showErrorMessage(localize('bad.executable', 'Bad CMake executable: {0}. Check to make sure it is installed or the value of the {1} setting contains the correct path', `"${cmakeInfo.path}"`, '"cmake.cmakePath"'));
+            // Do not show a popup here to avoid duplicate "Bad CMake executable" messages.
+            // The canonical user-facing error is shown when a command actually needs a driver
+            // and getCMakeDriverInstance() validates the executable.
             telemetry.logEvent('CMakeExecutableNotFound');
         }
 
@@ -1399,21 +1401,34 @@ export class CMakeProject {
     }
 
     async setKit(kit: Kit | null) {
+        const priorCMakePath = await this.getCMakePathofProject(); // used for later comparison to determine if we need to update the driver's cmake.
         this._activeKit = kit;
+        this.cachedCMakePathEnvironment = null;  // Invalidate cache on kit change
+        this.cachedCMakePathEnvironmentKit = null;
         if (kit) {
             log.debug(localize('injecting.new.kit', 'Injecting new Kit into CMake driver'));
             const drv = await this.cmakeDriver;  // Use only an existing driver, do not create one
             if (drv) {
                 try {
                     this.statusMessage.set(localize('reloading.status', 'Reloading...'));
                     await drv.setKit(kit, this.getPreferredGenerators());
+
+                    const updatedCMakePath = await this.getCMakePathofProject();
+
+                    // check if we need to update the driver's cmake, if so, update.
+                    if (priorCMakePath !== updatedCMakePath) {
+                        drv.cmake = await this.getCMakeExecutable();
+                    }
+
                     await this.workspaceContext.state.setActiveKitName(this.folderName, kit.name, this.isMultiProjectFolder);
                     this.statusMessage.set(localize('ready.status', 'Ready'));
                 } catch (error: any) {
                     void vscode.window.showErrorMessage(localize('unable.to.set.kit', 'Unable to set kit {0}.', `"${error.message}"`));
                     this.statusMessage.set(localize('error.on.switch.status', 'Error on switch of kit ({0})', error.message));
                     this.cmakeDriver = Promise.resolve(null);
                     this._activeKit = null;
+                    this.cachedCMakePathEnvironment = null;  // Invalidate cache on error
+                    this.cachedCMakePathEnvironmentKit = null;
                 }
             } else {
                 // Remember the selected kit for the next session.
@@ -1422,9 +1437,36 @@ export class CMakeProject {
         }
     }
 
+    private async getCMakePathEnvironment(): Promise<Environment | undefined> {
+        if (this.useCMakePresets || !this.activeKit) {
+            return undefined;
+        }
+
+        // Return cached result if kit hasn't changed
+        if (this.cachedCMakePathEnvironmentKit === this.activeKit && this.cachedCMakePathEnvironment !== null) {
+            return this.cachedCMakePathEnvironment === undefined ? undefined : this.cachedCMakePathEnvironment;
+        }
+
+        try {
+            const expansionOptions = await this.getExpansionOptions();
+            const result = await effectiveKitEnvironment(this.activeKit, expansionOptions);
+            // Cache the result: store undefined as a marker to avoid re-computation
+            this.cachedCMakePathEnvironment = result || undefined;
+            this.cachedCMakePathEnvironmentKit = this.activeKit;
+            return result;
+        } catch (e: any) {
+            log.warning(localize('failed.to.compute.kit.env.for.cmake.path', 'Unable to evaluate the active kit environment while resolving cmake.cmakePath: {0}', e?.message || e));
+            // Cache the error result as undefined
+            this.cachedCMakePathEnvironment = undefined;
+            this.cachedCMakePathEnvironmentKit = this.activeKit;
+            return undefined;
+        }
+    }
+
     async getCMakePathofProject(): Promise<string> {
         const overWriteCMakePathSetting = this.useCMakePresets ? this.configurePreset?.cmakeExecutable : undefined;
-        return await this.workspaceContext.getCMakePath(overWriteCMakePathSetting) || '';
+        const envOverride = await this.getCMakePathEnvironment();
+        return await this.workspaceContext.getCMakePath(overWriteCMakePathSetting, envOverride) || '';
     }
 
     async getCMakeExecutable() {
@@ -1539,6 +1581,12 @@ export class CMakeProject {
         return this._activeKit;
     }
 
+    /**
+     * Cache for CMake path environment to avoid redundant shell script executions
+     */
+    private cachedCMakePathEnvironment: Environment | undefined | null = null;
+    private cachedCMakePathEnvironmentKit: Kit | null = null;
+
     /**
      * The compilation database for this driver.
      */

src/paths.ts

@@ -11,6 +11,7 @@ import { vsInstallations } from '@cmt/installs/visualStudio';
 import { expandString } from '@cmt/expand';
 import { fs } from '@cmt/pr';
 import * as util from '@cmt/util';
+import { Environment } from '@cmt/environmentVariables';
 
 interface VSCMakePaths {
     cmake?: string;
@@ -189,16 +190,30 @@ class Paths {
         return this._ninjaPath;
     }
 
-    async which(name: string): Promise<string | null> {
+    private pathFromEnvironment(envOverride?: Environment): string | undefined {
+        if (!envOverride) {
+            return undefined;
+        }
+        // EnvironmentUtils.create() normalizes key casing on Windows, but keep a fallback for plain process env records.
+        return envOverride['PATH'] || envOverride['Path'] || undefined;
+    }
+
+    async which(name: string, envOverride?: Environment): Promise<string | null> {
         return new Promise<string | null>(resolve => {
-            which(name, (err, resolved) => {
+            const pathOverride = this.pathFromEnvironment(envOverride);
+            const cb = (err: Error | null, resolved?: string) => {
                 if (err) {
                     resolve(null);
                 } else {
                     console.assert(resolved, '`which` didn\'t do what it should have.');
                     resolve(resolved!);
                 }
-            });
+            };
+            if (pathOverride) {
+                which(name, { path: pathOverride }, cb);
+            } else {
+                which(name, cb);
+            }
         });
     }
 
@@ -248,17 +263,17 @@ class Paths {
         }
     }
 
-    async getCMakePath(wsc: DirectoryContext, overWriteCMakePathSetting?: string): Promise<string | null> {
+    async getCMakePath(wsc: DirectoryContext, overWriteCMakePathSetting?: string, envOverride?: Environment): Promise<string | null> {
         this._ninjaPath = undefined;
 
         let raw = overWriteCMakePathSetting;
         if (!raw) {
-            raw = await this.expandStringPath(wsc.config.rawCMakePath, wsc);
+            raw = await this.expandStringPath(wsc.config.rawCMakePath, wsc, envOverride);
         }
 
         if (raw === 'auto' || raw === 'cmake') {
             // We start by searching $PATH for cmake
-            const on_path = await this.which('cmake');
+            const on_path = await this.which('cmake', envOverride);
             if (on_path) {
                 return on_path;
             }
@@ -289,7 +304,7 @@ class Paths {
         return raw;
     }
 
-    async expandStringPath(raw_path: string, wsc: DirectoryContext): Promise<string> {
+    async expandStringPath(raw_path: string, wsc: DirectoryContext, envOverride?: Environment): Promise<string> {
         return expandString(raw_path, {
             vars: {
                 buildKit: '${buildKit}',
@@ -310,7 +325,8 @@ class Paths {
                 workspaceHash: util.makeHashString(wsc.folder.uri.fsPath),
                 workspaceRoot: wsc.folder.uri.fsPath,
                 workspaceRootFolderName: path.basename(wsc.folder.uri.fsPath)
-            }
+            },
+            envOverride
         });
     }
 

src/workspace.ts

@@ -5,6 +5,7 @@
 import * as vscode from 'vscode';
 
 import { ConfigurationReader } from '@cmt/config';
+import { Environment } from '@cmt/environmentVariables';
 import paths from '@cmt/paths';
 import { StateManager } from '@cmt/state';
 
@@ -43,8 +44,8 @@ export class DirectoryContext {
      * be used over `ConfigurationReader.cmakePath` because it will do additional
      * path expansion and searching.
      */
-    getCMakePath(overWriteCMakePathSetting?: string): Promise<string | null> {
-        return paths.getCMakePath(this, overWriteCMakePathSetting);
+    getCMakePath(overWriteCMakePathSetting?: string, envOverride?: Environment): Promise<string | null> {
+        return paths.getCMakePath(this, overWriteCMakePathSetting, envOverride);
     }
     /**
      * The CTest executable for the directory. See `cmakePath` for more