Repository files navigation

This repository contains a Bazel ruleset that can be used to download, build, and consume Swiftpackages. The rules in this repository build the external Swift packages usingrules_swift,rules_apple and native C/C++ rulesets making the Swift package products and targets available asBazel targets.

This repository is designed to fully replacerules_spm and provide utilities to ease Swiftdevelopment inside a Bazel workspace.

• Documentation
• Prerequisites
  • Mac OS
  • Linux
• Quickstart
  • 1. Enable bzlmod
  • 2. Configure yourMODULE.bazel to use rules_swift_package_manager.
    • (Optional) Useswift_package repository for updating packages
    • (Optional) Enableswift_deps_info generation for the Gazelle plugin
  • 3. Create a minimalPackage.swift file.
  • 4. Runswift package update
  • 5. Runbazel mod tidy.
  • 6. Build and test your project.
  • 7. Check inPackage.swift,Package.resolved, andMODULE.bazel.
  • 8. Start coding
• Using a Swift package registry
• Tips and Tricks

• Rules and API documentation
• High-level design
• Frequently Asked Questions

Be sure to install Xcode.

You will need toinstall Swift. Make surethat runningswift --version works properly.

Don't forget thatrules_swiftexpects the use ofclang. Hence,you will need to specifyCC=clang before running Bazel.

Finally, helprules_swift andrules_swift_package_manager find the Swift toolchain by ensuringthat aPATH that includes the Swift binary is available in the Bazel actions.

cat>>local.bazelrc<<EOFbuild --action_env=PATHEOF

This approach is necessary to successfully execute the examples on an Ubuntu runner using Githubactions. See theCI GitHub workflow for more details.

The following provides a quick introduction on how to set up and use the features in thisrepository. These instructions assume that you are usingBazel modules to load your externaldependencies. If you are using Bazel's legacy external dependency management, we recommend usingBazel's hybrid mode, then follow the steps in this quickstart guide.

Also, check out theexamples for more information.

This repository supportsbzlmod.

common --enable_bzlmod

Add a dependency onrules_swift_package_manager.

bazel_dep(name="rules_swift_package_manager",version="1.10.0")

In addition, add the following to load the external dependencies described in yourPackage.swiftandPackage.resolved files.

swift_deps=use_extension("@rules_swift_package_manager//:extensions.bzl","swift_deps",)swift_deps.from_package(resolved="//:Package.resolved",swift="//:Package.swift",)use_repo(swift_deps,"swift_deps_info",# This is generated by the ruleset.# The name of the Swift package repositories will be added to this declaration in step 4 after# running `bazel mod tidy`.# NOTE: The name of the Bazel external repository for a Swift package is `swiftpkg_xxx` where# `xxx` is the Swift package identity, lowercase, with punctuation replaced by `hyphen`. For# example, the repository name for apple/swift-nio is `swiftpkg_swift_nio`.)

You will also need to add a dependency onrules_swift.

NOTE: Some Swift package manager features (e.g., resources) use rules fromrules_apple. It is adependency forrules_swift_package_manager. However, you do not need to declare it unless you useany of the rules in your project.

Theswift_deps module extension will by default generate aswift_package repository which can be used to executeswift package commands.This is useful if you'd like to control the flags and behavior ofswift package, as well as for using the correctswift binary according to the Bazel configured toolchain.

For example, to resolve thePackage.swift file:

bazel run @swift_package//:resolve

To update packages to their latest supported version:

bazel run @swift_package//:update

Both targets support passing arguments as well, so for example, you could update a single package:

bazel run @swift_package//:update -- MyPackage

These targets will update thePackage.resolved file defined inswift_deps.from_package.The targets come with default flags applied to enable the best Bazel compatibility, if you wish to configure it further, you can do so withconfigure_swift_package:

# MODULE.bazelswift_deps.configure_swift_package(build_path="spm-build",cache_path="spm-cache",dependency_caching="false",manifest_cache="none",manifest_caching="false",)

If you do not want to use theswift_package repository you can disable it in theswift_deps.from_package call:

swift_deps.from_package(declare_swift_package=False,# <=== Disable the `swift_package` repositoryresolved="//:Package.resolved",swift="//:Package.swift",)

If you will be using theGazelle plugin for Swift, you will need to enable the generation oftheswift_deps_info repository by enablingdeclare_swift_deps_info.

swift_deps.from_package(declare_swift_deps_info=True,# <=== Enable swift_deps_info generation for the Gazelle pluginresolved="//:Package.resolved",swift="//:Package.swift",)

Create a minimalPackage.swift file that only contains the external dependencies that are directlyused by your Bazel workspace.

// swift-tools-version: 5.7import PackageDescriptionletpackage=Package(    name:"my-project",    dependencies:[        // Replace these entries with your dependencies..package(url:"https://github.com/apple/swift-argument-parser", from:"1.2.0"),.package(url:"https://github.com/apple/swift-log", from:"1.4.4"),])

The name of the package can be whatever you like. It is required for the manifest, but it is notused byrules_swift_package_manager. If your project is published and consumed as a Swift package,feel free to populate the rest of the manifest so that your package works properly by Swift packagemanager. Just note that theSwift Gazelle plugin does not use the manifest to generate Bazel buildfiles.

This will invoke Swift Package Manager and resolve all dependencies resulting in creation ofPackage.resolved file.

This will update yourMODULE.bazel with the correctuse_repo declaration.

Build and test your project.

bazeltest //...

• ThePackage.swift file is used byrules_swift_package_manager to generate information aboutyour project's dependencies.
• ThePackage.resolved file specifies that exact versions of the downloaded dependencies that wereidentified.
• TheMODULE.bazel contains the declarations for your external dependencies.

You are ready to start coding.

Seeour document on using a Swift package registry.

The following are a few tips to consider as you work with your repository:

• Are you trying to use a Swift package and it just won't build under Bazel? If you can figure outhow to fix it, you can patch the Swift package. Check outour document on patching Swift packages.