Skip to content

Instantly share code, notes, and snippets.



Last active Feb 26, 2021
What would you like to do?

Provide documentation for various Swift internals


Swift is a very successful combination of a compiled language with numerous high-level features. This means that, on the one hand, the behaviour of the code is very predictable, as there’s only one widely used Swift compiler. On the other hand, many such high-level features don’t directly translate to the present hardware’s instructions and as such require substantial language runtime and compiler magic to be able to work.

Unfortunately, there is currently little to no way for a typical language user — that is, anybody who isn’t familiar with the compiler’s implementation — to get acquainted with various implications of using most of the features of Swift. One either needs to familiarise themselves with different compilation stages and representations (SIL, LLVM IR) or rely on scarce, topical information present on the Swift forums or in videos from the WWDC or the LLVM conferences. This not only contributes to users having a harder time debugging or improving their code, but also has become a reason for various misconceptions about the language to get widespread.

A unified, verified source of lower-level information is thus required to foster a community that is able to use the language to its full potential. Because Swift also recommends itself as an introductory language, the documentation should provide a form of disclosure not only of language features per se, but also of their impact on the generated machine code to develop a holistic understanding of the programming environment.

We propose to greatly expand the official documentation hosted on by providing a curated walkthrough of the most used language features.

Topics covered

It will be generally assumed that Swift’s runtime is intentionally opaque and subject to change — in fact, Swift does a very great job of hiding the implementation complexity of its most powerful features, such as generics or protocol types. However, given the ABI stability on Apple’s platforms, we can say with a fair confidence that most details about discussed features won’t drastically deviate from their current implementations in the foreseeable future. We shall thus select the features that are unlikely to be altered and provide a deeper look into their inner workings.

The following list is a compilation of such topics, loosely organised in order of their prevalence (note especially that this sequence resembles how the high-level counterparts are introduced in the Swift language guide):

  • calling conventions (method, closure, thin)
  • type layout, tagged unions, thick function pointers
  • stack vs. heap allocation and ARC; value capturing
  • weak and unowned references, side tables
  • implementations of accessors and property observers
  • vtables and the concept of dynamic dispatch
  • the concept of ownership and definitive initialization/deinitialization
  • type metadata, runtime generation of such
  • generics, monomorphisation of functions and reabstraction thunks
  • existential containers
  • witness tables

— and really anything else our souls desire to document.

Beyond that, the project will also provide some introductory chapters discussing preliminary concepts such as ABI, calling conventions, metadata and similar, since we don’t want to assume any familiarity with such concepts.


We respectfully do not aim to provide any discussion of Swift’s interoperability with Objective-C (at least in the context of GSoC), as this could dilute the scope and introduce unnecessary minutia.

We shall also refrain from discussing features that are (at the moment of writing) obviously marked as experimental or internal, such as coroutines or ownership markers.

We also do not want to discuss obviously platform-specific implications such as endianness because these are both unlikely to matter and are unspecific to Swift in the first place.

The provided text shall adhere to an educational style: it is not intended to replace the very technical documentation present in the compiler repository.


Given the specifics of the project, it doesn’t necessarily make sense to provide a strict timeline of writing the chapters, as most of them can be freely reordered without affecting the overall text. Nevertheless, we expect to be able to cover roughly one chapter per week (see “Topics covered” above).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment