## 1. Project Overview & Quickstart (swiftlang/swift-corelibs-foundation)

# Foundation

The Foundation framework defines a base layer of functionality that is required for almost all applications. It provides primitive classes and introduces several paradigms that define functionality not provided by either the Objective-C runtime and language or Swift standard library and language.

It is designed with these goals in mind:

* Provide a small set of basic utility classes and data structures.
* Make software development easier by introducing consistent conventions.
* Support internationalization and localization, to make software accessible to users around the world.
* Provide a level of OS independence, to enhance portability.

There is more information on the Foundation framework [here](https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/ObjC_classic/).

This project, `swift-corelibs-foundation`, provides a compatibility implementation of the Foundation API for platforms where there is no Objective-C runtime. On macOS, iOS, and other Apple platforms, apps should use the Foundation that comes with the operating system.

## Project Navigator

Foundation builds in different configurations and is composed of several projects.

```mermaid
  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   
```

### Swift Foundation

A shared library shipped in the Swift toolchain, written in Swift. It provides the core implementation of many key types, including `URL`, `Data`, `JSONDecoder`, `Locale`, `Calendar`, and more in the `FoundationEssentials` and `FoundationInternationalization` modules. Its source code is shared across all platforms.

_swift-foundation_ depends on a limited set of packages, primarily [swift-collections](http://github.com/apple/swift-collections) and [swift-syntax](http://github.com/apple/swift-syntax).

### Swift Corelibs Foundation

A shared library shipped in the Swift toolchain. It provides compatibility API for clients that need pre-Swift API from Foundation. It is written in Swift and C. It provides, among other types, `NSObject`, class-based data structures, `NSFormatter`, and `NSKeyedArchiver`. It re-exports the `FoundationEssentials` and `FoundationInternationalization` modules, allowing compatibility for source written before the introduction of the _swift-foundation_ project. As these implementations are distinct from those written in Objective-C, the compatibility is best-effort only.

_swift-corelibs-foundation_ builds for non-Darwin platforms only. It installs the `Foundation` umbrella module, `FoundationXML`, and `FoundationNetworking`.

### Foundation ICU

A private library for Foundation, wrapping ICU. Using a standard version of ICU provides stability in the behavior of our internationalization API, and consistency with the latest releases on Darwin platforms. It is imported from the `FoundationInternationalization` module only. Clients that do not need API that relies upon the data provided by ICU can import `FoundationEssentials` instead.

### Foundation Framework

A [framework](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Frameworks.html) built into macOS, iOS, and all other Darwin platforms. It is written in a combination of C, Objective-C, and Swift. The Foundation framework compiles the sources from _swift-foundation_ into its binary and provides one `Foundation` module that contains all features.


## Using Foundation

Here is a simple `main.swift` file which uses Foundation. This guide assumes you have already installed a version of the latest [Swift binary distribution](https://swift.org/download/#latest-development-snapshots).

```swift
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"
```

You will want to use the [Swift Package Manager](https://swift.org/package-manager/) to build your Swift apps.

## Working on Foundation

swift-corelibs-foundation builds as a standalone project using Swift Package Manager. Simply use `swift build` in the root of the checkout to build the project.

swift-corelibs-foundation also builds as part of the toolchain for non-Darwin platforms. Instructions on building the toolchain are available in the [Swift project](https://github.com/swiftlang/swift?tab=readme-ov-file#building).

### Building swift-corelibs-foundation on Windows

When building Foundation as a standalone project, it requires you to provide some dependencies that it will link during the build. SwiftPM already fetches most of these dependencies and on Linux the remaining dependencies (dispatch, zlib, curl, libxml) are found in the Swift toolchain or on the host OS. However, Windows does not ship with zlib/curl/libxml on the host OS. In order to build swift-corelibs-foundation as a package on Windows, you must first checkout and build these dependenies before running `swift build` as recommended above. To do this, you can build the provided CMake target which (instead of building Foundation via CMake) will checkout and build these 3 dependencies via CMake and provide environment variables that will connect the SwiftPM build to these dependencies. To build these targets, run the following commands:

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

After running these commands, the output will include a list of environment variables to set. After setting these environment variables, you can run `swift test`/`swift build` just like on Linux in order to build swift-corelibs-foundation with an existing Swift toolchain.

## Contributions

We welcome contributions to Foundation! Please see the [known issues](Docs/Issues.md) page if you are looking for an area where we need help. We are also standing by on the [mailing lists](https://swift.org/community/#communication) to answer questions about what is most important to do and what we will accept into the project.

## 2. Official Technical Reference & Guides (swiftlang/docs)

## File: README.md

# Welcome to the Swift Project Documentation

This repository hosts multiple [DocC][docc] catalogs that provide the source location for documentation content for the Swift project, hosted at [www.swift.org][www.swift.org].
The repository provides a location to collect and collaborate on Documentation for the Swift open source project.
For more information on the intent and inception, read the [Swift Docs Proposal][docs-proposal].

Contributions to the Swift Documentation are welcomed and encouraged!

To be a truly great community, Swift Documentation welcomes developers from all walks of life, with different backgrounds, and with a wide range of experience.
A diverse and friendly community has more great ideas, more unique perspectives, and produces more great code. 
We work diligently to make the Swift Documentation 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][conduct].

## What's in this repository

The top levels of this repository generally host a very light Swift package that wraps a documentation catalog.
This repository isn't meant for consumable libraries, any documentation for a Swift library should be maintained with that library.
This library hosts general content related to the Swift language, guides, and cross-cutting details that support the Swift ecosystem more broadly.
Each of the catalogs is matched with an entry in the [CODEOWNERS][codeowners] file, which provides the technical reviewers for that catalog.

Each directory has it's own Swift package in order to support a full breadth of tooling for documentation and examples, including snippets. 
The packages in this repository aren't meant to be depended upon or provide library. 

## How you can help

- [Report issues with existing content][issues]
- [Report issues with missing content or request content][issues]
- Fix typos
- Propose new content

See [contributing][contributing] for more information on proposing new content, style and content guidelines, and the details of how contributors add content to the Swift Documentation.

[codeowners]: .github/CODEOWNERS
[www.swift.org]: https://www.swift.org/
[docs-proposal]: https://github.com/swiftlang/swift-org-website/blob/main/_info-architecture/0003-swift-docs-proposal.md
[issues]: https://github.com/swiftlang/docs/issues
[conduct]: https://www.swift.org/code-of-conduct
[contributing]: /CONTRIBUTING.md
[docc]: https://www.swift.org/documentation/docc/

---

## File: scripts/README.md

## Local validation

To build the combined documentation and view the result locally:

- from the docs repository root:
```bash
set -e
./scripts/build_docs.py
python3 -m http.server 8123 --directory .build-output
```

Then in another terminal:

```bash
open http://localhost:8123/main/documentation/
```

Serve from `.build-output` (the parent), not `.build-output/main`: the build
bakes a `/main/` hosting base path into every asset URL, so the `/main/` prefix
must map to the `main/` directory. This example avoids port 8000, which can be 
commonly used by other apps or examples. 

## Navigation manifest (combined sidebar curation)

`navigation.json` controls the left-hand navigator of the **combined** archive
(`docc merge` output): it groups modules under labelled sections, hides
internal modules, and orders them. Hidden modules are also pruned from the
synthesized landing page body (`data/documentation.json`), so they disappear
from the main page's module list as well as the sidebar. Each entry names a
`source` (a `sources.json` id) and the module `path` it applies to. Every module
in the merged index must be either placed in a group or listed under `hidden` —
`build_docs.py` validates and applies this automatically (the
`navigator-curation` build step), and fails the build on any mismatch or
uncovered module. See `../hacking-index-json.md` for the underlying mechanics.

A group's `title` is optional — omit it (or set it to `null`) for a headerless
group whose modules render with no section label in either the sidebar or the
landing page.

A group's `modules` list may also contain **external-link entries** — plain
links to content outside the archive, with no backing `sources.json` id. Give
these a `title` and an `https://` `url` instead of `source`/`path`:

```jsonc
{ "title": "Swift and C++", "url": "https://www.swift.org/documentation/cxx-interop/" }
```

External entries render in the sidebar only — they get no card on the
synthesized landing page — and aren't valid under `hidden` (there's no module
to hide). An optional `type` overrides the sidebar icon; it defaults to
`"resources"`.

### Checking the manifest while editing

Run the standalone checker — it does **not** modify any build output:

```bash
# From the repo root. Validates navigation.json against sources.json
# (no unknown sources, every source represented) and, if a combined archive
# exists at .build-output/<version>, dry-runs curation and previews the sidebar.
python3 scripts/validate_navigation.py
```

It exits non-zero when the manifest is invalid or a built archive contains a
module the manifest neither groups nor hides — so it doubles as a coverage
check. Point it at a specific archive (e.g. one you just built elsewhere) with:

```bash
python3 scripts/validate_navigation.py --archive path/to/combined.doccarchive
```

`--navigation` and `--sources` can override the input files for experimentation.