Pass symbol graph options to swift build to customize the output (#9124)

cmcgee1024 · web-flow · commit ec2a626d905c · 2025-09-11T20:31:00.000-04:00
diff --git a/.swift-version b/.swift-version
@@ -1 +1 @@
-6.1.0
+6.1.2
diff --git a/Sources/Commands/PackageCommands/DumpCommands.swift b/Sources/Commands/PackageCommands/DumpCommands.swift
@@ -56,8 +56,16 @@ struct DumpSymbolGraph: AsyncSwiftCommand {
             enableAllTraits: true,
             cacheBuildManifest: false
         )
-        // TODO pass along the various flags as associated values to the symbol graph build output (e.g. includeSPISymbols)
-        let buildResult = try await buildSystem.build(subset: .allExcludingTests, buildOutputs: [.symbolGraph, .buildPlan])
+        let buildResult = try await buildSystem.build(subset: .allExcludingTests, buildOutputs: [.symbolGraph(
+            BuildOutput.SymbolGraphOptions(
+                prettyPrint: prettyPrint,
+                minimumAccessLevel: .accessLevel(minimumAccessLevel),
+                includeSynthesized: !skipSynthesizedMembers,
+                includeSPI: includeSPISymbols,
+                emitExtensionBlocks: extensionBlockSymbolBehavior != .omitExtensionBlockSymbols,
+                // TODO skip inherited docs
+            )
+        ), .buildPlan])
 
         let symbolGraphDirectory = try swiftCommandState.productsBuildParameters.dataPath.appending("symbolgraph")
 
@@ -189,3 +197,9 @@ struct DumpPIF: AsyncSwiftCommand {
         return .init(wantsMultipleTestProducts: true)
     }
 }
+
+fileprivate extension BuildOutput.SymbolGraphAccessLevel {
+    fileprivate static func accessLevel(_ accessLevel: SymbolGraphExtract.AccessLevel) -> BuildOutput.SymbolGraphAccessLevel {
+        return BuildOutput.SymbolGraphAccessLevel.init(rawValue: accessLevel.rawValue)!
+    }
+}
diff --git a/Sources/Commands/Utilities/PluginDelegate.swift b/Sources/Commands/Utilities/PluginDelegate.swift
@@ -413,8 +413,7 @@ final class PluginDelegate: PluginInvocationDelegate {
         )
 
         // Build the target, if needed. We are interested in symbol graph (ideally) or a build plan.
-        // TODO pass along the options as associated values to the symbol graph build output (e.g. includeSPI)
-        let buildResult = try await buildSystem.build(subset: .target(targetName), buildOutputs: [.symbolGraph, .buildPlan])
+        let buildResult = try await buildSystem.build(subset: .target(targetName), buildOutputs: [.symbolGraph(options), .buildPlan])
 
         if let symbolGraph = buildResult.symbolGraph {
             let path = (try swiftCommandState.productsBuildParameters.buildPath)
@@ -505,3 +504,33 @@ extension BuildSystem {
         }
     }
 }
