Support build-before-run for non-active executable targets via targetName arg (#4757)

* feat: support build-before-run for non-active executable targets (#4656)

When a targetName is provided via ${input:...} args, resolve the named
target directly without calling setLaunchTargetByName(), preventing the
active launch target from changing as a side effect.

Add build deduplication cache (10s TTL) to prepareLaunchTargetExecutable
to avoid duplicate builds when multiple input variables resolve the same
target within a single launch.json evaluation.

Co-authored-by: hanniavalera <[email protected]>

* docs and tests: document ${input:...} pattern and add named target tests

- docs/debug-launch.md: add "Debugging a specific target" section with
  full ${input:...} examples for multi-executable projects
- docs/cmake-settings.md: document targetName argument for command
  substitution commands
- CHANGELOG.md: add feature entry for #4656
- test: add tests for named target resolution, active target
  preservation, buildBeforeRun honor/skip, and invalid target handling

Co-authored-by: hanniavalera <[email protected]>

* fix: check file existence before using build dedup cache

The _prepareCache would return cached results even when the built
binary was deleted, preventing buildBeforeRun from triggering a
rebuild. Add fs.exists() check so the cache is invalidated when the
artifact no longer exists on disk.

Co-authored-by: hanniavalera <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: hanniavalera <[email protected]>

Author: Copilot

CHANGELOG.md

@@ -10,6 +10,7 @@ Features:
 - Add "Set Build and Launch/Debug Target" command that sets both the build target and launch target simultaneously. [#4732](https://github.com/microsoft/vscode-cmake-tools/pull/4732)
 - Add `cmake.setBuildTargetSameAsLaunchTarget` setting to automatically set the build target when the launch/debug target is changed. [#4519](https://github.com/microsoft/vscode-cmake-tools/pull/4519) [@nikita-karatun](https://github.com/nikita-karatun)
 - Add `cmake.additionalBuildProblemMatchers` setting to define custom problem matchers for build output. Supports tools like clang-tidy, PCLint Plus, cppcheck, or custom scripts integrated via `add_custom_command`/`add_custom_target`. [#4077](https://github.com/microsoft/vscode-cmake-tools/issues/4077)
+- Support `targetName` argument for launch-target command substitutions (`cmake.launchTargetPath`, etc.) via `${input:...}` variables, enabling build-before-run for non-active executable targets without changing the active launch target. [#4656](https://github.com/microsoft/vscode-cmake-tools/issues/4656)
 
 Improvements:
 - Make "CMake: Add ... Preset" commands available in the command palette when `cmake.useCMakePresets` is set to `auto`, even before a CMakePresets.json file exists. [#4401](https://github.com/microsoft/vscode-cmake-tools/issues/4401)

docs/cmake-settings.md

@@ -219,6 +219,27 @@ Each matcher entry has the following properties:
 ]
 ```
 
+#### Resolving a specific target with `${input:...}`
+
+All launch-target commands (`cmake.launchTargetPath`, `cmake.getLaunchTargetPath`, and their directory/filename/name variants) accept an optional `targetName` argument. When `targetName` is provided, the command resolves that specific executable target **without changing the active launch target**. This is useful for projects with multiple executables, allowing stable per-target `launch.json` configurations.
+
+Use VS Code [input variables](https://code.visualstudio.com/docs/editor/variables-reference#_input-variables) to pass arguments:
+
+```jsonc
+{
+    "inputs": [
+        {
+            "id": "serverPath",
+            "type": "command",
+            "command": "cmake.launchTargetPath",
+            "args": { "targetName": "my_server" }
+        }
+    ]
+}
+```
+
+Then reference it in a launch configuration as `"program": "${input:serverPath}"`. See [Debugging a specific target](debug-launch.md#debugging-a-specific-target-multi-executable-projects) for full examples.
+
 ## Next steps
 
 - Learn about [user vs. workspace settings](https://code.visualstudio.com/docs/getstarted/settings)

docs/debug-launch.md

@@ -186,6 +186,57 @@ Here are minimal examples of a `launch.json` file that uses `cmake.launchTargetP
 
 The value of the `program` attribute is expanded by CMake Tools to be the absolute path of the program to run.
 
+### Debugging a specific target (multi-executable projects)
+
+If your project defines multiple executables (for example, a `client` and a `server`), you can create stable per-target debug configurations using VS Code's [input variables](https://code.visualstudio.com/docs/editor/variables-reference#_input-variables). Pass the `targetName` argument to any launch-target command so that it resolves a specific executable **without changing the active launch target**. If `cmake.buildBeforeRun` is enabled, the named target is built automatically.
+
+```jsonc
+{
+    "version": "0.2.0",
+    "inputs": [
+        {
+            "id": "serverPath",
+            "type": "command",
+            "command": "cmake.launchTargetPath",
+            "args": { "targetName": "my_server" }
+        },
+        {
+            "id": "serverDir",
+            "type": "command",
+            "command": "cmake.getLaunchTargetDirectory",
+            "args": { "targetName": "my_server" }
+        },
+        {
+            "id": "clientPath",
+            "type": "command",
+            "command": "cmake.launchTargetPath",
+            "args": { "targetName": "my_client" }
+        }
+    ],
+    "configurations": [
+        {
+            "name": "Debug Server",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${input:serverPath}",
+            "cwd": "${input:serverDir}"
+        },
+        {
+            "name": "Debug Client",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${input:clientPath}",
+            "cwd": "${workspaceFolder}"
+        }
+    ]
+}
+```
+
+When multiple `${input:...}` variables reference the same target (for example, `serverPath` and `serverDir` above), the build is triggered only once — results are cached for 10 seconds to avoid redundant builds.
+
+> **Tip:**
+> For large projects, consider setting `cmake.buildBeforeRun` to `false` and using a `preLaunchTask` instead to keep launch times predictable.
+
 ### Cache variable substitution
 
 You can substitute the value of any variable in the CMake cache by adding a `command`-type input for the `cmake.cacheVariable` command to the `inputs` section of `launch.json` with `args.name` as the name of the cache variable. That input can then be used with input variable substitution of values in the `configuration` section of `launch.json`. The optional `args.default` can provide a default value if the named variable isn't found in the CMake cache.

src/cmakeProject.ts

@@ -758,6 +758,14 @@ export class CMakeProject {
     }
     private readonly _launchTargetName = new Property<string | null>(null);
 
+    /**
+     * Short-lived cache for `prepareLaunchTargetExecutable` results keyed by target name.
+     * Prevents duplicate builds when multiple `${input:...}` variables resolve the same
+     * target within a single launch.json evaluation (typically < 1 s apart).
+     */
+    private readonly _prepareCache = new Map<string, { timestamp: number; result: ExecutableTarget }>();
+    private static readonly PREPARE_CACHE_TTL_MS = 10_000;
+
     /**
      * Whether CTest is enabled
      */
@@ -2715,9 +2723,10 @@ export class CMakeProject {
 
     /**
      * Implementation of `cmake.launchTargetPath`. This also ensures the target exists if `cmake.buildBeforeRun` is set.
+     * @param name Optional target name. When provided, resolves the named target without changing the active launch target.
      */
-    async launchTargetPath(): Promise<string | null> {
-        const executable = await this.prepareLaunchTargetExecutable();
+    async launchTargetPath(name?: string): Promise<string | null> {
+        const executable = await this.prepareLaunchTargetExecutable(name);
         if (!executable) {
             log.showChannel();
             log.warning('=======================================================');
@@ -2732,9 +2741,10 @@ export class CMakeProject {
 
     /**
      * Implementation of `cmake.launchTargetDirectory`. This also ensures the target exists if `cmake.buildBeforeRun` is set.
+     * @param name Optional target name. When provided, resolves the named target without changing the active launch target.
      */
-    async launchTargetDirectory(): Promise<string | null> {
-        const targetPath = await this.launchTargetPath();
+    async launchTargetDirectory(name?: string): Promise<string | null> {
+        const targetPath = await this.launchTargetPath(name);
         if (targetPath === null) {
             return null;
         }
@@ -2743,9 +2753,10 @@ export class CMakeProject {
 
     /**
      * Implementation of `cmake.launchTargetFilename`. This also ensures the target exists if `cmake.buildBeforeRun` is set.
+     * @param name Optional target name. When provided, resolves the named target without changing the active launch target.
      */
-    async launchTargetFilename(): Promise<string | null> {
-        const targetPath = await this.launchTargetPath();
+    async launchTargetFilename(name?: string): Promise<string | null> {
+        const targetPath = await this.launchTargetPath(name);
         if (targetPath === null) {
             return null;
         }
@@ -2754,9 +2765,10 @@ export class CMakeProject {
 
     /**
      * Implementation of `cmake.launchTargetName`. This also ensures the target exists if `cmake.buildBeforeRun` is set.
+     * @param name Optional target name. When provided, resolves the named target without changing the active launch target.
      */
-    async launchTargetNameForSubstitution(): Promise<string | null> {
-        const targetPath = await this.launchTargetPath();
+    async launchTargetNameForSubstitution(name?: string): Promise<string | null> {
+        const targetPath = await this.launchTargetPath(name);
         if (targetPath === null) {
             return null;
         }
@@ -2765,15 +2777,21 @@ export class CMakeProject {
 
     /**
      * Implementation of `cmake.getLaunchTargetPath`. This does not ensure the target exists.
+     * @param name Optional target name. When provided, resolves the named target without changing the active launch target.
      */
-    async getLaunchTargetPath(): Promise<string | null> {
+    async getLaunchTargetPath(name?: string): Promise<string | null> {
         if (await this.needsReconfigure()) {
             const rc = await this.configureInternal(ConfigureTrigger.launch, [], ConfigureType.Normal);
             if (rc.exitCode !== 0) {
                 return null;
             }
         }
-        const target = await this.getOrSelectLaunchTarget();
+        let target: ExecutableTarget | null;
+        if (name) {
+            target = (await this.executableTargets).find(e => e.name === name) || null;
+        } else {
+            target = await this.getOrSelectLaunchTarget();
+        }
         if (!target) {
             log.showChannel();
             log.warning('=======================================================');
@@ -2789,9 +2807,10 @@ export class CMakeProject {
 
     /**
      * Implementation of `cmake.getLaunchTargetDirectory`. This does not ensure the target exists.
+     * @param name Optional target name. When provided, resolves the named target without changing the active launch target.
      */
-    async getLaunchTargetDirectory(): Promise<string | null> {
-        const targetPath = await this.getLaunchTargetPath();
+    async getLaunchTargetDirectory(name?: string): Promise<string | null> {
+        const targetPath = await this.getLaunchTargetPath(name);
         if (targetPath === null) {
             return null;
         }
@@ -2800,9 +2819,10 @@ export class CMakeProject {
 
     /**
      * Implementation of `cmake.getLaunchTargetFilename`. This does not ensure the target exists.
+     * @param name Optional target name. When provided, resolves the named target without changing the active launch target.
      */
-    async getLaunchTargetFilename(): Promise<string | null> {
-        const targetPath = await this.getLaunchTargetPath();
+    async getLaunchTargetFilename(name?: string): Promise<string | null> {
+        const targetPath = await this.getLaunchTargetPath(name);
         if (targetPath === null) {
             return null;
         }
@@ -2811,9 +2831,10 @@ export class CMakeProject {
 
     /**
      * Implementation of `cmake.getLaunchTargetName`. This does not ensure the target exists.
+     * @param name Optional target name. When provided, resolves the named target without changing the active launch target.
      */
-    async getLaunchTargetName(): Promise<string | null> {
-        const targetPath = await this.getLaunchTargetPath();
+    async getLaunchTargetName(name?: string): Promise<string | null> {
+        const targetPath = await this.getLaunchTargetPath(name);
         if (targetPath === null) {
             return null;
         }
@@ -2894,6 +2915,16 @@ export class CMakeProject {
     }
 
     async prepareLaunchTargetExecutable(name?: string): Promise<ExecutableTarget | null> {
+        // Return cached result for named targets to avoid duplicate builds when
+        // multiple ${input:...} variables resolve the same target in quick succession.
+        if (name) {
+            const cached = this._prepareCache.get(name);
+            if (cached && (Date.now() - cached.timestamp) < CMakeProject.PREPARE_CACHE_TTL_MS
+                && await fs.exists(cached.result.path)) {
+                return cached.result;
+            }
+        }
+
         let chosen: ExecutableTarget;
 
         // Ensure that we've configured the project already. If we haven't, `getOrSelectLaunchTarget` won't see any
@@ -2944,6 +2975,12 @@ export class CMakeProject {
             }
 
         }
+
+        // Cache the result for named targets
+        if (name) {
+            this._prepareCache.set(name, { timestamp: Date.now(), result: chosen });
+        }
+
         return chosen;
     }
 

src/extension.ts

@@ -1753,7 +1753,7 @@ export class ExtensionManager implements vscode.Disposable {
         telemetry.logEvent("substitution", { command: "launchTargetPath" });
         return this.queryCMakeProject(async cmakeProject => {
             if (targetName !== undefined && targetName !== null) {
-                await cmakeProject.setLaunchTargetByName(targetName);
+                return cmakeProject.launchTargetPath(targetName);
             }
             const targetPath = await cmakeProject.launchTargetPath();
             return targetPath;
@@ -1766,7 +1766,7 @@ export class ExtensionManager implements vscode.Disposable {
         telemetry.logEvent("substitution", { command: "launchTargetDirectory" });
         return this.queryCMakeProject(async cmakeProject => {
             if (targetName !== undefined && targetName !== null) {
-                await cmakeProject.setLaunchTargetByName(targetName);
+                return cmakeProject.launchTargetDirectory(targetName);
             }
             const targetDirectory = await cmakeProject.launchTargetDirectory();
             return targetDirectory;
@@ -1779,7 +1779,7 @@ export class ExtensionManager implements vscode.Disposable {
         telemetry.logEvent("substitution", { command: "launchTargetFilename" });
         return this.queryCMakeProject(async cmakeProject => {
             if (targetName !== undefined && targetName !== null) {
-                await cmakeProject.setLaunchTargetByName(targetName);
+                return cmakeProject.launchTargetFilename(targetName);
             }
             const targetFilename = await cmakeProject.launchTargetFilename();
             return targetFilename;
@@ -1792,7 +1792,7 @@ export class ExtensionManager implements vscode.Disposable {
         telemetry.logEvent("substitution", { command: "launchTargetName" });
         return this.queryCMakeProject(async cmakeProject => {
             if (targetName !== undefined && targetName !== null) {
-                await cmakeProject.setLaunchTargetByName(targetName);
+                return cmakeProject.launchTargetNameForSubstitution(targetName);
             }
             const targetFilename = await cmakeProject.launchTargetNameForSubstitution();
             return targetFilename;
@@ -1805,7 +1805,7 @@ export class ExtensionManager implements vscode.Disposable {
         telemetry.logEvent("substitution", { command: "getLaunchTargetPath" });
         return this.queryCMakeProject(async cmakeProject => {
             if (targetName !== undefined && targetName !== null) {
-                await cmakeProject.setLaunchTargetByName(targetName);
+                return cmakeProject.getLaunchTargetPath(targetName);
             }
             const targetPath = await cmakeProject.getLaunchTargetPath();
             return targetPath;
@@ -1818,7 +1818,7 @@ export class ExtensionManager implements vscode.Disposable {
         telemetry.logEvent("substitution", { command: "getLaunchTargetDirectory" });
         return this.queryCMakeProject(async cmakeProject => {
             if (targetName !== undefined && targetName !== null) {
-                await cmakeProject.setLaunchTargetByName(targetName);
+                return cmakeProject.getLaunchTargetDirectory(targetName);
             }
             const targetDirectory = await cmakeProject.getLaunchTargetDirectory();
             return targetDirectory;
@@ -1831,7 +1831,7 @@ export class ExtensionManager implements vscode.Disposable {
         telemetry.logEvent("substitution", { command: "getLaunchTargetFilename" });
         return this.queryCMakeProject(async cmakeProject => {
             if (targetName !== undefined && targetName !== null) {
-                await cmakeProject.setLaunchTargetByName(targetName);
+                return cmakeProject.getLaunchTargetFilename(targetName);
             }
             const targetFilename = await cmakeProject.getLaunchTargetFilename();
             return targetFilename;
@@ -1844,7 +1844,7 @@ export class ExtensionManager implements vscode.Disposable {
         telemetry.logEvent("substitution", { command: "getLaunchTargetName" });
         return this.queryCMakeProject(async cmakeProject => {
             if (targetName !== undefined && targetName !== null) {
-                await cmakeProject.setLaunchTargetByName(targetName);
+                return cmakeProject.getLaunchTargetName(targetName);
             }
             const targetFilename = await cmakeProject.getLaunchTargetName();
             return targetFilename;