swift-corelibs-foundation: four projects, one umbrella module, and a duplicated flag in the Windows instructions

Four projects converge on swift-foundation

The project navigator draws the whole arrangement in one diagram, and it is worth reading before anything else:

  graph TD;
      FF[Foundation.framework]-->SF
      subgraph GitHub
        SCLF[swift-corelibs-foundation]-->SF
        SF[swift-foundation]-->FICU[swift-foundation-icu]
        SF-->SC[swift-collections]
      end

Two paths lead to the same node. Apple's Foundation.framework, the copy built into macOS and iOS, points at swift-foundation, and so does swift-corelibs-foundation. From there the shared implementation branches to swift-foundation-icu and to swift-collections.

The Apple framework section makes the sharing concrete: it compiles the sources from swift-foundation into its binary and exposes one Foundation module containing all features. So on Darwin the same Swift implementation is inside the operating system framework, and the compatibility layer is the only part that exists only outside it. The diagram names the ICU package swift-foundation-icu while the section heading above it calls the same component Foundation ICU.

Non-Darwin only, and the modules it installs are named

swift-corelibs-foundation builds for non-Darwin platforms only. That is not a technical limitation so much as a division of labour: on macOS, iOS and other Apple platforms the guidance is to use the Foundation that comes with the operating system.

What it installs is specific. Three modules, the Foundation umbrella module, FoundationXML, and FoundationNetworking. The umbrella exists because clients written before swift-foundation expect to import a single module named Foundation, and the compatibility library re-exports FoundationEssentials and FoundationInternationalization so that source keeps compiling.

Those two re-exported modules are also where the newer API surface lives. URL, Data, JSONDecoder, Locale and Calendar are named as the core types, implemented in Swift, with the source shared across all platforms. The distinction to hold in your head is that the umbrella module is the compatibility shape, and the two modules underneath it are the actual implementation.

Best effort compatibility is stated once, in a subordinate clause

One sentence carries the most important caveat on the page. The compatibility library is written in Swift and C, provides NSObject, class-based data structures, NSFormatter and NSKeyedArchiver among other types, and then says that as these implementations are distinct from those written in Objective-C, the compatibility is best-effort only.

That is the whole difference between the two Foundations in one clause. Nothing is shared with the Objective-C original. Types whose names begin with NS are reimplemented, and the reimplementation is a reimplementation, not a binding. So behaviour that depends on an undocumented Objective-C detail is exactly where a Linux result and a macOS result are most likely to differ.

The projects framing supports this reading rather than contradicting it. The stated goals are a small set of basic utility classes, consistent conventions, internationalization and localization, and a level of OS independence to enhance portability. Nothing in that list promises identical behaviour across platforms, only portability.

The ICU boundary is a module boundary you can choose

Foundation ICU is described as a private library for Foundation that wraps ICU. Two reasons are given for using a standard ICU version: it provides stability in the behaviour of the internationalization API, and it gives consistency with the latest releases on Darwin platforms.

The mechanism that matters for a client is the import. Foundation ICU is imported from the FoundationInternationalization module only. Clients that do not need API relying on the data ICU provides are told to import FoundationEssentials instead.

So there is a dependency decision hidden in an import line. A service that formats dates and numbers through the internationalization module pulls ICU in, while one that only needs the essentials types stays clear of it. That is a real design choice with a practical consequence, and it is stated in the architecture section rather than buried in a guide.

swift-foundation depends on swift-syntax, which is an unusual thing to find

The dependency sentence says swift-foundation depends on a limited set of packages, primarily swift-collections and swift-syntax. The first is the expected companion. The second is a less obvious building block for a library that provides URL, Data and Calendar.

The project does not explain the dependency on the page. It is a fact worth knowing before you vendor this into a constrained environment, because the dependency set is described as limited while also reaching into a syntax tool.

One more detail from the same page: the repository's recorded primary language is C, while the architecture section describes swift-foundation as written in Swift and the compatibility library as written in Swift and C. That is consistent with a compatibility layer that still carries C sources, and it explains why a Swift project shows up as C in language statistics.

The Windows instructions repeat --target and name four dependencies, then three

On Linux the remaining native dependencies, dispatch, zlib, curl and libxml, are found in the Swift toolchain or on the host OS, and SwiftPM fetches most of the rest. Windows does not ship zlib, curl or libxml on the host, so those have to be built first, and the repository ships a CMake target that does it and prints the environment variables needed to connect the SwiftPM build:

cmake -G Ninja -B build -DFOUNDATION_SWIFTPM_DEPS=YES
cmake --build build --target WindowsSwiftPMDependencies

The repository example repeats --target; the command above uses the documented CMake syntax with one --target and a concrete build directory. The upstream text lists zlib, curl and libxml for Windows while dispatch comes from the toolchain.

The contributions section links a docs page the root does not have

The contributions section invites pull requests and then does two specific things. It points at a known issues page for anyone who wants an area that needs help, and it points at the Swift community mailing lists.

The known issues link is written as Docs/Issues.md, a capital D. The repository root contains eleven entries, and none of them is a docs directory. What is there is a CONTRIBUTING.md, a CMakeLists.txt, a Package.swift, a .mailmap, and the Sources, Tests and cmake directories. So the page a newcomer is sent to for the list of known problems is not in this repository as it stands, which is an unfortunate first stop for the exact audience the sentence is aimed at.

The root is otherwise unusually small for a library of this size. No docs directory, no examples directory, no scripts folder. Documentation for a project this central is expected to live elsewhere, and the readme does say there is more information on the Foundation framework on Apple's developer site.

Releases are named after Swift releases, so this project has no version of its own

The release list is not this project's. It is swift-6.4.2-RELEASE from 2026-10-30, swift-6.4.0-RELEASE from 2026-09-15 and swift-6.1.1-RELEASE from 2025-05-24. These are toolchain tags, which means swift-corelibs-foundation does not carry an independent version number and has no changelog of its own to point at.

The gap between 6.1.1 and 6.4.0 is also worth noting plainly: sixteen months between 6.1.1 in May 2025 and 6.4.0 in September 2026. Whatever else that means, it means the most recent release was cut alongside a toolchain, not on a schedule of this repository's own.

Building follows the same logic. As a standalone project it is a Swift Package Manager package, and the instruction is to run swift build in the root of the checkout. It also builds as part of the toolchain for non-Darwin platforms, with those instructions in the Swift project itself. The using example is a few lines of Swift with URLComponents, and it assumes you have already installed a Swift binary distribution.

Editorial conclusion

Foundation for non-Darwin platforms is in a better position than it was, because the code Apple ships in its own framework and the code the Swift toolchain ships to Linux are the same swift-foundation sources, so fixes land in one place. What a team should understand before depending on it is the shape of the compromise. The compatibility layer is explicitly best effort, the Objective-C prefix types are reimplemented rather than shared, and ICU is reachable only through FoundationInternationalization, so an import that starts as FoundationEssentials avoids the dependency on ICU data. On Windows, budget a separate dependency build step, and note that the documented cmake line repeats --target, which may or may not be accepted by the generator in use. If exact behavioural parity with Apple's Foundation matters to your tests, the honest answer from this repository is that it does not promise it.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. swiftlang/swift-corelibs-foundation on GitHub