update example to use async await APIs (#4263)

motivation: async / await APIs are great, use them as example!

changes:
* expose some of workspace public APIs as async/await ones (in addition to the callback ones)
* update the example to use @main and call the async / await APIs

Author: tomerd

Examples/package-info/Package.swift

@@ -1,22 +1,25 @@
-// swift-tools-version:5.1
+// swift-tools-version:5.5
 
 import PackageDescription
 
 let package = Package(
     name: "package-info",
     platforms: [
-        .macOS(.v10_15),
+        .macOS(.v12),
         .iOS(.v13)
     ],
     dependencies: [
         // This just points to the SwiftPM at the root of this repository.
-        .package(path: "../../"),
+        .package(name: "swift-package-manager", path: "../../"),
         // You will want to depend on a stable semantic version instead:
         // .package(url: "https://github.com/apple/swift-package-manager", .exact("0.4.0"))
     ],
     targets: [
-        .target(
+        .executableTarget(
             name: "package-info",
-            dependencies: ["SwiftPM"]),
+            dependencies: [
+                .product(name: "SwiftPM", package: "swift-package-manager")
+            ]
+        ),
     ]
 )

Examples/package-info/Sources/package-info/example.swift

@@ -0,0 +1,50 @@
+import Basics
+import TSCBasic
+import Workspace
+
+@main
+@available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+struct Example {
+    static func main() async throws {
+        // PREREQUISITES
+        // ============
+
+        // We need a package to work with.
+        // This computes the path of this package root based on the file location
+        let packagePath = AbsolutePath(#file).parentDirectory.parentDirectory.parentDirectory
+
+        // LOADING
+        // =======
+
+        // There are several levels of information available.
+        // Each takes longer to load than the level above it, but provides more detail.
+
+        let observability = ObservabilitySystem({ print("\($0): \($1)") })
+
+        let workspace = try Workspace(forRootPackage: packagePath)
+
+        let manifest = try await workspace.loadRootManifest(at: packagePath, observabilityScope: observability.topScope)
+
+        let package = try await workspace.loadRootPackage(at: packagePath, observabilityScope: observability.topScope)
+
+        let graph = try workspace.loadPackageGraph(rootPath: packagePath, observabilityScope: observability.topScope)
+        
+        // EXAMPLES
+        // ========
+
+        // Manifest
+        let products = manifest.products.map({ $0.name }).joined(separator: ", ")
+        print("Products:", products)
+
+        let targets = manifest.targets.map({ $0.name }).joined(separator: ", ")
+        print("Targets:", targets)
+
+        // Package
+        let executables = package.targets.filter({ $0.type == .executable }).map({ $0.name })
+        print("Executable targets:", executables)
+
+        // PackageGraph
+        let numberOfFiles = graph.reachableTargets.reduce(0, { $0 + $1.sources.paths.count })
+        print("Total number of source files (including dependencies):", numberOfFiles)
+    }
+}

Examples/package-info/Sources/package-info/main.swift

@@ -1155,6 +1155,16 @@ extension Workspace {
         )
     }
 
+    /// Loads and returns manifests at the given paths.
+    @available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+    public func loadRootManifests(packages: [AbsolutePath], observabilityScope: ObservabilityScope) async throws -> [AbsolutePath: Manifest] {
+        return try await withCheckedThrowingContinuation{ continuation in
+            self.loadRootManifests(packages: packages, observabilityScope: observabilityScope) { result in
+                continuation.resume(with: result)
+            }
+        }
+    }
+
     /// Loads and returns manifests at the given paths.
     public func loadRootManifests(
         packages: [AbsolutePath],
@@ -1196,11 +1206,21 @@ extension Workspace {
         }
     }
 
+    /// Loads and returns manifest at the given path.
+    @available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+    public func loadRootManifest(at path: AbsolutePath, observabilityScope: ObservabilityScope) async throws -> Manifest {
+        return try await withCheckedThrowingContinuation{ continuation in
+            self.loadRootManifest(at: path, observabilityScope: observabilityScope) { result in
+                continuation.resume(with: result)
+            }
+        }
+    }
+
     /// Loads and returns manifest at the given path.
     public func loadRootManifest(
         at path: AbsolutePath,
         observabilityScope: ObservabilityScope,
-        completion: @escaping(Result<Manifest, Error>) -> Void
+        completion: @escaping (Result<Manifest, Error>) -> Void
     ) {
         self.loadRootManifests(packages: [path], observabilityScope: observabilityScope) { result in
             completion(result.tryMap{
@@ -1236,6 +1256,17 @@ extension Workspace {
         )
     }
 
+    /// Loads root package
+    @available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+    public func loadRootPackage(at path: AbsolutePath, observabilityScope: ObservabilityScope) async throws -> Package {
+        return try await withCheckedThrowingContinuation{ continuation in
+            self.loadRootPackage(at: path, observabilityScope: observabilityScope) { result in
+                continuation.resume(with: result)
+            }
+        }
+    }
+
+    /// Loads root package
     public func loadRootPackage(
         at path: AbsolutePath,
         observabilityScope: ObservabilityScope,