swift-corelibs-foundation: the Foundation compatibility layer for non-Darwin Swift

What swift-corelibs-foundation actually is, and who it is for

Foundation is a base layer of functionality that the README says is required for almost all applications: primitive classes, consistent conventions, internationalization, and a level of OS independence. On macOS, iOS and the other Apple platforms, that Foundation ships with the operating system. swift-corelibs-foundation exists for the platforms where it does not.

The README is explicit about the audience. This project "provides a compatibility implementation of the Foundation API for platforms where there is no Objective-C runtime," and it "builds for non-Darwin platforms only." It installs the Foundation umbrella module plus FoundationXML and FoundationNetworking. If you are writing an ordinary app on Linux, you are already consuming this code through the toolchain, whether or not you ever clone the repository. The people who clone it are toolchain builders and maintainers of code that predates the swift-foundation split.

That distinction matters more than it used to. The project navigator in the README shows two separate repositories feeding the same Foundation framework: swift-foundation, written in Swift and shared across all platforms, and swift-corelibs-foundation, which re-exports the FoundationEssentials and FoundationInternationalization modules and adds the compatibility API on top. The README describes the compatibility as "best-effort only," because these implementations are distinct from the Objective-C ones. That sentence is the single most important thing to read before depending on this code.

How the modules fit together: FoundationEssentials, FoundationInternationalization and the compatibility layer

The architecture is a split, not a monolith. swift-foundation provides the core implementation of URL, Data, JSONDecoder, Locale, Calendar and similar types inside two modules: FoundationEssentials and FoundationInternationalization. Its source is shared across platforms, and it depends on a limited set of packages, primarily swift-collections and swift-syntax.

swift-corelibs-foundation sits on top of that. It is written in Swift and C, and it supplies the pre-Swift API surface: NSObject, class-based data structures, NSFormatter, NSKeyedArchiver. It re-exports the two newer modules so that source written before the swift-foundation project existed still compiles. The Foundation framework on Darwin compiles the swift-foundation sources into its binary and presents one Foundation module containing everything; on non-Darwin platforms the same surface is assembled from these separate pieces.

A third repository, swift-foundation-icu, wraps ICU as a private library. The README explains the reason: using a standard version of ICU gives stability in the behavior of the internationalization API and consistency with the latest releases on Darwin. It is imported from FoundationInternationalization only. The practical consequence is that if your code does not need API relying on ICU data, you can import FoundationEssentials instead and carry less. That is the direction the project points toward, and the compatibility layer is the part you are meant to move off.

Building swift-corelibs-foundation on Linux and Windows

The README states that swift-corelibs-foundation builds as a standalone project using Swift Package Manager, and that you simply run swift build in the root of the checkout. It also builds as part of the toolchain for non-Darwin platforms, with instructions in the Swift project repository. The guide assumes you already have a version of the latest Swift binary distribution installed.

For a standalone build on Linux, the command is the one the README gives:

swift build

SwiftPM fetches most dependencies. The README says the remaining ones (dispatch, zlib, curl, libxml) are found in the Swift toolchain or on the host OS on Linux, so a plain build usually works there.

Windows is the case that needs preparation, because zlib, curl and libxml are not shipped with the host OS. The README says you must check out and build these dependencies before running swift build, using the provided CMake target, which instead of building Foundation via CMake will fetch and build the three dependencies and emit environment variables that connect the SwiftPM build to them:

cmake -G Ninja -B <build folder> -DFOUNDATION_SWIFTPM_DEPS=YES
cmake --build <build folder> --target --target WindowsSwiftPMDependencies

After that command, the output includes a list of environment variables to set. Once those are set, the README says you can run swift test or swift build just as on Linux. Note the duplicated --target in the second command exactly as the README prints it; if your CMake rejects it, that is a documentation defect rather than a configuration problem on your side.

For a first real use, the README's own sample is a short main.swift. It assumes a Swift toolchain is installed, and it exercises URLComponents:

import Foundation

// Make a URLComponents instance
let swifty = URLComponents(string: "https://swift.org")!

// Print something useful about the URL
print("\(swifty.host!)")

// Output: "swift.org"

Running it prints swift.org. The README points to the Swift Package Manager for building Swift apps generally, so a package with this file as an executable target is the normal path.

