There are multiple ways to obtain Foundation, and they have different tradeoffs to consider. This document discusses the various ways Foundation is distributed and offers recommended workflows.
This document was inspired by the equivalent Distributions.md in swift-testing.
Foundation is distributed in the following places:
- In Apple's macOS, iOS, and other Apple platforms, as a framework built into the operating system.
- In Swift.org toolchains, as a library included in the toolchain.
The locations above are considered built-in because they're included with a
larger collection of software (such as an operating system, toolchain, or IDE)
and consist of pre-compiled copies of the FoundationEssentials and
FoundationInternationalization modules.
Important
Prefer using a built-in copy of Foundation unless you're making changes to Foundation itself.
Foundation is also available as a Swift package library product from the swiftlang/swift-foundation repository. This copy is not considered built-in because it must be downloaded and compiled separately by each client.
Although Foundation is available as a Swift package, and hence you can declare a dependency on swift-foundation during development, it is not suitable for use in a package or app that you intend to ship. Doing so has several downsides:
- It requires building Foundation and its dependencies from source. This significantly increases your build time.
- You may encounter build failures when another package uses a built-in Foundation. If you use swift-foundation as a package, but you depend on a library from another package which uses a built-in copy of Foundation (as this document recommends), this can cause build failures due to ambiguous symbol definitions or module conflicts.
If you are contributing to Foundation or otherwise working on its source code, building it as a Swift package is the recommended workflow. The core contributors regularly develop Foundation this way, and its CI builds as a package as well. See Contributing for detailed steps on getting started.
It's also sometimes helpful to use swift-foundation as a package in order to validate how changes made to Foundation will impact tools or libraries that depend on it, or to test changes to both Foundation and a related project 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 to avoid those problems.