Swift Package Manager/Xcode

No setup is required to start using Buf's generated Swift SDKs with Xcode.

However, Xcode doesn't yet support using the Swift Package Manager CLI and Package.swift for iOS/Mac apps. Dependency management for these targets is still done with git repositories. To account for this, Buf provides a read-only git server for generated SDKs, which is available at the https://buf.build/gen/swift/git host.

If you aren't developing an iOS, macOS, watchOS, or tvOS app and use a Package.swift manifest file to control your package and its dependencies, please use our Swift Package Manager implementation.

Adding a dependency

To find the git URLs for your BSR module, go to the module's SDKs tab, which you can find at https://{host}/{org}/{module}/sdks. Ensure you have the Swift language and the Xcode tab selected.

1. In your Xcode project, navigate to File > Add Packages....

2. In the popup window, click into the Search or Enter Package URL text field in the top right and paste the provided SDK's .git URL:

   https://buf.build/gen/swift/git/0.8.0-20230913231627-233fca715f49.1/connectrpc_eliza_connectrpc_swift.git
   

3. Next, for the Dependency Rule, select Branch and point it to main.

4. Click Add Package. A new pop-up will appear prompting you to link the SDK's products to your app.

5. Ensure the library is checked and click Add to confirm the SDK addition (there will only ever be one library). Note that this will automatically add any transitive dependencies.

When using generated SDKs sourced from the read-only git server with Xcode, only use the Branch dependency rule providing the main branch, or the Exact Version dependency rule, providing the SemVer, as the ranging rules will not function.

Note: Since Buf lazily produces a separate git URL for each version of an SDK upon first request, Xcode's auto-update functionality doesn't work with these generated SDKs. To update an SDK, navigate to the module's SDKs tab and get a new link for a new version. Then manually update the dependency by replacing the existing SDK with the SDK sourced from the new link.

To find the references for your BSR module to use with Swift Package Manager, go to the module's SDKs page, which you can find at https://{host}/{org}/{module}/sdks. Ensure you have the Swift language and the SPM tab selected.

Setup

To enable Swift Package Manager to properly resolve all dependencies with the buf scope, set up the project registry with the following command:

$ swift package-registry set https://buf.build/gen/swift --scope=buf

Adding a dependency

Add a dependency on the generated SDK:

1. Add a package dependency to the dependencies block of your Package.swift manifest file:

   Package.swift

   dependencies: [
       .package(
           id: "buf.connectrpc_eliza_connectrpc_swift",
           exact: "0.8.0-20230913231627-233fca715f49.1"
       )
   ],
   

2. Add a product dependency to the dependencies block of your target's entry:

   Package.swift

   .target(
       name: "ExamplePackage",
       dependencies: [
           .product(
               name: "Connectrpc_Eliza_Connectrpc_Swift",
               package: "buf.connectrpc_eliza_connectrpc_swift"
           ),
       ]
   ),
   

When you attempt to access a private BSR module's generated SDKs with Xcode, a prompt window will appear. In the prompt window, ensure that it's requesting your username and password, and not the other VCS-based alternatives (GitHub, GitLab). Supply the username and token in these fields.

To access the private module, execute the following with the swift toolchain, which will associate the token with the registry in the swift configuration file ~/.swiftpm/configuration/registries.json and create a macOS Keychain (or .netrc file) entry to store the credentials locally:

$ swift package-registry login https://buf.build/gen/swift/login --token={token}

The login API was introduced in Swift 5.8. Please ensure your Swift toolchain version is 5.8 or later.