The best-effort compatibility promise is the real limitation

The README states plainly that the compatibility is best-effort only, because the implementations are distinct from those written in Objective-C. That is not a footnote. It means code that compiles and behaves one way against Darwin's Foundation may behave differently here, and the project does not promise otherwise. If your code depends on precise semantics of NSKeyedArchiver archives, NSFormatter output, or class-based collection behavior, you are relying on a reimplementation, not on the original.

The second constraint is scope. This project builds for non-Darwin platforms only, so it is not a way to get a newer Foundation onto macOS or iOS. On Apple platforms the README directs apps to the Foundation that comes with the operating system. If your problem is that Darwin's Foundation is missing something, this repository is not the answer.

The third is the direction of travel. The README frames swift-corelibs-foundation as providing "compatibility API for clients that need pre-Swift API from Foundation," while swift-foundation is described as the shared core implementation. A new project that reaches for NSObject or NSKeyedArchiver when FoundationEssentials would do is building on the part of the stack the project exists to keep alive, not the part it is developing. That is a defensible choice for a port, and a poor one for greenfield code.

How this differs from swift-foundation and the Darwin Foundation framework

The obvious alternative is swift-foundation, and the difference is not cosmetic. swift-foundation is written in Swift, its source is shared across all platforms, and it contains the core implementation of URL, Data, JSONDecoder, Locale and Calendar in FoundationEssentials and FoundationInternationalization. It depends on a limited set of packages, primarily swift-collections and swift-syntax. If your code can import those modules directly, you get the implementation rather than a compatibility shim over it, and you avoid the best-effort caveat entirely.

The other alternative is the Foundation framework that ships on Darwin, which is written in a combination of C, Objective-C and Swift and compiles the swift-foundation sources into its binary to present one Foundation module. Choosing it means choosing Apple's platforms; choosing swift-corelibs-foundation means choosing portability to platforms without an Objective-C runtime. The two are not interchangeable, and the README does not present them as such.

There is also a narrower choice inside this project: import FoundationEssentials instead of Foundation when you do not need ICU-backed internationalization. The README says clients that do not need API relying on ICU data can import FoundationEssentials, since the ICU wrapper is imported from FoundationInternationalization only. That is the cheapest way to reduce what you depend on without leaving the swift-foundation family.

Licence, releases and what maintenance costs you

The repository is licensed under Apache-2.0, with the LICENSE file at the top level. Apache-2.0 is a permissive licence that includes an express patent grant, which is the usual reason projects pick it over MIT or BSD for code that may end up in commercial products. It also carries notice and attribution obligations, so redistributing a modified copy means keeping the licence and notices intact. That is a general property of the licence text; whether it fits your distribution model is a question for your own counsel, not for this article.

The release cadence is tied to the toolchain, not to the repository. Recent releases listed for the project are swift-6.4.0-RELEASE on 2026-09-15, swift-6.1.1-RELEASE on 2025-05-24 and swift-6.1-RELEASE on 2025-04-01. The last push to the repository was on 2026-09-22. In practice you will rarely pick a version of swift-corelibs-foundation; you will pick a Swift toolchain, and the Foundation you get is the one that toolchain shipped. Upgrading Foundation therefore means upgrading Swift, with everything that implies for the rest of your build.

For contributors, the README points to Docs/Issues.md for known issues and to the Swift mailing lists for questions about what the project will accept. The top-level layout is conventional: Sources/, Tests/, Package.swift, CMakeLists.txt and a cmake/ directory, plus .github/, CONTRIBUTING.md, LICENSE and README.md.

Editorial conclusion

Adopt swift-corelibs-foundation if you are building the Swift toolchain for a non-Darwin platform, or if you maintain Swift code written against the pre-swift-foundation class-based Foundation API and need NSObject, NSFormatter or NSKeyedArchiver to keep compiling. Do not adopt it if you can import FoundationEssentials or FoundationInternationalization, because the README describes the compatibility layer as best-effort only and the newer modules are the shared implementation. Before you commit, check whether your code needs FoundationNetworking or FoundationXML, since those are separate installs, and on Windows confirm that you have built the zlib, curl and libxml dependencies through the CMake target before running swift build.

Frequently asked questions

Official sources

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