[opensourcedex]

swift-build is a free, open source build & deployment project written in Swift and released under Apache-2.0. It has 2,253 GitHub stars, 242 forks and 139 open issues, and was last pushed 4 days ago. On this registry it ranks #47 of 84 tracked projects in Build & Deployment, with 5 head-to-head comparisons available. It gained 11 stars over the last 30 tracked days.

What is swift-build?

Swift Build is a high-level build system based on llbuild with strong support for building Swift, and it is the build engine used by Xcode, Swift Playground, and the Swift Package Manager.

What it is

Swift Build is a high-level build system written in Swift and released under the Apache-2.0 licence, built on top of the lower-level llbuild engine. It exists to turn a description of a project into a planned, executable build, and it ships as the build engine behind three separate Swift tools: SwiftPM, Xcode, and Swift Playground. Within the Swift ecosystem it occupies the layer above llbuild and beneath those clients, which is why its testing strategy is built around project model objects that emulate the ones a higher-level client would construct.

The concrete problem it solves is the SwiftPM build system itself. In Swift 6.2 and 6.3 the existing system can be swapped out by passing --build-system swiftbuild, and in nightly snapshots of Swift's main branches Swift Build is already the default. Rather than every client reimplementing build planning, the project exposes a build system service that Xcode, xcodebuild, and SwiftPM can all drive, with task construction handled in a module such as SWBTaskConstruction that plans builds and produces an inspectable build graph.

Key capabilities

  • Builds Swift as a high-level build system layered on llbuild, and serves as the build system for SwiftPM, Xcode, and Swift Playground.
  • Enabled in Swift 6.2 and 6.3 with the --build-system swiftbuild flag, and used as the default SwiftPM build system in nightly snapshots of Swift's main branches.
  • Provides the launch-xcode command plugin, run as swift package --disable-sandbox launch-xcode, which launches the currently xcode-selected Xcode.app configured against a modified copy of the build system service.
  • Provides the run-xcodebuild command plugin, run as swift package --disable-sandbox run-xcodebuild, which runs xcodebuild against the modified service and forwards any arguments after -- unmodified.
  • Supports debugging of SwiftPM builds by running swift run --debugger swift-build ..., and debugging of the Xcode and xcodebuild workflows by attaching to the SWBBuildServiceBundle process.
  • Ships technical documentation in SwiftBuild.docc, previewable with docc preview SwiftBuild.docc, or xcrun docc preview SwiftBuild.docc on macOS.
  • Runs its test suite with swift test, organised into targets that each map to a component, such as SWBTaskConstructionTests for the SWBTaskConstruction module.

Who uses it and how

  • SwiftPM and Swift Build maintainers testing linked changes, using SWIFTCI_USE_LOCAL_DEPS=1 swift build --package-path /path/to/swiftpm against a full checkout of the Swift repositories.
  • Developers co-developing SwiftPM and Swift Build together in Xcode on macOS, using the SwiftPM+SwiftBuild.xcworkspace workspace kept in the Utilities directory.
  • Xcode contributors validating build system changes inside a real Xcode instance, by running the launch-xcode plugin from a checkout of swift-build.
  • Build engineers validating changes through the command-line toolchain, by running the run-xcodebuild plugin and forwarding extra arguments to xcodebuild.
  • Contributors preparing pull requests, who are expected to run the full suite with swift test from the repository root before submitting, with bug reports filed in the swift-build GitHub issue tracker.

Getting started

For SwiftPM users, enable it with swift build --build-system swiftbuild on Swift 6.2 or 6.3, or rely on it as the default in nightly snapshots of Swift's main branches. When SwiftPM is built from source, Swift Build is built alongside it as a package dependency.

How it compares

No paid or closed products are listed as things this project replaces, so the meaningful comparison is with the layer directly beneath it: llbuild is the lower-level build engine, while Swift Build is the high-level system layered on top of it, adding Swift-aware build planning and the service that Xcode, xcodebuild, and SwiftPM drive. It does not replace a general-purpose build tool outside the Swift ecosystem.

When to use it — and when not to

