From 7e330295d432dc055915c4e1864ddcbd20af6f7f Mon Sep 17 00:00:00 2001 From: Stuart Montgomery Date: Mon, 15 Dec 2025 19:05:14 -0600 Subject: [PATCH 1/2] Document the official distribution locations and the recommendation to use a built-in copy --- Documentation/Distributions.md | 100 +++++++++++++++++++++++++++++++++ Documentation/README.md | 4 ++ 2 files changed, 104 insertions(+) create mode 100644 Documentation/Distributions.md diff --git a/Documentation/Distributions.md b/Documentation/Distributions.md new file mode 100644 index 000000000..8700870fe --- /dev/null +++ b/Documentation/Distributions.md @@ -0,0 +1,100 @@ +# Obtaining Swift Testing + + + +There are multiple ways to obtain Swift Testing, and they have different +tradeoffs to consider. This document discusses the various ways Swift Testing is +distributed and offers recommended workflows. + +## Distribution locations + +Swift Testing is distributed in the following places: + +* In [Swift.org toolchains][install], versions 6.0 and later (for + [supported platforms][]), as a dynamic library. +* In Apple’s [Xcode IDE][], versions 16.0 and later, as a framework. +* In Apple’s [Command Line Tools for Xcode package][], versions 16.0 and later, + as a framework. + +The locations above are considered **built-in** because they're included with a +larger collection of software (such as a toolchain, IDE, or system package) and +consist of _pre-compiled_ copies of the `Testing` module, its associated runtime +libraries, and its macro plugin. + +> [!IMPORTANT] +> Prefer using a built-in copy of Swift Testing unless you're making changes to +> Swift Testing itself. + +Swift Testing is also available as a Swift **package library product** from the +[swiftlang/swift-testing][swift-testing] repository. This copy is _not_ +considered built-in because it must be downloaded and compiled separately by +each client. The package version is generally considered to have a lower level +of support than the built-in copies above due to the [known caveats][caveats] +described in the following section. + +## Caveats when using Swift Testing as a package + +Although Swift Testing is available as a Swift package and you _can_ declare a +dependency on [swift-testing][] to use it, doing so is not generally recommended +because it has several downsides: + +* **It requires building the Swift Testing runtime library.** This increases + your build time, and since builds for testing are typically for debug + configuration, it will not include performance optimizations. +* **It requires building Swift Testing’s macro plugin.** This also increases + build time, especially because it often requires building [SwiftSyntax][] as + well. (SwiftSyntax now offers [prebuilt copies][prebuilt-swift-syntax], but + Swift Testing doesn't always declare a dependency on one of the prebuilt tags, + circumventing this time-saver.) Additionally, the locally-built macro plugin + and SwiftSyntax will be built for debug, without optimizations. +* **It may not integrate as well with spporting tools/IDEs as a built-in copy.** + Tools which integrate with Swift Testing such as Swift Package Manager or + Apple's Xcode IDE often optimize for the copy included in the same + distribution. Some features may not work as well or be missing entirely when + using Swift Testing as a package. +* **It may encounter build failures when another package uses Swift + Testing.** If you use Swift Testing as a package, but you depend on a library + from another package which uses a built-in copy of Swift Testing (as this + document recommends), this can cause build failures: + * The other package may fail to build non-deterministically due to not having + a target dependency on the `Testing` target from the locally-built + [swift-testing][] package. + * On platforms which don't support a two-level linker namespace, it can fail + to link due to duplicate defintions for the symbols in the `Testing` library. +* **It may misbehave at runtime.** Even if your build doesn't encounter one of + the failures mentioned above, mixing built-in and package copies of Swift + Testing can lead to runtime problems, such as issues (e.g. `#expect` failures) + being silently ignored. + +## When to use Swift Testing as a package + +The primary reason Swift Testing is available to be used as a Swift package is +to support its own development. The core contributors regularly develop Swift +Testing by building it locally as a package, following workflows described in +[Contributing][], and its CI builds that way as well. + +It's also sometimes helpful to use Swift Testing as a package in order to +validate how changes made to the testing library will impact supporting tools, +or to test changes to both the testing library and a related tool in conjunction +with each other. When using one of these workflows locally, it's important to be +mindful of the [caveats][] above, but during local development it's often +possible to take extra care and control things sufficiently to avoid those +problems. + +[install]: https://www.swift.org/install +[supported platforms]: https://github.com/swiftlang/swift-testing/blob/main/README.md#cross-platform-support +[Xcode IDE]: https://developer.apple.com/xcode/ +[Command Line Tools for Xcode package]: https://developer.apple.com/documentation/xcode/installing-the-command-line-tools/ +[swift-testing]: https://github.com/swiftlang/swift-testing +[SwiftSyntax]: https://github.com/swiftlang/swift-syntax +[Contributing]: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md +[caveats]: #caveats-when-using-swift-testing-as-a-package +[prebuilt-swift-syntax]: https://www.swift.org/blog/swift-6.2-released/#macro-build-performance diff --git a/Documentation/README.md b/Documentation/README.md index 3ef579986..e7442e338 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -23,6 +23,10 @@ as supplemental content located in the [`Sources/Testing/Testing.docc/`](https://github.com/swiftlang/swift-testing/tree/main/Sources/Testing/Testing.docc) directory. +[Obtaining Swift Testing](https://github.com/swiftlang/swift-testing/blob/main/Documentation/Distributions.md) +discusses the various ways Swift Testing is distributed and offers recommended +usage workflows. + ## Vision document and API proposals The [Vision document](https://github.com/swiftlang/swift-evolution/blob/main/visions/swift-testing.md) From 19bdc28d6f7683252b776b1d88c10109869cedfa Mon Sep 17 00:00:00 2001 From: Stuart Montgomery Date: Tue, 16 Dec 2025 12:58:12 -0600 Subject: [PATCH 2/2] Apply suggestions from code review Fix a couple typos Co-authored-by: Joseph Heck --- Documentation/Distributions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/Distributions.md b/Documentation/Distributions.md index 8700870fe..47176dd4a 100644 --- a/Documentation/Distributions.md +++ b/Documentation/Distributions.md @@ -55,7 +55,7 @@ because it has several downsides: Swift Testing doesn't always declare a dependency on one of the prebuilt tags, circumventing this time-saver.) Additionally, the locally-built macro plugin and SwiftSyntax will be built for debug, without optimizations. -* **It may not integrate as well with spporting tools/IDEs as a built-in copy.** +* **It may not integrate as well with supporting tools/IDEs as a built-in copy.** Tools which integrate with Swift Testing such as Swift Package Manager or Apple's Xcode IDE often optimize for the copy included in the same distribution. Some features may not work as well or be missing entirely when @@ -68,7 +68,7 @@ because it has several downsides: a target dependency on the `Testing` target from the locally-built [swift-testing][] package. * On platforms which don't support a two-level linker namespace, it can fail - to link due to duplicate defintions for the symbols in the `Testing` library. + to link due to duplicate definitions for the symbols in the `Testing` library. * **It may misbehave at runtime.** Even if your build doesn't encounter one of the failures mentioned above, mixing built-in and package copies of Swift Testing can lead to runtime problems, such as issues (e.g. `#expect` failures)