CoreCommands,PackageModel: introduce -debug-format option

This adds a new flag `-debug-format` that allows some structured control
over the debug information format.  This is particularly important for
Windows where there are two different debugging information formats:
  - Code View (PDB)
  - DWARF

While theoretically LLDB supports PDBs, the overall support for that is
limited.  Furthermore, the CodeView emitted by the swift frontend is
limiting for debugging as expression evaluation as not possible due to
the debug information encoding employed by Swift: skeletal information
is emitted into the binary and the type information is queried
dynamically by the AST deserialiser in the compiler.

DWARF on the other hand does not support PE/COFF particularly well (e.g.
exceeding the section name limits, representations potentially not being
serialisable into the object file, etc), but allows a better experience
with LLDB.  More importantly, it breaks debugging with the system
libraries (e.g. kernel32 or NTDLL). As a result, while it is often used
with Swift code, PDBs can also be beneficial.  Furthermore, DWARF forces
the use of lld as the linker as link does not properly emit linked DWARF
information.

Provide a top-level control to emit the debug information in a
particular format as both of these options require altering the C/C++,
Swift, and linker flags.  We default to DWARF on all platforms, but on
Windows, if CodeView is selected, we will alter the flags appropriately
to ease switching of debug information format.

Author: compnerd

Sources/CoreCommands/Options.swift

