[6.1] Apply toolset's debugger property in swift run (#8257)

Cherry-pick of #8252, merged as
88e2af7.

**Explanation**: Per [SE-0378 toolsets can specify an optional `debugger` property](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md#toolsetjson-files), which so far had no effect. We should respect this property in `swift run` invocations when any toolsets or Swift SDKs are selected.

This allows running and debugging cross-compiled products in an environment other than the host, e.g. a container runtime when cross-compiled to Linux, QEMU or a firmware flasher and serial port setup script with Swift Embedded for microcontrollers, or in a Wasm runtime for a Wasm binary.
**Scope**: Only impacts `swift-run` when a toolset or a Swift SDK are selected.
**Risk**: Low, due to limited scope and automated testing.
**Testing**: Added a new test cause to the existing XCTest suite.
**Issue**: rdar://143814083
**Reviewer**: @dschaefer2

Author: MaxDesiatov

Fixtures/Miscellaneous/EchoExecutable/echo.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+echo "$@"

Fixtures/Miscellaneous/EchoExecutable/toolset.json

@@ -0,0 +1,5 @@
+{
+  "debugger": { "path": "echo.sh" },
+  "schemaVersion" : "1.0",
+  "rootPath" : "."
+}

Sources/Commands/SwiftRunCommand.swift

@@ -169,17 +169,28 @@ public struct SwiftRunCommand: AsyncSwiftCommand {
                     try await buildSystem.build(subset: .product(productName))
                 }
 
-                let executablePath = try swiftCommandState.productsBuildParameters.buildPath.appending(component: productName)
+                let productRelativePath = try swiftCommandState.productsBuildParameters.executablePath(for: productName)
+                let productAbsolutePath = try swiftCommandState.productsBuildParameters.buildPath.appending(productRelativePath)
 
                 // Make sure we are running from the original working directory.
                 let cwd: AbsolutePath? = swiftCommandState.fileSystem.currentWorkingDirectory
                 if cwd == nil || swiftCommandState.originalWorkingDirectory != cwd {
                     try ProcessEnv.chdir(swiftCommandState.originalWorkingDirectory)
                 }
 
-                let pathRelativeToWorkingDirectory = executablePath.relative(to: swiftCommandState.originalWorkingDirectory)
-                let lldbPath = try swiftCommandState.getTargetToolchain().getLLDB()
-                try exec(path: lldbPath.pathString, args: ["--", pathRelativeToWorkingDirectory.pathString] + options.arguments)
+                if let debugger = try swiftCommandState.getTargetToolchain().swiftSDK.toolset.knownTools[.debugger],
+                   let debuggerPath = debugger.path {
+                    try self.run(
+                        fileSystem: swiftCommandState.fileSystem,
+                        executablePath: debuggerPath,
+                        originalWorkingDirectory: swiftCommandState.originalWorkingDirectory,
+                        arguments: debugger.extraCLIOptions + [productAbsolutePath.pathString] + options.arguments
+                    )
+                } else {
+                    let pathRelativeToWorkingDirectory = productAbsolutePath.relative(to: swiftCommandState.originalWorkingDirectory)
+                    let lldbPath = try swiftCommandState.getTargetToolchain().getLLDB()
+                    try exec(path: lldbPath.pathString, args: ["--", pathRelativeToWorkingDirectory.pathString] + options.arguments)
+                }
             } catch let error as RunError {
                 swiftCommandState.observabilityScope.emit(error)
                 throw ExitCode.failure
@@ -215,11 +226,27 @@ public struct SwiftRunCommand: AsyncSwiftCommand {
                 }
 
                 let executablePath = try swiftCommandState.productsBuildParameters.buildPath.appending(component: productName)
+
+                let productRelativePath = try swiftCommandState.productsBuildParameters.executablePath(for: productName)
+                let productAbsolutePath = try swiftCommandState.productsBuildParameters.buildPath.appending(productRelativePath)
+
+                let runnerPath: AbsolutePath
+                let arguments: [String]
+
+                if let debugger = try swiftCommandState.getTargetToolchain().swiftSDK.toolset.knownTools[.debugger],
+                   let debuggerPath = debugger.path {
+                    runnerPath = debuggerPath
+                    arguments = debugger.extraCLIOptions + [productAbsolutePath.pathString] + options.arguments
+                } else {
+                    runnerPath = executablePath
+                    arguments = options.arguments
+                }
+
                 try self.run(
                     fileSystem: swiftCommandState.fileSystem,
-                    executablePath: executablePath,
+                    executablePath: runnerPath,
                     originalWorkingDirectory: swiftCommandState.originalWorkingDirectory,
-                    arguments: options.arguments
+                    arguments: arguments
                 )
             } catch Diagnostics.fatalError {
                 throw ExitCode.failure
@@ -267,8 +294,8 @@ public struct SwiftRunCommand: AsyncSwiftCommand {
         fileSystem: FileSystem,
         executablePath: AbsolutePath,
         originalWorkingDirectory: AbsolutePath,
-        arguments: [String]) throws
-    {
+        arguments: [String]
+    ) throws {
         // Make sure we are running from the original working directory.
         let cwd: AbsolutePath? = fileSystem.currentWorkingDirectory
         if cwd == nil || originalWorkingDirectory != cwd {

Sources/SPMBuildCore/BuildParameters/BuildParameters.swift

@@ -286,7 +286,7 @@ public struct BuildParameters: Encodable {
     }
 
     /// Returns the path to the executable of a product for the current build parameters.
-    private func executablePath(for name: String) throws -> RelativePath {
+    package func executablePath(for name: String) throws -> RelativePath {
         try RelativePath(validating: "\(name)\(self.suffix)\(self.triple.executableExtension)")
     }
 

Tests/CommandsTests/RunCommandTests.swift

@@ -40,6 +40,25 @@ final class RunCommandTests: CommandsTestCase {
         XCTAssert(stdout.contains("Swift Package Manager"), "got stdout:\n" + stdout)
     }
 
+// echo.sh script from the toolset won't work on Windows
+#if !os(Windows)
+    func testToolsetDebugger() async throws {
+        try await fixture(name: "Miscellaneous/EchoExecutable") { fixturePath in
+            let (stdout, stderr) = try await SwiftPM.Run.execute(
+                ["--toolset", "\(fixturePath)/toolset.json"], packagePath: fixturePath)
+
+            // We only expect tool's output on the stdout stream.
+            XCTAssertMatch(stdout, .contains("""
+                \(fixturePath)/.build
+                """))
+
+            // swift-build-tool output should go to stderr.
+            XCTAssertMatch(stderr, .regex("Compiling"))
+            XCTAssertMatch(stderr, .contains("Linking"))
+        }
+    }
+#endif
+
     func testUnknownProductAndArgumentPassing() async throws {
         try await fixture(name: "Miscellaneous/EchoExecutable") { fixturePath in
             let (stdout, stderr) = try await SwiftPM.Run.execute(