Add option to explain a given module dependency

Adds support for '-explain-dependency <MODULE_NAME>', which causes the driver to run a dependency scan, and find all dependency paths that cause the main module to depend, directly or transitively, on a given module dependency.

Author: artemcm

Sources/SwiftDriver/Driver/Driver.swift

@@ -1370,6 +1370,37 @@ extension Driver {
       return
     }
 
+    // If we're only supposed to explain a dependency on a given module, do so now.
+    if let explainModuleName = parsedOptions.getLastArgument(.explainModuleDependency) {
+      guard let dependencyPlanner = explicitDependencyBuildPlanner else {
+        fatalError("Cannot explain dependency without Explicit Build Planner")
+      }
+      guard let dependencyPaths = try dependencyPlanner.explainDependency(explainModuleName.asSingle) else {
+        diagnosticEngine.emit(.remark("No such module dependency found: '\(explainModuleName.asSingle)'"))
+        return
+      }
+      diagnosticEngine.emit(.remark("Module '\(moduleOutputInfo.name)' depends on '\(explainModuleName.asSingle)'"))
+      for path in dependencyPaths {
+        var pathString:String = ""
+        for (index, moduleId) in path.enumerated() {
+          switch moduleId {
+          case .swift(let moduleName):
+            pathString = pathString + "[" + moduleName + "]"
+          case .swiftPrebuiltExternal(let moduleName):
+            pathString = pathString + "[" + moduleName + "]"
+          case .clang(let moduleName):
+            pathString = pathString + "[" + moduleName + "](ObjC)"
+          case .swiftPlaceholder(_):
+            fatalError("Unexpected unresolved Placeholder module")
+          }
+          if index < path.count - 1 {
+            pathString = pathString + " -> "
+          }
+        }
+        diagnosticEngine.emit(.note(pathString))
+      }
+    }
+
     if parsedOptions.contains(.driverPrintOutputFileMap) {
       if let outputFileMap = self.outputFileMap {
         stderrStream <<< outputFileMap.description

Sources/SwiftDriver/ExplicitModuleBuilds/ExplicitDependencyBuildPlanner.swift

@@ -124,7 +124,6 @@ public typealias ExternalTargetModuleDetailsMap = [ModuleDependencyId: ExternalT
     }
     for moduleId in swiftDependencies {
       let moduleInfo = try dependencyGraph.moduleInfo(of: moduleId)
-      let pcmArgs = try dependencyGraph.swiftModulePCMArgs(of: moduleId)
       var inputs: [TypedVirtualPath] = []
       let outputs: [TypedVirtualPath] = [
         TypedVirtualPath(file: moduleInfo.modulePath.path, type: .swiftModule)
@@ -488,6 +487,12 @@ public typealias ExternalTargetModuleDetailsMap = [ModuleDependencyId: ExternalT
   }
 }
 
+internal extension ExplicitDependencyBuildPlanner {
+  func explainDependency(_ dependencyModuleName: String) throws -> [[ModuleDependencyId]]? {
+    return try dependencyGraph.explainDependency(dependencyModuleName: dependencyModuleName)
+  }
+}
+
 // InterModuleDependencyGraph printing, useful for debugging
 internal extension InterModuleDependencyGraph {
   func prettyPrintString() throws -> String {

Sources/SwiftDriver/ExplicitModuleBuilds/InterModuleDependencies/CommonDependencyOperations.swift

@@ -222,3 +222,48 @@ extension InterModuleDependencyGraph {
                       details: .clang(combinedModuleDetails))
   }
 }
+
+internal extension InterModuleDependencyGraph {
+  func explainDependency(dependencyModuleName: String) throws -> [[ModuleDependencyId]]? {
+    guard modules.contains(where: { $0.key.moduleName == dependencyModuleName }) else { return nil }
+    var results = [[ModuleDependencyId]]()
+    try findAllPaths(source: .swift(mainModuleName),
+                     to: dependencyModuleName,
+                     pathSoFar: [.swift(mainModuleName)],
+                     results: &results)
+    return Array(results)
+  }
+
+
+  private func findAllPaths(source: ModuleDependencyId,
+                            to moduleName: String,
+                            pathSoFar: [ModuleDependencyId],
+                            results: inout [[ModuleDependencyId]]) throws {
+    let sourceInfo = try moduleInfo(of: source)
+    // If the source is our target, we are done
+    guard source.moduleName != moduleName else {
+      // If the source is a target Swift module, also check if it
+      // depends on a corresponding Clang module with the same name.
+      // If it does, add it to the path as well.
+      var completePath = pathSoFar
+      if let dependencies = sourceInfo.directDependencies,
+         dependencies.contains(.clang(moduleName)) {
+        completePath.append(.clang(moduleName))
+      }
+      results.append(completePath)
+      return
+    }
+
+    // If no more dependencies, this is a leaf node, we are done
+    guard let dependencies = sourceInfo.directDependencies else {
+      return
+    }
+
+    for dependency in dependencies {
+      try findAllPaths(source: dependency,
+                       to: moduleName,
+                       pathSoFar: pathSoFar + [dependency],
+                       results: &results)
+    }
+  }
+}

Sources/SwiftDriver/Jobs/Planning.swift

@@ -140,7 +140,8 @@ extension Driver {
                                                           IncrementalCompilationState.InitialStateForPlanning?)
   throws -> InterModuleDependencyGraph? {
     let interModuleDependencyGraph: InterModuleDependencyGraph?
-    if parsedOptions.contains(.driverExplicitModuleBuild) {
+    if parsedOptions.contains(.driverExplicitModuleBuild) ||
+       parsedOptions.contains(.explainModuleDependency) {
       interModuleDependencyGraph =
         try initialIncrementalState?.maybeUpToDatePriorInterModuleDependencyGraph ??
             gatherModuleDependencies()
@@ -195,13 +196,15 @@ extension Driver {
     dependencyGraph: InterModuleDependencyGraph?,
     addJob: (Job) -> Void)
   throws {
-    // If asked, add jobs to precompile module dependencies
-    guard parsedOptions.contains(.driverExplicitModuleBuild) else { return }
     guard let resolvedDependencyGraph = dependencyGraph else {
-      fatalError("Attempting to plan explicit dependency build without a dependency graph")
+      return
     }
     let modulePrebuildJobs =
         try generateExplicitModuleDependenciesJobs(dependencyGraph: resolvedDependencyGraph)
+    // If asked, add jobs to precompile module dependencies. Otherwise exit.
+    // We may have a dependency graph but not be required to add pre-compile jobs to the build plan,
+    // for example when `-explain-dependency` is being used.
+    guard parsedOptions.contains(.driverExplicitModuleBuild) else { return }
     modulePrebuildJobs.forEach(addJob)
   }
 

Sources/SwiftOptions/Options.swift

@@ -18,6 +18,11 @@
 //===----------------------------------------------------------------------===//
 
 extension Option {
+  // ACTODO before merging: Add in the main repo and re-sync here
+  public static let explainModuleDependency: Option = Option("-explain-module-dependency", .separate,
+                                                       attributes: [.helpHidden, .doesNotAffectIncrementalBuild],
+                                                       helpText: "Show a dependency chain to a specified module",
+                                                       group: .internalDebug)
   public static let INPUT: Option = Option("<input>", .input, attributes: [.argumentIsPath])
   public static let HASHHASHHASH: Option = Option("-###", .flag, alias: Option.driverPrintJobs)
   public static let abi: Option = Option("-abi", .flag, attributes: [.noDriver], helpText: "Dumping ABI interface")
@@ -791,6 +796,7 @@ extension Option {
 extension Option {
   public static var allOptions: [Option] {
     return [
+      Option.explainModuleDependency,
       Option.INPUT,
       Option.HASHHASHHASH,
       Option.abi,

Tests/SwiftDriverTests/ExplicitModuleBuildTests.swift

@@ -1613,6 +1613,53 @@ final class ExplicitModuleBuildTests: XCTestCase {
     XCTAssertEqual(moduleMap[1].sourceInfoPath!.path.description, "B.swiftsourceinfo")
     XCTAssertEqual(moduleMap[1].isFramework, false)
   }
+
+
+  func testTraceDependency() throws {
+    try withTemporaryDirectory { path in
+      try localFileSystem.changeCurrentWorkingDirectory(to: path)
+      let moduleCachePath = path.appending(component: "ModuleCache")
+      try localFileSystem.createDirectory(moduleCachePath)
+      let main = path.appending(component: "testTraceDependency.swift")
+      try localFileSystem.writeFileContents(main) {
+        $0 <<< "import C;"
+        $0 <<< "import E;"
+        $0 <<< "import G;"
+      }
+
+      let cHeadersPath: AbsolutePath =
+          testInputsPath.appending(component: "ExplicitModuleBuilds")
+                        .appending(component: "CHeaders")
+      let swiftModuleInterfacesPath: AbsolutePath =
+          testInputsPath.appending(component: "ExplicitModuleBuilds")
+                        .appending(component: "Swift")
+      let sdkArgumentsForTesting = (try? Driver.sdkArgumentsForTesting()) ?? []
+      var driver = try Driver(args: ["swiftc",
+                                     "-I", cHeadersPath.nativePathString(escaped: true),
+                                     "-I", swiftModuleInterfacesPath.nativePathString(escaped: true),
+                                     "-explicit-module-build", "-v",
+                                     "-module-cache-path", moduleCachePath.nativePathString(escaped: true),
+                                     "-working-directory", path.nativePathString(escaped: true),
+                                     "-explain-module-dependency", "A",
+                                     main.nativePathString(escaped: true)] + sdkArgumentsForTesting,
+                              env: ProcessEnv.vars)
+      let jobs = try driver.planBuild()
+      try driver.run(jobs: jobs)
+      XCTAssertTrue(!driver.diagnosticEngine.diagnostics.isEmpty)
+      XCTAssertTrue(driver.diagnosticEngine.diagnostics.contains { $0.behavior == .remark &&
+                                                                   $0.message.text == "Module 'testTraceDependency' depends on 'A'"})
+
+      for diag in driver.diagnosticEngine.diagnostics {
+        print(diag.behavior)
+        print(diag.message)
+      }
+      XCTAssertTrue(driver.diagnosticEngine.diagnostics.contains { $0.behavior == .note &&
+                                                                   $0.message.text == "[testTraceDependency] -> [A] -> [A](ObjC)"})
+      XCTAssertTrue(driver.diagnosticEngine.diagnostics.contains { $0.behavior == .note &&
+                                                                   $0.message.text == "[testTraceDependency] -> [C](ObjC) -> [B](ObjC) -> [A](ObjC)"})
+    }
+  }
+
 // We only care about prebuilt modules in macOS.
 #if os(macOS)
   func testPrebuiltModuleGenerationJobs() throws {