@@ -447,6 +447,10 @@ public struct BuildOptions: ParsableArguments {
     @Option(name: .customLong("build-system"))
     var _buildSystem: BuildSystemProvider.Kind = .native
 
+    /// The Debug Information Format to use.
+    @Option(name: .customLong("debug-info-format", withSingleDash: true))
+    public var debugInfoFormat: DebugInfoFormat = .dwarf
+
     public var buildSystem: BuildSystemProvider.Kind {
         #if os(macOS)
         // Force the Xcode build system if we want to build more than one arch.
@@ -499,6 +503,11 @@ public struct BuildOptions: ParsableArguments {
         /// See `BuildParameters.LinkTimeOptimizationMode.thin` for details.
         case thin
     }
+
+    public enum DebugInfoFormat: String, Codable, ExpressibleByArgument {
+        case dwarf
+        case codeview
+    }
 }
 
 public struct LinkerOptions: ParsableArguments {

Sources/CoreCommands/SwiftTool.swift

@@ -678,12 +678,33 @@ public final class SwiftTool {
                 component: destinationTriple.platformBuildPathComponent(buildSystem: options.build.buildSystem)
             )
 
+            var flags: BuildFlags = options.build.buildFlags
+            if destinationTriple.isWindows() {
+                switch options.build.debugInfoFormat {
+                case .dwarf:
+                    // DWARF requires lld as link.exe expects CodeView debug info.
+                    flags = flags.merging(BuildFlags(
+                        cCompilerFlags: ["-gdwarf"],
+                        cxxCompilerFlags: ["-gdwarf"],
+                        swiftCompilerFlags: ["-g", "-use-ld=lld"],
+                        linkerFlags: ["-debug:dwarf"]
+                    ))
+                case .codeview:
+                    flags = flags.merging(BuildFlags(
+                        swiftCompilerFlags: ["-g", "-debug-info-format=codeview"],
+                        linkerFlags: ["-debug"]
+                    ))
+                }
+            } else if options.build.debugInfoFormat == .codeview {
+                observabilityScope.emit(error: "CodeView debug information is currently not supported for this platform")
+            }
+
             return try BuildParameters(
                 dataPath: dataPath,
                 configuration: options.build.configuration,
                 toolchain: destinationToolchain,
                 destinationTriple: destinationTriple,
-                flags: options.build.buildFlags,
+                flags: flags,
                 pkgConfigDirectories: options.locations.pkgConfigDirectories,
                 architectures: options.build.architectures,
                 workers: options.build.jobs ?? UInt32(ProcessInfo.processInfo.activeProcessorCount),

Sources/PackageModel/BuildFlags.swift

@@ -40,4 +40,15 @@ public struct BuildFlags: Equatable, Encodable {
         self.linkerFlags = linkerFlags
         self.xcbuildFlags = xcbuildFlags
     }
+
+    public mutating func merging(_ flags: BuildFlags) -> Self {
+        self.cCompilerFlags.insert(contentsOf: flags.cCompilerFlags, at: 0)
+        self.cxxCompilerFlags.insert(contentsOf: flags.cxxCompilerFlags, at: 0)
+        self.swiftCompilerFlags.insert(contentsOf: flags.swiftCompilerFlags, at: 0)
+        self.linkerFlags.insert(contentsOf: flags.linkerFlags, at: 0)
+        if self.xcbuildFlags != nil || flags.xcbuildFlags != nil {
+            self.xcbuildFlags = (self.xcbuildFlags ?? []) + (flags.xcbuildFlags ?? [])
+        }
+        return self
+    }
 }

Tests/CommandsTests/SwiftToolTests.swift

@@ -11,12 +11,15 @@
 //===----------------------------------------------------------------------===//
 
 @testable import Basics
+@testable import Build
 @testable import CoreCommands
 @testable import Commands
+@testable import PackageModel
 import SPMTestSupport
 import XCTest
 
 import class TSCBasic.BufferedOutputByteStream
+import class TSCBasic.InMemoryFileSystem
 import protocol TSCBasic.OutputByteStream
 import var TSCBasic.stderrStream
 
@@ -232,6 +235,66 @@ final class SwiftToolTests: CommandsTestCase {
             // Tests should not modify user's home dir .netrc so leaving that out intentionally
         }
     }
+
+    func testDebugFormatFlags() throws {
+        let fs = InMemoryFileSystem(emptyFiles: [
+            "/Pkg/Sources/exe/main.swift",
+        ])
+
+        let explicitDwarfOptions = try GlobalOptions.parse(["--triple", "x86_64-unknown-windows-msvc", "-debug-info-format", "dwarf"])
+        let explicitDwarf = try SwiftTool.createSwiftToolForTest(options: explicitDwarfOptions)
+
+        let observer = ObservabilitySystem.makeForTesting()
+        let graph = try loadPackageGraph(fileSystem: fs, manifests: [
+                Manifest.createRootManifest(displayName: "Pkg",
+                                            path: "/Pkg",
+                                            targets: [TargetDescription(name: "exe")])
+        ], observabilityScope: observer.topScope)
+
+        var plan: BuildPlan
+
+        plan = try BuildPlan(
+            buildParameters: explicitDwarf.buildParameters(),
+            graph: graph,
+            fileSystem: fs,
+            observabilityScope: observer.topScope
+        )
+        try XCTAssertMatch(plan.buildProducts.compactMap { $0 as? Build.ProductBuildDescription }.first?.linkArguments() ?? [],
+                           [.anySequence, "-g", "-use-ld=lld", "-Xlinker", "-debug:dwarf"])
+
+        let explicitCodeViewOptions = try GlobalOptions.parse(["--triple", "x86_64-unknown-windows-msvc", "-debug-info-format", "codeview"])
+        let explicitCodeView = try SwiftTool.createSwiftToolForTest(options: explicitCodeViewOptions)
+
+        plan = try BuildPlan(
+            buildParameters: explicitCodeView.buildParameters(),
+            graph: graph,
+            fileSystem: fs,
+            observabilityScope: observer.topScope
+        )
+        try XCTAssertMatch(plan.buildProducts.compactMap { $0 as?  Build.ProductBuildDescription }.first?.linkArguments() ?? [],
+                           [.anySequence, "-g", "-debug-info-format=codeview", "-Xlinker", "-debug"])
+
+        let implicitDwarfOptions = try GlobalOptions.parse(["--triple", "x86_64-unknown-windows-msvc"])
+        let implicitDwarf = try SwiftTool.createSwiftToolForTest(options: implicitDwarfOptions)
+        plan = try BuildPlan(
+            buildParameters: implicitDwarf.buildParameters(),
+            graph: graph,
+            fileSystem: fs,
+            observabilityScope: observer.topScope
+        )
+        try XCTAssertMatch(plan.buildProducts.compactMap { $0 as? Build.ProductBuildDescription }.first?.linkArguments() ?? [],
+                           [.anySequence, "-g", "-use-ld=lld", "-Xlinker", "-debug:dwarf"])
+
+        // Explicitly pass Linux as when the SwiftTool tests are enabled on
+        // Windows, this would fail otherwise as CodeView is supported on the
+        // native host.
+        let unsupportedCodeViewOptions = try GlobalOptions.parse(["--triple", "x86_64-unknown-linux-gnu", "-debug-info-format", "codeview"])
+        let stream = BufferedOutputByteStream()
+        let unsupportedCodeView = try SwiftTool.createSwiftToolForTest(outputStream: stream, options: unsupportedCodeViewOptions)
+
+        XCTAssertNotNil(try? unsupportedCodeView.buildParameters())
+        XCTAssertMatch(stream.bytes.validDescription, .contains("error: CodeView debug information is currently not supported for this platform"))
+    }
 }
 
 extension SwiftTool {