This file defines several terms used by the Swift compiler and standard library source code, tests, and commit messages. See also the LLVM lexicon.
The unsubstituted generic type of a property or function parameter, which sets constraints on its representation in memory. For example, given the following definitions:
struct Foo<T> { var value: T // Foo.value has abstraction pattern <T> T } struct Bar<T, U> { var value: (T) -> U // Bar.value has abstraction pattern <T, U> (T) -> U } struct Bas { var value: (Int) -> String // Bas.value has abstraction pattern (Int) -> String } let transform: (Int) -> String = { "\($0)" } let foo = Foo<(Int) -> String>(value: transform) let bar = Bar<Int, String>(value: transform) let bas = Bas(value: transform)
although foo.value, bar.value, and bas.value all have the same function type (Int) -> String, they have different abstraction patterns. Because a value of type Foo or Bar may be used in a generic context and invoke value with a parameter or result type of unknown size, the compiler has to pick a more conservative representation for the closure that uses indirect argument passing, whereas Bas.value has a fully concrete closure type so can always use a more specialized direct register-based calling convention. The compiler transparently introduces reabstraction conversions when a value is used with a different abstraction pattern. (This is where the infamous “reabstraction thunk helpers” sometimes seen in Swift backtraces come from.)
A placeholder for a generic parameter or an associated type within a generic context. Sometimes known as a “rigid type variable” in formal CS literature. Directly stores its conforming protocols and nested archetypes, if any.
“Abstract syntax tree”, although in practice it's more of a directed graph. A parsed representation of code used by a compiler.
Serialized LLVM IR.
Apple term for “the person assigned to watch CI this week”.
SIL after the mandatory passes have run. This can be used as input to IRGen to generate LLVM IR or object files.
A unique representation of a type, with any sugar removed. These can usually be directly compared to test whether two types are the same; the exception is when generics get involved. In this case you'll need a generic environment. Contrast with sugared type.
A kind of dependency edge relevant to the incremental name tracking subsystem. A cascading dependency (as opposed to a private dependency requires the Swift driver to transitively consider dependency edges in the file that defines the used name when incremental compilation is enabled. A cascading dependency is much safer to produce than its private counterpart, but it comes at the cost of increased usage of compilation resources - even if those resources are being wasted on rebuilding a file that didn't actually require rebuilding. See DependencyAnalysis.md.
The part of the compiler that reads C and Objective-C declarations and exposes them as Swift. Essentially contains a small instance of Clang running inside the Swift compiler, which is also used during IRGen.
A construct detailing how a particular type conforms to a particular protocol. Represented in the compiler by the ProtocolConformance type at the AST level. See also witness table.
print(6 * 9), the contextual type of the expression 6 * 9 is Any.An edge in a control flow graph where the destination has multiple predecessors and the source has multiple successors.
Informal term for a protocol requirement that has a default implementation, i.e. one that conforming types don't have to implement but have the option to “customize”.
Any request that uses a matching dependency source to write dependency edges into the referenced name trackers. For example, a request that performs direct lookup will write the name being looked up into the name tracker associated with the file that issued the lookup request. The request evaluator automatically determines the appropriate tracker for a dependency sink to write into based on the current active dependency source request.
Any request that defines a scope under which reference dependencies may be registered. For example, a request to type check an entire file is a dependency source. Dependency sources are automatically managed by the request evaluator as request evaluation proceeds. Dependency sources provide one half of the necessary information to complete a full dependency edge. The other half is provided by corresponding dependency sink requests.
The feature that no uninitialized variables, constants, or properties will be read by a program, or the analysis pass that operates on SIL to guarantee this. This was discussed on Apple's Swift blog.
“Do not merge”. Placed in PR titles where discussion or analysis is still ongoing.
From “duplicate”. As a noun, refers to another filed issue that describes the same bug (“I have a dup of this”); as a verb, the act of marking a bug as a duplicate (“Please dup this to the underlying issue”). Sometimes written “dupe”. Pronounced the same way as the first syllable of “duplicate”, which for most American English speakers is “doop”.
A value whose type is a protocol composition (including a single protocol and zero protocols; the latter is the Any type).
A module build where all dependency modules (including Clang modules) are passed to the compiler explicitly by an external build system, including any modules in caches. See also: implicit module build and fast dependency scanner.
A Swift compiler mode that scans a Swift module for import declarations and resolves which modules will be loaded. It is based on the clang-scan-deps library within Clang, for (Objective-)C modules, but is extended to also understand textual Swift modules (.swiftinterface files).
The fast dependency scanner outputs a graph of compilation steps which can be used by a build system to schedule explicit module builds.
Describes a type or function where making changes will break binary compatibility. See LibraryEvolution.rst.
Describes contributions which fix code that is not executed (such as in a manifesto or README) and written text (correcting typos and grammatical errors).
Provides context for interpreting a type that may have generic parameters in it. Generic parameter types are normally just represented as “first generic parameter in the outermost context” (or similar), so it's up to the generic environment to note that that type must be a Collection. (Another way of looking at it is that the generic environment connects interface types with contextual types).
A representation of all generic parameters and their requirements. Like types, generic signatures can be canonicalized to be compared directly.
“if and only if”. This term comes from mathematics.
A module build where the compiler is free to transparently build dependent modules (including Clang modules), and access modules in different caches as necessary. For example, if a textual Swift module (.swiftinterface file) for a dependency does not have a corresponding binary Swift module (.swiftmodulea file), the compiler may transparently build a binary Swift module from the textual one as a cache for future compiler jobs, without involving any external build system that invoked the compiler. See also: explicit module build.
The type of a value or declaration outside its generic context. These types are written using “formal” generic types, which only have meaning when combined with a particular generic declaration's “generic signature”. Unlike contextual types, interface types store conformances and requirements in the generic signature and not in the types themselves. They can be compared across declarations but cannot be used directly from within the context.
A pattern that always matches. These patterns either bind to a variable or perform structural modification, e.x.:
case _:.case let x:.case (_, _):.A type like Optional, but it implicitly converts to its wrapped type. If the value is nil during such a conversion, the program traps just as it would when a normal Optional is force-unwrapped. IUOs implicitly convert to and from normal Optionals with the same wrapped type.
The accepted wisdom that implementation files (.cpp, .c, .m, .mm) should explicitly #include or #import the headers they use. Doing so prevents compilation errors when header files are included in a different order, or when header files are modified to use forward declarations instead of direct includes.
“Looks good to me.” Used in code review to indicate approval with no further comments.
See IR.
Pronounced “L-value”. Refers to an expression that can be assigned to or passed inout. The term originally comes from C; the “L” refers to the “l”eft side of an assignment operator. See also rvalue.
The module for the file or files currently being compiled.
Transformations over SIL that run immediately after SIL generation. Once all mandatory passes have run (and if no errors are found), the SIL is considered canonical.
The type of a value representing a type. Greg Parker has a good explanation of Objective-C's “metaclasses”; because Swift has types that are not classes, a more general term is used.
We also sometimes refer to a value representing a type as a “metatype object” or just “metatype”, usually within low-level contexts like IRGen and LLDB. This is technically incorrect (it's just a “type object”), but the malapropism happened early in the project and has stuck around.
A type that conforms to a particular protocol. Sometimes “concrete model”. Example: “Array and Set are both models of CollectionType”.
Has many uses in the Swift world. We may want to rename some of them. #1 and #2 are the most common.
import declaration brings modules into scope. Represented as ModuleDecl in the compiler.Clang's cache directory for precompiled module files. As cache files, these are not forward-compatible, and so cannot be loaded by different versions of Clang (or programs using Clang, like the Swift compiler). Normally this is fine, but occasionally a development compiler will not have proper version information and may try to load older module files, resulting in crashes in clang::ASTReader.
“No functionality change.” Written in commit messages that are intended to have no change on the compiler or library's behavior, though for some this refers to having the same implementation and for others merely an equivalent one. “NFC” is typically used to explain why a patch has no included testcase, since the Swift project requires testcases for all patches that change functionality.
An existential value with its dynamic type pulled out, so that the compiler can do something with it.
A wrapper library that is implicitly imported “on top of” another library. It contains an @_exported import of the underlying library, but it augments it with additional APIs which, for one reason or another, are not included in the underlying library directly.
There are two kinds of overlays:
A “clang overlay” (the older kind, so it‘s often just called an “overlay”) is a Swift library that adds Swift-specific functionality to a C-family library or framework. Clang overlays are used with system libraries that cannot be modified to add Swift features. A clang overlay has the same module name as the underlying library and can do a few special things that normal modules can’t, like adding required initializers to classes. If a module has a clang overlay, the Clang Importer will always load it unless it is actually compiling the overlay itself. Apple has a number of clang overlays for its own SDKs in stdlib/public/Darwin/.
A “separately-imported overlay” is a separate module with its own name. Unlike a clang overlay, it can be imported in some SourceFiles and not others. When the compiler processes import declarations, it determines which separately-imported overlays need to be imported and then adds them to the list of imports for that file; name lookup also knows to look through the overlay when it looks for declarations in the underlying module. Separately-imported overlays are used to implement the “cross-import overlays” feature, which is used to augment a module with additional functionality when it is imported alongside another module.
The type in which a given declaration is nested. For example:
struct Outer { struct Inner { } }
Outer is the parent type of Inner.
Note that the terms “parent type” and “superclass” refer to completely different concepts.
Precompiled header, a type of file ending in .pch. A precompiled header is like a precompiled module, in the sense that it's the same file format and is just a cache file produced by clang and read by clang::ASTReader. The difference is that PCH files are not “modular”: they do not correspond to a named module, and cannot be read in any order or imported by module-name; rather they must be the first file parsed by the compiler. PCHs are used only to accelerate the process of reading C/C++/Objective-C headers, such as the bridging headers read in by the -import-objc-header command-line flag to swiftc.
The file currently being compiled, as opposed to the other files that are only needed for context. See also Whole-Module Optimization.
A kind of dependency edge relevant to the incremental name tracking subsystem. A private dependency (as opposed to a cascading dependency) declares a dependency edge from one file to a name referenced in that file that does not require further transitive evaluation of dependency edges by the Swift driver. Private dependencies are therefore cheaper than cascading dependencies, but must be used with the utmost care or dependent files will fail to rebuild and the result will most certainly be a miscompile. See DependencyAnalysis.
“Quality of implementation.” The term is meant to describe not how well-engineered a particular implementation is, but how much value it provides to users beyond a sort of minimum expectation. Good diagnostics are a matter of QoI, as is good unoptimized performance. For example, a comment like “FIXME: QoI could be improved here” is suggesting that there's some sort of non-mandatory work that could be done that would improve the behavior of the compiler--it is not just a general statement that the code needs to be improved.
It's possible that this term was originally “quality of life”, written as “Qol”, referring to the experience of end users. At some point along its history, the lowercase “L” was misinterpreted as an uppercase “i”, and a new meaning derived. Swift inherited this term from LLVM, which got it from GCC.
Apple's bug-tracking system, or an issue reported on that system.
SIL just after being generated, not yet in a form that can be used for IR generation. See mandatory passes.
An implicit representation change that occurs when a value is used with a different abstraction pattern from its current representation.
A pattern that may not always match. These include patterns such as:
case let x as String:.case .none:.case foo():.Describes a type or function where making certain changes will not break binary compatibility. See LibraryEvolution.rst.
Code that implements a language‘s dynamic features that aren’t just compiled down to plain instructions. For example, Swift's runtime library includes support for dynamic casting and for the Mirror-based reflection.
Pronounced “R-value”. Represents an expression that can be used as a value; in Swift this is nearly every expression, so we don't use the term very often. The term originally comes from C; the “R” refers to the “r”ight side of an assignment operator. Contrast with lvalue.
The parsing mode that allows top-level imperative code in a source file.
Short for ‘Semantic Analysis’, the compiler pass that performs type checking, validation, and expression rewriting before SILGen.
“Swift Intermediate Language”. A high-level IR used by the Swift compiler for flow-sensitive diagnostics, optimization, and LLVM IR generation.
An issue reported on bugs.swift.org. A backronym for “Swift Report”; really the name is derived from LLVM‘s idiomatic use of “PR” (“Problem Report”) for its bugs. We didn’t go with “PR” for Swift because we wanted to be able to unambiguously reference LLVM bugs.
“Standard library”. Sometimes this just means the “Swift” module (also known as “swiftCore”); sometimes it means everything in the stdlib/ directory. Pronounced “stid-lib” or “ess-tee-dee-lib”.
A type that may have been written in a more convenient way, using special language syntax or a typealias. (For example, Int? is the sugared form of Optional<Int>.) Sugared types preserve information about the form and use of the type even though the behavior usually does not change (except for things like access control). Contrast with canonical type.
In the Swift compiler, a synthesized function whose only purpose is to perform some kind of adjustment in order to call another function. For example, Objective-C and Swift have different calling conventions, so the Swift compiler generates a thunk for use in Objective-C that calls through to the real Swift implementation.
A deterministic runtime failure. Can be used as both as a noun (“Using an out-of-bounds index on an Array results in a trap”) and a verb (“Force-unwrapping a nil Optional will trap”).
The runtime representation of a type, and everything you can do with it. Like a Class in Objective-C, but for any type.
A Unified Symbol Resolution (USR) is a string that identifies a particular entity (function, class, variable, etc.) within a program. USRs can be compared across translation units to determine, e.g., when references in one translation refer to an entity defined in another translation unit.
A runtime structure that describes how to do basic operations on an unknown value, like “assign”, “copy”, and “destroy”. (For example, does copying this value require any retains?)
Only conceptually related to a witness table.
A map attached to a class of which implementation to use for each overridable method in the class. Unlike an Objective-C method table, vtable keys are just offsets, making lookup much simpler at the cost of dynamism and duplicated information about non-overridden methods.
“Work-in-progress”. Placed in PR titles to indicate that the PR is not ready for review or merging.
The value or type that satisfies a protocol requirement.
The SIL (and runtime) representation of a conformance; essentially a vtable but for a protocol instead of a class.
Only conceptually related to a value witness table.
A compilation mode where all files in a module are compiled in a single process. In this mode there is no primary file; all files are parsed, type-checked, and optimized together at the SIL level. LLVM optimization and object file generation may happen all together or in separate threads.