Use Swift Build when working inside the Swift toolchain, either through SwiftPM on Swift 6.2 and 6.3 or through the Xcode and xcodebuild workflows, and accept that both plugin workflows run with --disable-sandbox and are only supported against the latest available Xcode version. Do not pick it for non-Swift projects or as a general build runner; it is scoped to Swift and to the clients that consume it. Note also that the opt-in flag is still the path on Swift 6.2 and 6.3, that default status currently applies only to nightly snapshots, and that the tracker carries 139 open issues, so the project should be treated as moving code tied to Swift's release cadence rather than a frozen, independently versioned product.

project readme (upstream, from github) — read inline

Swift Build

Swift Build is a high-level build system based on llbuild with great support for building Swift. It is used by SwiftPM, Xcode, and Swift Playground.

Usage

With SwiftPM

Swift Build is the default SwiftPM build system in nightly snapshots of Swift's main branches. In Swift 6.2 and 6.3, it can be enabled by passing --build-system swiftbuild. When building SwiftPM from source it will be built as a package dependency. When checking out the full set of Swift repositories, SWIFTCI_USE_LOCAL_DEPS=1 swift build --package-path /path/to/swiftpm can be used to test local changes to Swift Build and SwiftPM together. The Utilities directory also contains SwiftPM+SwiftBuild.xcworkspace which allows codeveloping the two repositories in Xcode on macOS.

With Xcode

Changes to swift-build can also be tested in Xcode using the launch-xcode command plugin provided by the package. Run swift package --disable-sandbox launch-xcode from your checkout of swift-build to launch a copy of the currently xcode-selected Xcode.app configured to use your modified copy of the build system service. This workflow is generally only supported when using the latest available Xcode version.

With xcodebuild

Changes to swift-build can also be tested in xcodebuild using the run-xcodebuild command plugin provided by the package. Run swift package --disable-sandbox run-xcodebuild from your checkout of swift-build to run xcodebuild from the currently xcode-selected Xcode.app configured to use your modified copy of the build system service. Arguments followed by -- will be forwarded to xcodebuild unmodified. This workflow is generally only supported when using the latest available Xcode version.

Debugging

When using Swift Build with SwiftPM, the build process runs entirely within the swift-build (or swift-test, swift-run, etc.) process. You can debug by using swift run --debugger swift-build ... or an IDE like VSCode or Xcode.

When using the Xcode or xcodebuild workflows above, you can easily set breakpoints and debug. First, open the swift-build package containing your changes in Xcode and choose the "Debug > Attach to Process by PID or Name…" menu item. In the panel that appears, type "SWBBuildServiceBundle" as the process name and click "Attach". The debugger will wait for the process to launch. Run the relevant command shown above to launch Xcode or xcodebuild, and once you open a workspace the swift-build process will launch and the debugger will attach to it automatically.

Documentation

SwiftBuild.docc contains additional technical documentation.

To view the documentation in browser, run the following command at the root of the project:

docc preview SwiftBuild.docc

On macOS, use:

xcrun docc preview SwiftBuild.docc

Testing

Before submitting the pull request, please make sure you have tested your changes. You can run the full test suite by running swift test from the root of the repository. The test suite is organized into a number of different test targets, with each corresponding to a specific component. For example, SWBTaskConstructionTests contains tests for the SWBTaskConstruction module which plan builds and then inspect the resulting build graph. Many tests in Swift Build operate on test project model objects which emulate those constructed by a higher level client and validate behavior at different layers. You can learn more about how these tests are written and organized in Project Tests.

Contributing to Swift Build

Contributions to Swift Build are welcomed and encouraged! Please see the Contributing to Swift guide.

Before submitting the pull request, please make sure that they follow the Swift project guidelines for contributing code. Bug reports should be filed in the issue tracker of swift-build repository on GitHub.

To be a truly great community, Swift.org needs to welcome developers from all walks of life, with different backgrounds, and with a wide range of experience. A diverse and friendly community will have more great ideas, more unique perspectives, and produce more great code. We will work diligently to make the Swift community welcoming to everyone.

To give clarity of what is expected of our members, Swift has adopted the code of conduct defined by the Contributor Covenant. This document is used across many open source communities, and we think it articulates our values well. For more, see the Code of Conduct.

License

See https://swift.org/LICENSE.txt for license information.

Frequently asked questions

Is swift-build free to use?

swift-build is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does swift-build do?

A high-level build system based on llbuild, used by Xcode, Swift Playground, and the Swift Package Manager

What is swift-build written in?

swift-build is primarily written in Swift. Its source is publicly available at https://github.com/swiftlang/swift-build, and it has 2,253 GitHub stars.