[xcodegen] Add --buildable-folders

This enables the use of folder references for
compatible targets, allowing new source files to
be added without needing to regenerate the project.
Currently disabled by default; I'd like to get
some living-on before enabling.

Author: hamishknight

utils/swift-xcodegen/README.md

@@ -90,6 +90,15 @@ PROJECT CONFIGURATION:
   --prefer-folder-refs/--no-prefer-folder-refs
                           Whether to prefer folder references for groups containing non-source
                           files (default: --no-prefer-folder-refs)
+  --buildable-folders/--no-buildable-folders
+                          Requires Xcode 16: Enables the use of "buildable folders", allowing
+                          folder references to be used for compatible targets. This allows new
+                          source files to be added to a target without needing to regenerate the
+                          project.
+
+                          Only supported for targets that have no per-file build settings. This
+                          unfortunately means some Clang targes such as 'lib/Basic' and 'stdlib'
+                          cannot currently use buildable folders. (default: --no-buildable-folders)
 
 MISC:
   --project-root-dir <project-root-dir>

utils/swift-xcodegen/Sources/SwiftXcodeGen/BuildArgs/ClangBuildArgsProvider.swift

@@ -83,6 +83,11 @@ struct ClangBuildArgsProvider {
     return .init(for: .clang, args: fileArgs.sorted())
   }
 
+  /// Whether the given path has any unique args not covered by `parent`.
+  func hasUniqueArgs(for path: RelativePath, parent: RelativePath) -> Bool {
+    args.hasUniqueArgs(for: path, parent: parent)
+  }
+
   /// Whether the given file has build arguments.
   func hasBuildArgs(for path: RelativePath) -> Bool {
     !args.getArgs(for: path).isEmpty

utils/swift-xcodegen/Sources/SwiftXcodeGen/BuildArgs/CommandArgTree.swift

@@ -46,4 +46,14 @@ struct CommandArgTree {
   ) -> Set<Command.Argument> {
     getArgs(for: path).subtracting(getArgs(for: parent))
   }
+
+  /// Whether the given path has any unique args not covered by `parent`.
+  func hasUniqueArgs(for path: RelativePath, parent: RelativePath) -> Bool {
+    let args = getArgs(for: path)
+    guard !args.isEmpty else { return false }
+    // Assuming `parent` is an ancestor of path, the arguments for parent is
+    // guaranteed to be a subset of the arguments for `path`. As such, we
+    // only have to compare sizes here.
+    return args.count != getArgs(for: parent).count
+  }
 }

utils/swift-xcodegen/Sources/SwiftXcodeGen/Generator/ProjectGenerator.swift

