Discover and curate Swift Packages using Collections

Highlight

Xcode 13 introduces Swift Package collections, allowing developers to discover, filter, sign and import Swift packages using shareable JSON manifests, and bring package metadata directly into Xcode and SwiftPM workflows.

Core Content

When you copy a piece of Swift code from a blog and paste it into Xcode, the first thing that often happens is that the compilation fails. The module has not been added to the project. Next, you need to go back to the article to find the GitHub address, confirm the package name, select the version rule, and then go back to Xcode to add dependencies.

As the number of packages increases, search becomes a problem. A team may only be allowed to use audited packages. The course author hopes that students will get the supporting dependencies directly. Bloggers want readers to take one less step. A GitHub link alone cannot convey the license, README, release history, and product list.

Xcode 13’s Swift Package collections solve this entry problem. A collection is a JSON file, typically obtained over HTTPS, that lists a set of package URLs and metadata. Both Xcode and Swift Package Manager (SwiftPM) can read this collection.

Apple also built in default collections in Xcode 13. In the demo, the developerimport NumericsAfter encountering a missing module, Xcode directly gives fix-it and opens a new Add Package process. This flow displays the latest version, author, license, README and Release History. Once added, the dependency appears in the project’s Swift Packages tab, and the product is linked to the target’s Frameworks, Libraries, and Embedded Content stage.

Collections can also be maintained by yourself. Educators can publish a collection to a course. Businesses can release a reviewed collection to internal teams. Community authors can assign a collection to articles, allowing readers to reproduce experiments based on the same set of dependencies.

Detailed Content

A collection is a JSON with metadata

（04:28）

The base format of Swift Package collections is JSON. It contains the collection level name, overview, keywords, authors, and also contains the package list. Each package requires at least a URL. The generation tool automatically fetches more information.

{
  "name": "WWDC21 Demo Collection",
  "overview": "Packages to be used in our demo app",
  "keywords": ["wwdc21"],
  "author": {
    "name": "Boris Buegling"
  },
  "packages": [
    { "url": "https://github.com/apple/swift-format" },
    { "url": "https://github.com/Alamofire/Alamofire" }
  ]
}

Key points:

nameis the name of the collection as it appears in Xcode. -overviewDescribes the purpose of this collection, which will be displayed when adding a collection. -keywordsUsed to describe the collection theme. -author.nameIdentifies the collection author. -packagesis a list of package URLs from which Xcode and SwiftPM will continue to read package information.

（07:17）

Collections also support supplementing metadata for individual packages. In the demonstration,swift-formatThe package adds summary, keywords, version restrictions, excluded products, and README URL.

{
  "name": "WWDC21 Demo Collection",
  "overview": "Packages to be used in our demo app",
  "keywords": ["wwdc21"],
  "packages": [
    {
      "url": "https://github.com/apple/swift-format",
      "summary": "Formatting technology for Swift source code.",
      "keywords": ["formatting", "swift"],
      "versions": ["0.50400.0", "0.50300.0"],
      "excludedProducts": ["SwiftFormatConfiguration"],
      "readmeURL": "https://github.com/apple/swift-format/blob/main/README.md"
    },
    { "url": "https://github.com/Alamofire/Alamofire" }
  ],
  "author": {
    "name": "Boris Buegling"
  }
}

Key points:

urlPoints to the Swift package repository. -summaryWill improve presentation and search results in Xcode. -keywordsAdd search keywords to individual packages. -versionsLimit the version range represented by the collection. -excludedProductsYou can hide products you don’t want readers to choose. -readmeURLBy specifying the README address, Xcode can display the README in the package details.

Create collection files using generators

（08:46）

Apple releases Swift Package Collection Generator. The input is a JSON consisting of a package URL and optional metadata. The output is a shareable collection JSON. The generator will automatically collect package information and output files in the latest format.

package-collection-generate --verbose input.json collection.json --auth-token

Key points:

package-collection-generateIs the command to generate a collection. ---verboseOutput more process information, and use it in the demonstration to view the process of the generator grabbing the package version. -input.jsonis a handwritten input file containing the package URL and optional metadata. -collection.jsonIt is a generated collection file that can be continued for signing or distributed directly. ---auth-tokenUsed to let tools query more metadata via the GitHub API.

Collection of signatures, confirming authorship and integrity

（09:30）

Signing is an optional step. It allows SwiftPM to verify the collection author and also protect the collection contents from modification. The demonstration uses a separate signing tool to combine the generated JSON, private key and certificate into a signature set.

package-collection-sign collection.json collection-signed.json developer-key.pem developer-cert.cer

Key points:

package-collection-signis a signature command. -collection.jsonis the collection generated in the previous stage. -collection-signed.jsonIs the signed output file. -developer-key.pemIs the private key used for signing. -developer-cert.cerIt is the corresponding certificate.
The SwiftPM documentation states the requirements for certificates that can be used for signing: the certificate needs to be valid, not expired, and not revoked.

