Swift reference

Toolchain and command line¶

A Swift toolchain is a single download containing the compiler, standard library, package manager, debugger, formatter, language server, and documentation compiler. On macOS it is embedded in Xcode and also available standalone; on Linux and Windows it is installed from swift.org or through swiftly, the official toolchain manager, which installs several toolchains side by side and selects between them per project.

The commands that make up a Swift installation.

Source: Swift.org toolchain documentation and swift --help for the current release.

The compiler flags that appear most often in real build configurations.

Source: swiftc -help and the Swift compiler documentation. Package manifests set most of these through swiftSettings rather than by passing flags directly.

Back to top

Swift Package Manager¶

SwiftPM is part of the toolchain, not a separate project. A package is a directory with a Package.swift manifest, which is itself a Swift program executed by the package manager: the first line is a swift-tools-version comment that tells SwiftPM which manifest API to compile it against, and therefore also sets the default language mode.

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "Atlas",
    platforms: [.macOS(.v14), .iOS(.v17)],
    products: [
        .library(name: "AtlasCore", targets: ["AtlasCore"]),
        .executable(name: "atlas", targets: ["AtlasCLI"]),
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-argument-parser", from: "1.5.0"),
        .package(url: "https://github.com/apple/swift-log", .upToNextMinor(from: "1.6.0")),
    ],
    targets: [
        .target(
            name: "AtlasCore",
            dependencies: [.product(name: "Logging", package: "swift-log")],
            swiftSettings: [
                .swiftLanguageMode(.v6),
                .enableUpcomingFeature("ExistentialAny"),
                .define("ATLAS_INTERNAL_CHECKS", .when(configuration: .debug)),
            ]
        ),
        .executableTarget(
            name: "AtlasCLI",
            dependencies: [
                "AtlasCore",
                .product(name: "ArgumentParser", package: "swift-argument-parser"),
            ]
        ),
        .testTarget(name: "AtlasCoreTests", dependencies: ["AtlasCore"]),
    ],
    swiftLanguageModes: [.v6]
)

The seven target types.

Source: the PackageDescription API reference for tools version 6. Conventional layout means most packages need no explicit path: arguments.

Dependency resolution follows semantic versioning and records exact resolved versions in Package.resolved, which is committed. Version requirements are expressed as from: (up to the next major), .upToNextMinor(from:), an exact version, a branch, or a revision; the last two are accepted for a root package but rejected in a package that is itself a dependency, which prevents unpinned transitive requirements.

Back to top

Testing¶

Two frameworks coexist. XCTest is the older, Objective-C-derived framework; Swift Testing, introduced with Swift 6, is written for the modern language and uses macros so that a single #expect reports the values of every sub-expression in a failed assertion. Both run under swift test and can live in the same target, which is what makes incremental adoption practical.

The two frameworks compared on the points that affect how tests are written.

Source: the Swift Testing documentation and the XCTest reference. Swift Testing does not replace XCTest for UI and performance testing on Apple platforms, which remain XCTest-only.

import Testing
@testable import AtlasCore

@Suite("Version parsing")
struct VersionParsingTests {

    @Test("Accepts well-formed semantic versions",
          arguments: ["6.3.3", "1.0.0", "10.20.30"])
    func parsesValid(_ input: String) throws {
        let version = try #require(Version(input))
        #expect(version.description == input)
    }

    @Test(.tags(.regression))
    func rejectsTrailingText() {
        #expect(Version("6.3.3-beta") == nil)
    }
}

Back to top

Attribute reference¶

Attributes are written with a leading @ before the declaration or type they modify. They fall into three positions: declaration attributes, type attributes, and one switch-case attribute (@unknown, which future-proofs a switch over a non-frozen enumeration).

Declaration attributes, grouped by what they are for rather than alphabetically.

Source: The Swift Programming Language, Attributes chapter. Interface Builder attributes (@IBAction, @IBOutlet, @IBDesignable, @IBInspectable) and the deprecated @UIApplicationMain/@NSApplicationMain are omitted.

The four type attributes.

Type attributes appear on a type, most often a function type in a parameter position.

Back to top

Declaration modifiers¶

Modifiers are keywords or context-sensitive keywords written between a declaration's attributes and the keyword that introduces it. Access-level modifiers are covered in the Access control section of the language article; each also accepts a (set) argument to give a setter narrower access than its getter.

Non-access modifiers.

Source: The Swift Programming Language, Declarations → Declaration Modifiers.

Back to top

Operators and precedence¶

Swift has no fixed operator table in the grammar. Operators are library declarations that name a precedence group, and precedence groups declare their relations to one another with higherThan and lowerThan. The hierarchy need only be partially ordered, so two groups may have no defined relation, in which case their operators cannot appear adjacent without parentheses.

The eleven precedence groups used by the standard library.

Source: Apple Developer, Operator Declarations. Listed in decreasing order of precedence. Prefix operators (! ~ + - ..< ...) and postfix ... bind more tightly than any infix operator.

// Declaring a new operator: fixity declaration, precedence group, implementation.
infix operator |>: ForwardPipePrecedence

precedencegroup ForwardPipePrecedence {
    associativity: left
    higherThan: AssignmentPrecedence
    lowerThan: TernaryPrecedence
}

func |> <A, B>(value: A, transform: (A) -> B) -> B { transform(value) }