@@ -182,7 +182,6 @@ fileprivate final class ProjectGenerator {
     // group there.
     if ref.kind == .folder {
       guard groups[path] == nil else {
-        log.warning("Skipping blue folder '\(path)'; already added")
         return nil
       }
     }
@@ -211,24 +210,35 @@ fileprivate final class ProjectGenerator {
   }
 
   func generateBaseTarget(
-    _ name: String, at parentPath: RelativePath?,
+    _ name: String, at parentPath: RelativePath?, canUseBuildableFolder: Bool,
     productType: Xcode.Target.ProductType?, includeInAllTarget: Bool
   ) -> Xcode.Target? {
     guard targets[name] == nil else {
       log.warning("Duplicate target '\(name)', skipping")
       return nil
     }
-    // Make sure we can create a group for the parent path, otherwise
-    // this is nested in a folder reference and there's nothing we can do.
-    if let parentPath, !parentPath.components.isEmpty,
-       group(for: repoRelativePath.appending(parentPath)) == nil {
-      return nil
+    var buildableFolder: Xcode.FileReference?
+    if let parentPath, !parentPath.components.isEmpty {
+      // If we've been asked to use buildable folders, see if we can create
+      // a folder reference at the parent path. Otherwise, create a group at
+      // the parent path. If we can't create either a folder or group, this is
+      // nested in a folder reference and there's nothing we can do.
+      if spec.useBuildableFolders && canUseBuildableFolder {
+        buildableFolder = getOrCreateRepoRef(.folder(parentPath))
+      }
+      guard buildableFolder != nil ||
+              group(for: repoRelativePath.appending(parentPath)) != nil else {
+        return nil
+      }
     }
     let target = project.addTarget(productType: productType, name: name)
     targets[name] = target
     if includeInAllTarget {
       allTarget.addDependency(on: target)
     }
+    if let buildableFolder {
+      target.addBuildableFolder(buildableFolder)
+    }
     target.buildSettings.common.ONLY_ACTIVE_ARCH = "YES"
     target.buildSettings.common.USE_HEADERMAP = "NO"
     // The product name needs to be unique across every project we generate
@@ -274,8 +284,12 @@ fileprivate final class ProjectGenerator {
     }
     unbuildableSources += targetInfo.unbuildableSources
 
-    for header in targetInfo.headers {
-      getOrCreateRepoRef(.file(header))
+    // Need to defer the addition of headers since the target may want to use
+    // a buildable folder.
+    defer {
+      for header in targetInfo.headers {
+        getOrCreateRepoRef(.file(header))
+      }
     }
 
     // If we have no sources, we're done.
@@ -289,8 +303,20 @@ fileprivate final class ProjectGenerator {
       }
       return
     }
+    // Can only use buildable folders if there are no unique arguments and no
+    // unbuildable sources.
+    // TODO: To improve the coverage of buildable folders, we ought to start
+    // automatically splitting umbrella Clang targets like 'stdlib', since
+    // they always have files with unique args.
+    let canUseBuildableFolders =
+      try spec.useBuildableFolders && targetInfo.unbuildableSources.isEmpty &&
+      targetInfo.sources.allSatisfy {
+        try !buildDir.clangArgs.hasUniqueArgs(for: $0.path, parent: targetPath)
+      }
+
     let target = generateBaseTarget(
-      targetInfo.name, at: targetInfo.parentPath, productType: .staticArchive,
+      targetInfo.name, at: targetPath,
+      canUseBuildableFolder: canUseBuildableFolders, productType: .staticArchive,
       includeInAllTarget: includeInAllTarget
     )
     guard let target else { return }
@@ -464,7 +490,7 @@ fileprivate final class ProjectGenerator {
       )
     }
     let target = generateBaseTarget(
-      targetInfo.name, at: nil, productType: nil,
+      targetInfo.name, at: nil, canUseBuildableFolder: false, productType: nil,
       includeInAllTarget: includeInAllTarget
     )
     guard let target else { return nil }
@@ -505,9 +531,11 @@ fileprivate final class ProjectGenerator {
     guard checkNotExcluded(buildRule.parentPath, for: "Swift target") else {
       return nil
     }
+    // Create the target. Swift targets can always use buildable folders
+    // since they have a consistent set of arguments.
     let target = generateBaseTarget(
-      targetInfo.name, at: buildRule.parentPath, productType: .staticArchive,
-      includeInAllTarget: includeInAllTarget
+      targetInfo.name, at: buildRule.parentPath, canUseBuildableFolder: true,
+      productType: .staticArchive, includeInAllTarget: includeInAllTarget
     )
     guard let target else { return nil }
 

utils/swift-xcodegen/Sources/SwiftXcodeGen/Generator/ProjectSpec.swift

@@ -40,6 +40,9 @@ public struct ProjectSpec {
   /// files.
   public var preferFolderRefs: Bool
 
+  /// Whether to enable the use of buildable folders for targets.
+  public var useBuildableFolders: Bool
+
   /// If provided, the paths added will be implicitly appended to this path.
   let mainRepoDir: RelativePath?
 
@@ -55,7 +58,7 @@ public struct ProjectSpec {
     addClangTargets: Bool, addSwiftTargets: Bool,
     addSwiftDependencies: Bool, addRunnableTargets: Bool,
     addBuildForRunnableTargets: Bool, inferArgs: Bool, preferFolderRefs: Bool,
-    mainRepoDir: RelativePath? = nil
+    useBuildableFolders: Bool, mainRepoDir: RelativePath? = nil
   ) {
     self.name = name
     self.buildDir = buildDir
@@ -67,6 +70,7 @@ public struct ProjectSpec {
     self.addBuildForRunnableTargets = addBuildForRunnableTargets
     self.inferArgs = inferArgs
     self.preferFolderRefs = preferFolderRefs
+    self.useBuildableFolders = useBuildableFolders
     self.mainRepoDir = mainRepoDir
   }
 

utils/swift-xcodegen/Sources/swift-xcodegen/Options.swift

@@ -202,6 +202,21 @@ struct ProjectOptions: ParsableArguments {
   )
   var preferFolderRefs: Bool = false
 
+  @Flag(
+    name: .customLong("buildable-folders"), inversion: .prefixedNo,
+    help: """
+      Requires Xcode 16: Enables the use of "buildable folders", allowing
+      folder references to be used for compatible targets. This allows new
+      source files to be added to a target without needing to regenerate the
+      project.
+      
+      Only supported for targets that have no per-file build settings. This
+      unfortunately means some Clang targes such as 'lib/Basic' and 'stdlib' 
+      cannot currently use buildable folders.
+      """
+  )
+  var useBuildableFolders: Bool = false
+
   @Option(help: .hidden)
   var blueFolders: String = ""
 }

utils/swift-xcodegen/Sources/swift-xcodegen/SwiftXcodegen.swift

@@ -72,7 +72,7 @@ struct SwiftXcodegen: AsyncParsableCommand, Sendable {
       addRunnableTargets: false,
       addBuildForRunnableTargets: self.addBuildForRunnableTargets,
       inferArgs: self.inferArgs, preferFolderRefs: self.preferFolderRefs,
-      mainRepoDir: mainRepoDir
+      useBuildableFolders: self.useBuildableFolders, mainRepoDir: mainRepoDir
     )
   }