+
+extension BuildOutput {
+    static func symbolGraph(_ options: PluginInvocationSymbolGraphOptions) -> BuildOutput {
+        return .symbolGraph(SymbolGraphOptions(
+                minimumAccessLevel: .accessLevel(options.minimumAccessLevel),
+                includeSynthesized: options.includeSynthesized,
+                includeSPI: options.includeSPI,
+                emitExtensionBlocks: options.emitExtensionBlocks
+        ))
+    }
+}
+
+fileprivate extension BuildOutput.SymbolGraphAccessLevel {
+    fileprivate static func accessLevel(_ accessLevel: PluginInvocationSymbolGraphOptions.AccessLevel) -> BuildOutput.SymbolGraphAccessLevel {
+        return switch accessLevel {
+        case .private:
+            .private
+        case .fileprivate:
+            .fileprivate
+        case .internal:
+            .internal
+        case .package:
+            .package
+        case .public:
+            .public
+        case .open:
+            .open
+        }
+    }
+}
diff --git a/Sources/SPMBuildCore/BuildSystem/BuildSystem.swift b/Sources/SPMBuildCore/BuildSystem/BuildSystem.swift
@@ -38,14 +38,59 @@ public enum BuildSubset {
 /// can produce certain extra outputs in the process of building. Not all
 /// build systems can produce all possible build outputs. Check the build
 /// result for indication that the output was produced.
-public enum BuildOutput {
-    case symbolGraph
-    // TODO associated values for the following symbol graph options:
-    // "-skip-inherited-docs"
-    // "-symbol-graph-minimum-access-level", “<LEVEL>”
-    // "-include-spi-symbols"
-    // "-emit-extension-block-symbols"
-    // "-emit-synthesized-members"
+public enum BuildOutput: Equatable {
+    public static func == (lhs: BuildOutput, rhs: BuildOutput) -> Bool {
+        switch lhs {    
+        case .symbolGraph(let leftOptions):
+            switch rhs {
+                case .symbolGraph(let rightOptions):
+                    return leftOptions == rightOptions
+                default:
+                    return false
+            }
+        case .buildPlan:
+            switch rhs {
+                case .buildPlan:
+                    return true
+                default:
+                    return false
+            }
+        case .replArguments:
+            switch rhs {
+                case .replArguments:
+                    return true
+                default:
+                    return false
+            }
+        }
+    }
+
+    public enum SymbolGraphAccessLevel: String {
+        case `private`, `fileprivate`, `internal`, `package`, `public`, `open`
+    }
+    public struct SymbolGraphOptions: Equatable {
+        public var prettyPrint: Bool
+        public var minimumAccessLevel: SymbolGraphAccessLevel
+        public var includeSynthesized: Bool
+        public var includeSPI: Bool
+        public var emitExtensionBlocks: Bool
+
+        public init(
+            prettyPrint: Bool = false,
+            minimumAccessLevel: SymbolGraphAccessLevel,
+            includeSynthesized: Bool,
+            includeSPI: Bool,
+            emitExtensionBlocks: Bool
+        ) {
+            self.prettyPrint = prettyPrint
+            self.minimumAccessLevel = minimumAccessLevel
+            self.includeSynthesized = includeSynthesized
+            self.includeSPI = includeSPI
+            self.emitExtensionBlocks = emitExtensionBlocks
+        }
+    }
+
+    case symbolGraph(SymbolGraphOptions)
     case buildPlan
     case replArguments
 }
diff --git a/Sources/SwiftBuildSupport/SwiftBuildSystem.swift b/Sources/SwiftBuildSupport/SwiftBuildSystem.swift
@@ -351,16 +351,26 @@ public final class SwiftBuildSystem: SPMBuildCore.BuildSystem {
 
         try await writePIF(buildParameters: buildParameters)
 
+        var symbolGraphOptions: BuildOutput.SymbolGraphOptions?
+        for output in buildOutputs {
+            switch output {
+            case .symbolGraph(let options):
+                symbolGraphOptions = options
+            default:
+                continue
+            }
+        }
+
         return try await startSWBuildOperation(
             pifTargetName: subset.pifTargetName,
-            genSymbolGraph: buildOutputs.contains(.symbolGraph),
+            symbolGraphOptions: symbolGraphOptions,
             generateReplArguments: buildOutputs.contains(.replArguments),
         )
     }
 
     private func startSWBuildOperation(
         pifTargetName: String,
-        genSymbolGraph: Bool,
+        symbolGraphOptions: BuildOutput.SymbolGraphOptions?,
         generateReplArguments: Bool
     ) async throws -> BuildResult {
         let buildStartTime = ContinuousClock.Instant.now
@@ -413,7 +423,7 @@ public final class SwiftBuildSystem: SPMBuildCore.BuildSystem {
                         throw error
                     }
 
-                    let request = try await self.makeBuildRequest(session: session, configuredTargets: configuredTargets, derivedDataPath: derivedDataPath, genSymbolGraph: genSymbolGraph)
+                    let request = try await self.makeBuildRequest(session: session, configuredTargets: configuredTargets, derivedDataPath: derivedDataPath, symbolGraphOptions: symbolGraphOptions)
 
                     struct BuildState {
                         private var targetsByID: [Int: SwiftBuild.SwiftBuildMessage.TargetStartedInfo] = [:]
@@ -631,7 +641,7 @@ public final class SwiftBuildSystem: SPMBuildCore.BuildSystem {
         )
     }
 
-    private func makeBuildParameters(session: SWBBuildServiceSession, genSymbolGraph: Bool) async throws -> SwiftBuild.SWBBuildParameters {
+    private func makeBuildParameters(session: SWBBuildServiceSession, symbolGraphOptions: BuildOutput.SymbolGraphOptions?) async throws -> SwiftBuild.SWBBuildParameters {
         // Generate the run destination parameters.
         let runDestination = makeRunDestination()
 
@@ -658,9 +668,39 @@ public final class SwiftBuildSystem: SPMBuildCore.BuildSystem {
 
         // FIXME: workaround for old Xcode installations such as what is in CI
         settings["LM_SKIP_METADATA_EXTRACTION"] = "YES"
-        if genSymbolGraph {
+        if let symbolGraphOptions {
             settings["RUN_SYMBOL_GRAPH_EXTRACT"] = "YES"
-            // TODO set additional symbol graph options from the build output here, such as "include-spi-symbols"
+
+            if symbolGraphOptions.prettyPrint {
+                settings["DOCC_PRETTY_PRINT"] = "YES"
+            }
+
+            if symbolGraphOptions.emitExtensionBlocks {
+                settings["DOCC_EXTRACT_EXTENSION_SYMBOLS"] = "YES"
+            }
+
+            if !symbolGraphOptions.includeSynthesized {
+                settings["DOCC_SKIP_SYNTHESIZED_MEMBERS"] = "YES"
+            }
+
+            if symbolGraphOptions.includeSPI {
+                settings["DOCC_EXTRACT_SPI_DOCUMENTATION"] = "YES"
+            }
+
+            switch symbolGraphOptions.minimumAccessLevel {
+            case .private:
+                settings["DOCC_MINIMUM_ACCESS_LEVEL"] = "private"
+            case .fileprivate:
+                settings["DOCC_MINIMUM_ACCESS_LEVEL"] = "fileprivate"
+            case .internal:
+                settings["DOCC_MINIMUM_ACCESS_LEVEL"] = "internal"
+            case .package:
+                settings["DOCC_MINIMUM_ACCESS_LEVEL"] = "package"
+            case .public:
+                settings["DOCC_MINIMUM_ACCESS_LEVEL"] = "public"
+            case .open:
+                settings["DOCC_MINIMUM_ACCESS_LEVEL"] = "open"
+            }
         }
 
         let normalizedTriple = Triple(buildParameters.triple.triple, normalizing: true)
@@ -741,9 +781,9 @@ public final class SwiftBuildSystem: SPMBuildCore.BuildSystem {
         return params
     }
 
-    public func makeBuildRequest(session: SWBBuildServiceSession, configuredTargets: [SWBTargetGUID], derivedDataPath: Basics.AbsolutePath, genSymbolGraph: Bool) async throws -> SWBBuildRequest {
+    public func makeBuildRequest(session: SWBBuildServiceSession, configuredTargets: [SWBTargetGUID], derivedDataPath: Basics.AbsolutePath, symbolGraphOptions: BuildOutput.SymbolGraphOptions?) async throws -> SWBBuildRequest {
         var request = SWBBuildRequest()
-        request.parameters = try await makeBuildParameters(session: session, genSymbolGraph: genSymbolGraph)
+        request.parameters = try await makeBuildParameters(session: session, symbolGraphOptions: symbolGraphOptions)
         request.configuredTargets = configuredTargets.map { SWBConfiguredTarget(guid: $0.rawValue, parameters: request.parameters) }
         request.useParallelTargets = true
         request.useImplicitDependencies = false
diff --git a/Tests/CommandsTests/PackageCommandTests.swift b/Tests/CommandsTests/PackageCommandTests.swift
@@ -5971,7 +5971,7 @@ struct PackageCommandTests {
         func commandPluginSymbolGraphCallbacks(
             data: BuildData,
         ) async throws {
-            try await withKnownIssue {
+            try await withKnownIssue(isIntermittent: true) {
                 try await testWithTemporaryDirectory { tmpPath in
                     // Create a sample package with a library, and executable, and a plugin.
                     let packageDir = tmpPath.appending(components: "MyPackage")
@@ -6102,7 +6102,8 @@ struct PackageCommandTests {
                     }
                 }
             } when: {
-                ProcessInfo.hostOperatingSystem == .windows && data.buildSystem == .swiftbuild
+                (ProcessInfo.hostOperatingSystem == .windows && data.buildSystem == .swiftbuild)
+                || !CiEnvironment.runningInSmokeTestPipeline
             }
         }
 
diff --git a/Tests/FunctionalTests/TraitTests.swift b/Tests/FunctionalTests/TraitTests.swift
@@ -595,25 +595,29 @@ struct TraitTests {
         buildSystem: BuildSystemProvider.Kind,
         configuration: BuildConfiguration,
         ) async throws {
-        try await fixture(name: "Traits") { fixturePath in
-            // The swiftbuild build system doesn't yet have the ability for command plugins to request symbol graphs
-             try await withKnownIssue(
-                "https://github.com/swiftlang/swift-build/issues/609",
-                isIntermittent: true,
-            ) {
-                let (stdout, _) = try await executeSwiftPackage(
-                    fixturePath.appending("Package10"),
-                    configuration: configuration,
-                    extraArgs: ["plugin", "extract"],
-                    buildSystem: buildSystem,
-                )
-                let path = String(stdout.split(whereSeparator: \.isNewline).first!)
-                let symbolGraph = try String(contentsOfFile: "\(path)/Package10Library1.symbols.json", encoding: .utf8)
-                #expect(symbolGraph.contains("TypeGatedByPackage10Trait1"))
-                #expect(symbolGraph.contains("TypeGatedByPackage10Trait2"))
-            } when: {
-               buildSystem == .swiftbuild && ProcessInfo.hostOperatingSystem == .windows
+        try await withKnownIssue(isIntermittent: true) {
+            try await fixture(name: "Traits") { fixturePath in
+                // The swiftbuild build system doesn't yet have the ability for command plugins to request symbol graphs
+                try await withKnownIssue(
+                    "https://github.com/swiftlang/swift-build/issues/609",
+                    isIntermittent: true,
+                ) {
+                    let (stdout, _) = try await executeSwiftPackage(
+                        fixturePath.appending("Package10"),
+                        configuration: configuration,
+                        extraArgs: ["plugin", "extract"],
+                        buildSystem: buildSystem,
+                    )
+                    let path = String(stdout.split(whereSeparator: \.isNewline).first!)
+                    let symbolGraph = try String(contentsOfFile: "\(path)/Package10Library1.symbols.json", encoding: .utf8)
+                    #expect(symbolGraph.contains("TypeGatedByPackage10Trait1"))
+                    #expect(symbolGraph.contains("TypeGatedByPackage10Trait2"))
+                } when: {
+                    buildSystem == .swiftbuild && ProcessInfo.hostOperatingSystem == .windows
+                }
             }
+        } when: {
+            !CiEnvironment.runningInSmokeTestPipeline
         }
     }
 

Original file line number	Diff line number	Diff line change
`@@ -5971,7 +5971,7 @@ struct PackageCommandTests {`
`5971`	`5971`	`func commandPluginSymbolGraphCallbacks(`
`5972`	`5972`	`data: BuildData,`
`5973`	`5973`	`) async throws {`
`5974`		`- try await withKnownIssue {`
	`5974`	`+ try await withKnownIssue(isIntermittent: true) {`
`5975`	`5975`	`try await testWithTemporaryDirectory { tmpPath in`
`5976`	`5976`	`// Create a sample package with a library, and executable, and a plugin.`
`5977`	`5977`	`let packageDir = tmpPath.appending(components: "MyPackage")`
`@@ -6102,7 +6102,8 @@ struct PackageCommandTests {`
`6102`	`6102`	`}`
`6103`	`6103`	`}`
`6104`	`6104`	`} when: {`
`6105`		`- ProcessInfo.hostOperatingSystem == .windows && data.buildSystem == .swiftbuild`
	`6105`	`+ (ProcessInfo.hostOperatingSystem == .windows && data.buildSystem == .swiftbuild)`
	`6106`	`+ \|\| !CiEnvironment.runningInSmokeTestPipeline`
`6106`	`6107`	`}`
`6107`	`6108`	`}`
`6108`	`6109`