swift Documentation

The Swift Programming Language

70,247 stars Swift Swift 1 file · ~5,435 tokens
RAW Doc

1. Project Overview & Quickstart (swiftlang/swift)

File: README.md

Swift Programming Language

Welcome to Swift

Swift is a high-performance system programming language. It has a clean
and modern syntax, offers seamless access to existing C and Objective-C code
and frameworks, and is memory-safe by default.

Although inspired by Objective-C and many other languages, Swift is not itself a
C-derived language. As a complete and independent language, Swift packages core
features like flow control, data structures, and functions, with high-level
constructs like objects, protocols, closures, and generics. Swift embraces
modules, eliminating the need for headers and the code duplication they entail.

To learn more about using the language, visit swift.org.
To learn more about the compiler's internal design, see the
documentation index.

Contributing to Swift

Contributions to Swift are welcomed and encouraged! Please see the
Contributing to Swift guide.

Before submitting the pull request, please make sure you have tested your
changes
and that they follow the Swift project guidelines for contributing
code.

To be a truly great community, Swift.org needs to welcome
developers from all walks of life, with different backgrounds, and with a wide
range of experience. A diverse and friendly community will have more great
ideas, more unique perspectives, and produce more great code. We will work
diligently to make the Swift 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.

Getting Started

If you are interested in:

We also have an FAQ that answers common questions.

Swift Toolchains

Building

Swift toolchains are created using the script
build-toolchain. This
script is used by swift.org's CI to produce snapshots and can allow for one to
locally reproduce such builds for development or distribution purposes. A typical
invocation looks like the following:

sh
$ ./swift/utils/build-toolchain $BUNDLE_PREFIX

where $BUNDLE_PREFIX is a string that will be prepended to the build
date to give the bundle identifier of the toolchain's Info.plist. For
instance, if $BUNDLE_PREFIX was com.example, the toolchain
produced will have the bundle identifier com.example.YYYYMMDD. It
will be created in the directory you run the script with a filename
of the form: swift-LOCAL-YYYY-MM-DD-a-osx.tar.gz.

Beyond building the toolchain, build-toolchain also supports the
following (non-exhaustive) set of useful options:

  • --dry-run: Perform a dry run build. This is off by default.
  • --test: Test the toolchain after it has been compiled. This is off by default.
  • --distcc: Use distcc to speed up the build by distributing the C++ part of
    the swift build. This is off by default.
  • --sccache: Use sccache to speed up subsequent builds of the compiler by
    caching more C++ build artifacts. This is off by default.

More options may be added over time. Please pass --help to
build-toolchain to see the full set of options.

Installing into Xcode

On macOS if one wants to install such a toolchain into Xcode:

  1. Untar and copy the toolchain to one of /Library/Developer/Toolchains/ or
    ~/Library/Developer/Toolchains/. E.g.:
sh
$ sudo tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx.tar.gz -C /
  $ tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx.tar.gz -C ~/

The script also generates an archive containing debug symbols which
can be installed over the main archive allowing symbolication of any
compiler crashes.

sh
$ sudo tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx-symbols.tar.gz -C /
  $ tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx-symbols.tar.gz -C ~/
  1. Specify the local toolchain for Xcode's use via Xcode->Toolchains.

Build Failures

Try the suggestions in
Troubleshooting build issues.

Make sure you are using the
correct release
of Xcode.

If you have changed Xcode versions but still encounter errors that appear to
be related to the Xcode version, try passing --clean to build-script.

When a new version of Xcode is released, you can update your build without
recompiling the entire project by passing --reconfigure to build-script.

File: docs/README.md

Documentation Index

This page contains a curated index of the documentation found in the Swift
compiler repository.

Sometimes documentation is not enough.
Especially if you are a new contributor, you might run into roadblocks
which are not addressed by the existing documentation.
If you are stuck, please use the development category on the Swift forums
to ask for help!

Building the Toolchain

  • GettingStarted.md:
    Describes how to set up a working Swift development environment
    for Linux and macOS, and get an edit-build-test-debug loop going.
  • Building for Android:
    • Android.md:
      How to run some simple programs and the Swift test suite on an Android device.
    • AndroidBuild.md:
      How to build the Swift SDK for Android on Windows.
  • Building for Windows:
  • Building for OpenBSD:
    • OpenBSD.md:
      Overview of specific steps for building on OpenBSD.