Adding and inspecting collections with SwiftPM

（10:15）

SwiftPM providespackage-collectionsubcommand. Once you add a collection, it goes into the local cache and is available to Xcode. SwiftPM’s collection capabilities come from libSwiftPM (SwiftPM library), which also provides Xcode’s package functionality.

swift package-collection add https://example.com/collection-signed.json

Key points:

swiftCall the SwiftPM command line tool. -package-collectionEnter the collection management subcommand. -addAdd the remote collection to the current machine’s configuration.
URL points to a published collection JSON, which can be a signed collection.

（10:34）

Once added, the entire collection can be inspected. In the demo, the output includes collection metadata, package list, and signature information.

swift package-collection describe

Key points:

describeView overall information for a configured collection without a package URL.
The output shows the previously written collection metadata.
The output lists the packages in the collection.
If the collection is signed, the output shows the signer and the result of SwiftPM’s verification.

（11:11）

You can also view details for individual packages in the collection. Demo useswift-formatThe repository URL, the output includes available versions, authors, stars, README URL, Swift tools version, modules and products.

swift package-collection describe https://github.com/apple/swift-format

Key points:

describeWhen followed by a package URL, view metadata for an individual package. -https://github.com/apple/swift-formatis the package to check.
The output will display the cached packet information in the collection.
This information is also the basis for the Xcode Add Package process to display rich details.

Using packages from collections in Xcode

（12:01）

Xcode can also add custom collections. The path is File > Add Packages, click+, paste the collection URL, and click Load. Xcode displays the number of packages contained in the collection and when it was updated. After the collection is added, a list of packages appears in the Add Package panel.

（13:07）

The demo app adds Alamofire from the collection and makes a README request in the SwiftUI view.

import SwiftUI
import Alamofire

struct ContentView: View {
  let readMeURL = "https://raw.githubusercontent.com/apple/swift/main/README.md"

  var body: some View {
    Button("Click me!") {
      AF.request(readMeURL).response { response in
        debugPrint(response)
      }
    }
  }
}

Key points:

import SwiftUIsupplyView、Buttonandbody。
import AlamofireIntroduce the network library just added to the project. -readMeURLSave the original file address of the Swift repository README. -Button("Click me!")Create a button. -AF.request(readMeURL)Use Alamofire to make network requests. -.responseReceive request results. -debugPrint(response)Print the response to the debug console to confirm that dependencies are linked and available.

Core Takeaways

What: Maintain a collection of “allowed Swift packages” for the team. Why it’s worth doing: Collections can narrow the scope of choices, and in enterprise scenarios can direct developers to reviewed packages. How to get started: Createinput.json, put the internally approved package URL intopackages,usepackage-collection-generateBuild the collection and publish it via an internal HTTPS address.
What to do: Assign a dependency set to a technical article or course. Why it’s worth doing: Readers can directly see the packages used in the article after opening Xcode, reducing the steps of copying the warehouse address and selecting products. How to start: Write the article sample dependencies as a collection, such as Alamofire, swift-format, and provide the collection URL at the beginning of the article.
What to do: Establish a “Recommended Extension Pack” entry for open source projects. Why it’s worth doing: Collections support abstracts, keywords, README URLs and version restrictions, and can organize supporting tools and sample dependencies into a group. How to get started: Refill for each packsummary、keywords、readmeURL, use when necessaryexcludedProductsHide irrelevant products.
What to do: Periodically rebuild the collection in CI. Why it’s worth doing: The generator outputs the collection in the latest format and grabs the package metadata. Collection publishers do not need to manually maintain every version detail. How to get started: Run in an automation taskpackage-collection-generate --verbose input.json collection.json --auth-token, upload to the fixed URL after generation.
What: Publish signature collections to external developers. Why it’s worth doing: SwiftPM can display the signer and verification results, helping users confirm the source of the collection and the integrity of the content. How to start: Prepare a valid code signing certificate and runpackage-collection-sign collection.json collection-signed.json developer-key.pem developer-cert.cer, distribute the signed JSON.

Meet DocC documentation in Xcode — Use DocC to generate browsable documentation for Swift packages and frameworks.
Host and automate your DocC documentation — Host Swift package documentation online and connect to the automated process.
Meet the Swift Algorithms and Collections packages — Learn about Algorithms and Collections in Apple’s open source Swift package ecosystem.
What’s new in Swift — Learn about Swift 5.5 language, toolchain, and ecosystem updates.

Highlight

Core Content

Detailed Content

A collection is a JSON with metadata

Create collection files using generators

Collection of signatures, confirming authorship and integrity

Adding and inspecting collections with SwiftPM

Using packages from collections in Xcode

Core Takeaways

Related Sessions

Comments