-
Notifications
You must be signed in to change notification settings - Fork 53
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add initial experimental support for combined documentation for multi…
…ple targets (#84) * Add a minimal build graph for documentation tasks rdar://116698361 * Build documentation for targets in reverse dependency order rdar://116698361 * Fix unrelated warning about a deprecated (renamed) DocC flag * Combine nested conditionals into one if-statement * Decode the supported features for a given DocC executable * List all the generated documentation archvies * Add flag to enable combined documentation support This flag allows the targets to link to each other and creates an additional combined archive. rdar://116698361 * Warn if the DocC executable doesn't support combined documentation * Update integration tests to more explicitly check for archive paths in console output * Update check-source to include 2024 as a supported year * Address code review feedback: - Check for errors after queue has run the build operations - Avoid repeat-visiting targets when constructing the build graph - Update internal-only documentation comment * Add a type to encapsulate performing work for each build graph item * Remove extra blank line before license comment which cause a false-positive source validation error
- Loading branch information
1 parent
5761ba9
commit 63f47d3
Showing
17 changed files
with
747 additions
and
67 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
112 changes: 112 additions & 0 deletions
112
Sources/SwiftDocCPluginUtilities/BuildGraph/DocumentationBuildGraph.swift
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,112 @@ | ||
| // This source file is part of the Swift.org open source project | ||
| // | ||
| // Copyright (c) 2024 Apple Inc. and the Swift project authors | ||
| // Licensed under Apache License v2.0 with Runtime Library Exception | ||
| // | ||
| // See https://swift.org/LICENSE.txt for license information | ||
| // See https://swift.org/CONTRIBUTORS.txt for Swift project authors | ||
|
|
||
| import Foundation | ||
|
|
||
| /// A target that can have a documentation task in the build graph | ||
| protocol DocumentationBuildGraphTarget { | ||
| typealias ID = String | ||
| /// The unique identifier of this target | ||
| var id: ID { get } | ||
| /// The unique identifiers of this target's direct dependencies (non-transitive). | ||
| var dependencyIDs: [ID] { get } | ||
| } | ||
|
|
||
| /// A build graph of documentation tasks. | ||
| struct DocumentationBuildGraph<Target: DocumentationBuildGraphTarget> { | ||
| fileprivate typealias ID = Target.ID | ||
| /// All the documentation tasks | ||
| let tasks: [Task] | ||
|
|
||
| /// Creates a new documentation build graph for a series of targets with dependencies. | ||
| init(targets: some Sequence<Target>) { | ||
| // Create tasks | ||
| let taskLookup: [ID: Task] = targets.reduce(into: [:]) { acc, target in | ||
| acc[target.id] = Task(target: target) | ||
| } | ||
| // Add dependency information to each task | ||
| for task in taskLookup.values { | ||
| task.dependencies = task.target.dependencyIDs.compactMap { taskLookup[$0] } | ||
| } | ||
|
|
||
| tasks = Array(taskLookup.values) | ||
| } | ||
|
|
||
| /// Creates a list of dependent operations to perform the given work for each task in the build graph. | ||
| /// | ||
| /// You can add these operations to an `OperationQueue` to perform them in dependency order | ||
| /// (dependencies before dependents). The queue can run these operations concurrently. | ||
| /// | ||
| /// - Parameter work: The work to perform for each task in the build graph. | ||
| /// - Returns: A list of dependent operations that performs `work` for each documentation task task. | ||
| func makeOperations(performing work: @escaping (Task) -> Void) -> [Operation] { | ||
| var builder = OperationBuilder(work: work) | ||
| for task in tasks { | ||
| builder.buildOperationHierarchy(for: task) | ||
| } | ||
|
|
||
| return Array(builder.operationsByID.values) | ||
| } | ||
| } | ||
|
|
||
| extension DocumentationBuildGraph { | ||
| /// A documentation task in the build graph | ||
| final class Task { | ||
| /// The target to build documentation for | ||
| let target: Target | ||
| /// The unique identifier of the task | ||
| fileprivate var id: ID { target.id } | ||
| /// The other documentation tasks that this task depends on. | ||
| fileprivate(set) var dependencies: [Task] | ||
|
|
||
| init(target: Target) { | ||
| self.target = target | ||
| self.dependencies = [] | ||
| } | ||
| } | ||
| } | ||
|
|
||
| extension DocumentationBuildGraph { | ||
| /// A type that builds a hierarchy of dependent operations | ||
| private struct OperationBuilder { | ||
| /// The work that each operation should perform | ||
| let work: (Task) -> Void | ||
| /// A lookup of operations by their ID | ||
| private(set) var operationsByID: [ID: Operation] = [:] | ||
|
|
||
| /// Adds new dependent operations to the builder. | ||
| /// | ||
| /// You can access the created dependent operations using `operationsByID.values`. | ||
| mutating func buildOperationHierarchy(for task: Task) { | ||
| let operation = makeOperation(for: task) | ||
| for dependency in task.dependencies { | ||
| let hasAlreadyVisitedTask = operationsByID[dependency.id] != nil | ||
|
|
||
| let dependentOperation = makeOperation(for: dependency) | ||
| operation.addDependency(dependentOperation) | ||
|
|
||
| if !hasAlreadyVisitedTask { | ||
| buildOperationHierarchy(for: dependency) | ||
| } | ||
| } | ||
| } | ||
|
|
||
| /// Returns the existing operation for the given task or creates a new operation if the builder didn't already have an operation for this task. | ||
| private mutating func makeOperation(for task: Task) -> Operation { | ||
| if let existing = operationsByID[task.id] { | ||
| return existing | ||
| } | ||
| // Copy the closure and the target into a block operation object | ||
| let new = BlockOperation { [work, task] in | ||
| work(task) | ||
| } | ||
| operationsByID[task.id] = new | ||
| return new | ||
| } | ||
| } | ||
| } |
54 changes: 54 additions & 0 deletions
54
Sources/SwiftDocCPluginUtilities/BuildGraph/DocumentationBuildGraphRunner.swift
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| // This source file is part of the Swift.org open source project | ||
| // | ||
| // Copyright (c) 2024 Apple Inc. and the Swift project authors | ||
| // Licensed under Apache License v2.0 with Runtime Library Exception | ||
| // | ||
| // See https://swift.org/LICENSE.txt for license information | ||
| // See https://swift.org/CONTRIBUTORS.txt for Swift project authors | ||
|
|
||
|
|
||
| import Foundation | ||
|
|
||
| /// A type that runs tasks for each target in a build graph in dependency order. | ||
| struct DocumentationBuildGraphRunner<Target: DocumentationBuildGraphTarget> { | ||
|
|
||
| let buildGraph: DocumentationBuildGraph<Target> | ||
|
|
||
| typealias Work<Result> = (DocumentationBuildGraph<Target>.Task) throws -> Result | ||
|
|
||
| func perform<Result>(_ work: @escaping Work<Result>) throws -> [Result] { | ||
| // Create a serial queue to perform each documentation build task | ||
| let queue = OperationQueue() | ||
| queue.maxConcurrentOperationCount = 1 | ||
|
|
||
| // Operations can't raise errors. Instead we catch the error from 'performBuildTask(_:)' | ||
| // and cancel the remaining tasks. | ||
| let resultLock = NSLock() | ||
| var caughtError: Error? | ||
| var results: [Result] = [] | ||
|
|
||
| let operations = buildGraph.makeOperations { [work] task in | ||
| do { | ||
| let result = try work(task) | ||
| resultLock.withLock { | ||
| results.append(result) | ||
| } | ||
| } catch { | ||
| resultLock.withLock { | ||
| caughtError = error | ||
| queue.cancelAllOperations() | ||
| } | ||
| } | ||
| } | ||
|
|
||
| // Run all the documentation build tasks in dependency order (dependencies before dependents). | ||
| queue.addOperations(operations, waitUntilFinished: true) | ||
|
|
||
| // If any of the build tasks raised an error. Re-throw that error. | ||
| if let caughtError { | ||
| throw caughtError | ||
| } | ||
|
|
||
| return results | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.