let shortNames = names |> { $0.filter { $0.count < 6 } }

// Overloading an existing operator for your own type.
extension Rectangle {
    static func * (lhs: Rectangle, rhs: Double) -> Rectangle {
        Rectangle(width: lhs.width * rhs, height: lhs.height * rhs)
    }
}

Back to top

Standard library map¶

The standard library is written in Swift and is available to every program without an import. It sits on a C++ runtime that implements the dynamic parts of the language — type metadata, generic instantiation, dynamic casting, reflection, and reference counting — and, on Apple platforms, on SDK overlays that adapt Objective-C frameworks to Swift conventions.

The protocols a type most often adopts, and what each buys.

Sources: Apple Developer standard library reference and the Protocols chapter. “Synthesised” means the compiler writes the implementation when the declaration lists the conformance.

Beyond the standard library, a set of packages maintained by the Swift project is treated as quasi-standard: swift-collections (deque, ordered set and dictionary, heap), swift-algorithms, swift-numerics, swift-argument-parser, swift-log, swift-nio, and swift-syntax. The Standard Library Preview package additionally vends accepted evolution proposals as standalone modules before they ship in the library itself.

Back to top

API design guidelines¶

Swift's naming conventions are published as normative guidelines by the Swift project, and the standard library follows them exactly. They are grammatical rather than typographical: the aim is that a call site reads as an English phrase, which is why argument labels exist as a separate concept from parameter names.

The rules that decide most naming arguments.

Source: Swift.org, API Design Guidelines. Reproduced in condensed form; the full document includes worked counter-examples for each rule.

Naming mutating and nonmutating method pairs.

Mutating and nonmutating pairs must be named consistently, so that a reader can predict one from the other.

// Reads as a phrase at the point of use.
let foreground = Color(red: 32, green: 64, blue: 128)
let newPart = factory.makeWidget(gears: 42, spindles: 14)
employees.remove(at: x)                  // Not remove(x) - ambiguous with remove(element)
allViews.remove(cancelButton)            // No label: the argument is the thing being removed

// Grammatical continuity forced into the first argument reads worse, not better.
// let foreground = Color(havingRGBValuesRed: 32, green: 64, andBlue: 128)

// Documentation comment: a summary fragment first, then parameters and returns.
/// Returns a view of `self` containing the same elements in reverse order.
///
/// - Parameter preservingIndices: Whether index positions are retained.
/// - Returns: A lazily evaluated reversed collection.
/// - Complexity: O(1).
func reversed(preservingIndices: Bool = false) -> ReverseCollection<Self>

Back to top

Documentation comments and DocC¶

Documentation comments use /// or /** */ and are written in Swift's dialect of Markdown. DocC, the documentation compiler in the toolchain, reads them together with standalone article files and tutorial files to produce a documentation archive that can be hosted statically or read inside Xcode. Because the doc comments are compiled rather than scraped, a reference to a symbol that no longer exists is a build warning.

/// A logger that records temperature measurements for one location.
///
/// Create a logger with an initial measurement, then record further readings
/// with ``update(with:)``. The maximum is maintained incrementally:
///
/// ```swift
/// let logger = TemperatureLogger(label: "Outdoors", measurement: 25)
/// await logger.update(with: 31)
/// ```
///
/// - Note: Access from outside the actor is asynchronous.
/// - SeeAlso: ``Measurement``
public actor TemperatureLogger { }

The callouts DocC recognises include - Parameter, - Parameters, - Returns, - Throws, - Complexity, - Precondition, - Note, - Warning, and - SeeAlso. Double-backtick syntax (``symbol``) creates a checked link to another symbol. Documentation is built with swift package generate-documentation and previewed with swift package --disable-sandbox preview-documentation.

Back to top

Compilation and code generation¶

Swift does not go straight from source to LLVM IR. It introduces its own intermediate representation, SIL (Swift Intermediate Language), which is high-level enough to still know about generics, protocol conformances, ownership, and reference counting. Most of what distinguishes Swift's optimiser from a generic LLVM front end happens at that level: generic specialisation, devirtualisation of protocol witnesses, ARC traffic elimination, copy-on-write and exclusivity checking, and closure specialisation.

The seven costs that show up most often in Swift profiling.

Sources: Swift compiler documentation and the performance discussions in the Swift forums. Every row is a trade-off the language makes deliberately, not a defect.

Back to top

Swift Evolution¶

Every change to the language goes through a public process. A pitch is posted to the Swift forums for informal discussion; if it gains traction, it is written up as a proposal in the swiftlang/swift-evolution repository with an SE-NNNN number and a reference implementation. A language steering group schedules a review period, typically one to two weeks, and then publishes an acceptance, rejection, or return-for-revision with written rationale.

The process has a specific consequence for developers: a language change almost never arrives unannounced. A behaviour that will be the default in a future language mode is available first as an upcoming feature flag, so a codebase can adopt it, and be diagnosed against it, one release before it becomes mandatory. The Release model section of the language article describes how those flags combine with language modes.

Governance is distributed across workgroups — language steering, core team, and topic-specific groups for the platform ports (Android, Windows), the server ecosystem, C++ interoperability, documentation, and website. Each publishes its charter and meeting notes on swift.org.

Back to top

Sources¶