Contributing

  • FirstPullRequest.md:
    Describes how to submit your first pull request. This is the place to start
    if you're new to the project!
  • Branches.md:
    Describes how different branches are setup and what the automerger does.
  • ContinuousIntegration.md:
    Describes the continuous integration setup, including the @swift_ci bot.
  • DebuggingTheCompiler.md:
    Describes a variety of techniques for debugging.
  • FAQ.md:
    Answers "How do I do X?" for a variety of common tasks.
  • Lexicon.md:
    Canonical reference for terminology used throughout the project.
  • Testing.md:
    Information about running and developing tests in the compiler's test suite.

Reference Guides

  • Backtracing.rst:
    Describes Swift's backtracing and crash reporting support.
  • CompilerPerformance.md:
    Thoroughly discusses different ways of measuring compiler performance
    and common pitfalls.
  • Generics/: "Compiling Swift Generics", a book about
    the implementation of parameteric polymorphism in the Swift compiler.
    Also covers the compilation pipeline, request evaluator, and type system in
    general.
  • LibraryEvolution.rst:
    Specifies what changes can be made without breaking binary compatibility.
  • RequestEvaluator.md:
    Describes the request evaluator architecture, which is used for
    lazy type-checking and efficient caching.
  • SIL/: Documentation about SIL, the Swift intermediate language.
  • TypeChecker.md:
    Provides an overview of the expression type checker.
  • UnderscoredAttributes.md:
    Documents semantics for underscored (unstable) attributes in the language.

The Swift ABI

  • CallingConventionSummary.rst:
    A concise summary of the calling conventions used for C/C++, Objective-C
    and Swift on Apple platforms. Contains references to source documents,
    where further detail is required.
  • CallingConvention.rst:
    This whitepaper discusses the Swift calling convention (high-level semantics;
    ownership transfer; physical representation; function signature lowering).
  • KeyPaths.md:
    Describes the layout of key path objects (instantiated by the runtime,
    and therefore not strictly ABI).
    TODO: The layout of key path patterns (emitted by the compiler,
    to represent key path literals) isn't documented yet.
  • Mangling.rst:
    Describes the stable mangling scheme, which produces unique symbols for
    ABI-public declarations.
  • TypeLayout.rst:
    Describes the algorithms/strategies for fragile struct and tuple layout;
    class layout; fragile enum layout; and existential container layout.
  • TypeMetadata.rst:
    Describes the fields, values, and layout of metadata records, which can be
    used (by reflection and debugger tools) to discover information about types.

SIL Optimizer

  • OptimizerDesign.md:
    Describes the design of the optimizer pipeline.
  • HighLevelSILOptimizations.rst:
    Describes how the optimizer understands the semantics of high-level
    operations on currency data types and
    optimizes accordingly.
    Includes a thorough discussion of the @_semantics attribute.
  • HowToUpdateDebugInfo.md: A guide for SIL
    optimization pass authors for how to properly update debug info in SIL
    program transformations.
  • OptimizerCountersAnalysis.md:
    TODO: Consider breaking up into a how-to guide
    on dumping and analyzing the counters
    and an explanation for the counter collection system.
  • TransparentAttr.md:
    Documents the semantics of the @_transparent attribute.

Swift Driver

  • Driver.md:
    Provides an overview of the driver, compilation model, and the compiler's
    command-line options. Useful for integration into build systems other than
    SwiftPM or Xcode.

  • DriverInternals.md:
    Provides a bird's eye view of the driver's implementation.

  • DriverParseableOutput.md:
    Describes the output format of the driver's -parseable-output flag,
    which is suitable for consumption by editors and IDEs.

  • DependencyAnalysis.md:
    Describes different kinds of dependencies across files in the same module,
    important for understanding incremental builds.

Objective-C Interop

Rationales and Manifestos

Uncategorized

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

File: README.md

Welcome to the Swift Project Documentation

This repository hosts multiple DocC catalogs that provide the source location for documentation content for the Swift project, hosted at 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.

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.

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

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

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/latest/documentation/

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

Note: Ensure that you have a version of Swift available that will build the
content that you point at in sources.json. For latest development tree builds,
that typically requires either the latest Xcode beta or a Swift nightly development
build to support Swift, SwiftPM, swift-testing, and other core projects.

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.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →