Skip to content

Commit 440cd0b

Browse files
varungandhi-applevarungandhi-apple
authored
[docs] Add documentation describing external resources. (swiftlang#32584)
1 parent ff99d65 commit 440cd0b

File tree

2 files changed

+180
-6
lines changed

2 files changed

+180
-6
lines changed

‎docs/ExternalResources.md

+176
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# External Resources
2+
3+
The official [Swift blog](https://swift.org/blog/) has a lot of useful
4+
information, such as [how runtime reflection works][mirror-post] and how the
5+
compiler's [new diagnostic architecture][diagnostic-arch-post] is structured.
6+
7+
[mirror-post]: https://swift.org/blog/how-mirror-works/
8+
[diagnostic-arch-post]: https://swift.org/blog/new-diagnostic-arch-overview/
9+
10+
This page lists some external resources apart from the Swift blog which may be
11+
helpful for people interested in contributing to Swift. The resources are listed
12+
in reverse-chronological order and organized by topic.
13+
14+
<!--
15+
Some resources don't fall cleanly into one topic bucket or another; in such a
16+
case we break the tie arbitrarily.
17+
-->
18+
19+
<!--
20+
The textual descriptions should be written in a way that makes it clear
21+
which topics are discussed, and what a potential contributor to Swift
22+
will gain from it. This is usually different from the talk's abstract.
23+
-->
24+
25+
## Contributing Guides and Tips
26+
27+
- [Steps for first PR and asking questions][] by Varun Gandhi (Swift forum
28+
comment, Dec 2019).
29+
- [Contributing to Swift for the First Time][] by Robert Pieta (talk, Jun 2019):
30+
This talk describes Robert's experience contributing to
31+
`swift-corelibs-foundation` and later `swift`, providing a step-by-step guide
32+
for new contributors to get their feet wet.
33+
- [Contributing to Swift compiler][] by Yusuke Kita (lightning talk, Apr 2019).
34+
- Contributing to Swift ([Part 1][Contributing to Swift - Part 1],
35+
[Part 2][Contributing to Swift - Part 2]) by Suyash Srijan (blog post series,
36+
Dec 2018).
37+
- [Setting up a compile-edit-test cycle][] by Robert Widmann (Swift forum
38+
comment, May 2018)
39+
- [Becoming an Effective Contributor to Swift][] by Harlan Haskins and Robert
40+
Widmann (talk, Apr 2018): Covers the following topics:
41+
- The organization of different projects part of the Swift monorepo.
42+
- How to set up an environment for building Swift.
43+
- Common utilities and compiler flags for debugging different stages.
44+
- Common build configurations.
45+
- Tips and tricks for testing: early exiting, filtering tests,
46+
testing Swift and Objective-C together, using `PrettyStackTrace`.
47+
- A live demo fixing a crash:
48+
- Copying program arguments into Xcode for debugging.
49+
- Using `dump()` for print debugging.
50+
- [Getting Started with Swift Compiler Development][] by Brian Gesiak (blog post
51+
series, Aug 2017 - Jun 2018)
52+
- [Contributing to Open Source Swift][] by Jesse Squires (talk, Mar 2016):
53+
Covers the following topics:
54+
- The overall compiler pipeline.
55+
- The organization of different projects part of the Swift monorepo,
56+
including some "difficulty levels" for different projects.
57+
- Tips for contributing effectively.
58+
59+
[Steps for first PR and asking questions]:
60+
https://forums.swift.org/t/getting-started-with-swift-compiler-development/31502/2
61+
[Contributing to Swift for the First Time]: https://youtu.be/51j7TrFNKiA
62+
[Contributing to Swift compiler]: https://youtu.be/HAXJsgYniqE
63+
[Contributing to Swift - Part 1]: https://medium.com/kinandcartacreated/contributing-to-swift-part-1-ea19108a2a54
64+
[Contributing to Swift - Part 2]:
65+
https://medium.com/kinandcartacreated/contributing-to-swift-part-2-efebcf7b6c93
66+
[Setting up a compile-edit-test cycle]: https://forums.swift.org/t/need-a-workflow-advice/12536/14
67+
[Becoming an Effective Contributor to Swift]: https://youtu.be/oGJKsp-pZPk
68+
[Getting Started with Swift Compiler Development]: https://modocache.io/getting-started-with-swift-development
69+
[Contributing to Open Source Swift]: https://youtu.be/Ysa2n8ZX-YY
70+
71+
## AST
72+
73+
- [The secret life of types in Swift][] by Slava Pestov (blog post, Jul 2016):
74+
This blog post describes the representation of Swift types inside the compiler.
75+
It covers many important concepts: `TypeLoc` vs `TypeRepr` vs `Type`, the
76+
representation of generic types, substitutions and more.
77+
<!-- TODO: It would be great to integrate some of the descriptions
78+
in this blog post into the compiler's own doc comments. -->
79+
80+
[The secret life of types in Swift]: https://medium.com/@slavapestov/the-secret-life-of-types-in-swift-ff83c3c000a5
81+
82+
### libSyntax and SwiftSyntax
83+
84+
- [An overview of SwiftSyntax][] by Luciano Almeida (blog post, Apr 2019):
85+
This post provides a quick tour of libSyntax and SwiftSyntax.
86+
- [Improving Swift Tools with libSyntax][] by Harlan Haskins (talk, Sep 2017):
87+
This talk describes the design of libSyntax/SwiftSyntax and discusses some
88+
useful APIs. It also describes how to write a simple Swift formatter using the
89+
library.
90+
91+
[An overview of SwiftSyntax]: https://medium.com/@lucianoalmeida1/an-overview-of-swiftsyntax-cf1ae6d53494
92+
[Improving Swift Tools with libSyntax]: https://youtu.be/5ivuYGxW_3M
93+
94+
## Type checking and inference
95+
96+
- [Implementing Swift Generics][] by Slava Pestov and John McCall (talk, Oct 2017):
97+
This talk dives into how Swift's compilation scheme for generics balances
98+
(a) modularity and separate compilation with (b) the ability to pass unboxed
99+
values and (c) the flexibility to optionally generate fully specialized code.
100+
It covers the following type-checking related topics: type-checking generic
101+
contexts, requirement paths and canonicalized generic signatures.
102+
- [A Type System from Scratch][] by Robert Widmann (talk, Apr 2017):
103+
This talk covers several topics related to type-checking and inference in Swift:
104+
- Understanding sequent notation which can be used to represent typing judgments.
105+
- An overview of how bidirectional type-checking works.
106+
- Examples of checking and inferring types for some Swift expressions.
107+
- Interaction complexity of different type system features with type inference.
108+
- Type variables and constraint graphs.
109+
110+
[Implementing Swift Generics]: https://youtu.be/ctS8FzqcRug
111+
[A Type System from Scratch]: https://youtu.be/IbjoA5xVUq0
112+
113+
## SIL
114+
115+
- [Ownership SSA][] by Michael Gottesman (talk, Oct 2019): This talk describes
116+
efficiency and correctness challenges with automatic reference counting and
117+
how including ownership semantics in the compiler's intermediate representation
118+
helps tackles those challenges.
119+
- [How to talk to your kids about SIL type use][] by Slava Pestov (blog post,
120+
Jul 2016): This blog post describes several important SIL concepts: object
121+
vs address types, AST -> SIL type lowering, trivial vs loadable vs
122+
address-only SIL types, abstraction patterns and more.
123+
- [Swift's High-Level IR][] by Joe Groff and Chris Lattner (talk, Oct 2015):
124+
This talk describes the goals and design of SIL. It covers the following:
125+
- Some commonly used SIL instructions and how they are motivated by language
126+
features.
127+
- Some early passes in SIL processing, such as mandatory inlining,
128+
box-to-stack promotion and definite initialization.
129+
- Why SIL is useful as an intermediate representation between the AST and
130+
LLVM IR.
131+
132+
[Ownership SSA]: https://youtu.be/qy3iZPHZ88o
133+
[How to talk to your kids about SIL type use]: https://medium.com/@slavapestov/how-to-talk-to-your-kids-about-sil-type-use-6b45f7595f43
134+
[Swift's High-Level IR]: https://youtu.be/Ntj8ab-5cvE
135+
136+
## Code generation, runtime and ABI
137+
138+
- [How Swift Achieved Dynamic Linking Where Rust Couldn't][] by Alexis
139+
Beingessner (blog post, Nov 2019): This blog post describes Swift's approach
140+
for compiling polymorphic functions, contrasting it with the strategy used by
141+
Rust and C++ (monomorphization). It covers the following topics: ABI stability,
142+
library evolution, resilient type layout, reabstraction, materialization,
143+
ownership and calling conventions.
144+
- [arm64e: An ABI for Pointer Authentication][] by Ahmed Bougacha and John McCall
145+
(talk, Oct 2019): This talk does not mention Swift specifically, but provides a
146+
good background on the arm64e ABI and pointer authentication. The ABI affects
147+
parts of IR generation, the Swift runtime, and small parts of the standard
148+
library using unsafe code.
149+
- [Exploiting The Swift ABI][] by Robert Widmann (talk, July 2019):
150+
This talk is a whirlwind tour of different aspects of the Swift ABI and runtime
151+
touching the following topics: reflection, type layout, ABI entrypoints,
152+
Swift's compilation model for generics and archetypes, witness tables,
153+
relative references, context descriptors and more.
154+
- [Efficiently Implementing Runtime Metadata][] by Joe Groff and Doug Gregor
155+
(talk, Oct 2018): This talk covers the use of relative references in Swift's
156+
runtime metadata structures. After describing some important metrics impacted
157+
by the use of dynamic libraries, it goes through the different kinds of
158+
relative references used in the Swift runtime and the resulting tooling and
159+
performance benefits.
160+
- [Coroutine Representations and ABIs in LLVM][] by John McCall (talk, Oct 2018):
161+
This talk describes several points in the design space for coroutines, diving
162+
into important implementation tradeoffs. It explains how different language
163+
features can be built on top of coroutines and how they impose different
164+
design requirements. It also contrasts C++20's coroutines feature with
165+
Swift's accessors, describing the differences between the two as implemented
166+
in LLVM.
167+
- [Implementing Swift Generics][]: This talk is mentioned in the type-checking
168+
section. It also covers the following code generation and runtime topics:
169+
value witness tables, type metadata, abstraction patterns, reabstraction,
170+
reabstraction thunks and protocol witness tables.
171+
172+
[How Swift Achieved Dynamic Linking Where Rust Couldn't]: https://gankra.github.io/blah/swift-abi/
173+
[arm64e: An ABI for Pointer Authentication]: https://youtu.be/C1nZvpEBfYA
174+
[Exploiting The Swift ABI]: https://youtu.be/0rHG_Pa86oA
175+
[Efficiently Implementing Runtime Metadata]: https://youtu.be/G3bpj-4tWVU
176+
[Coroutine Representations and ABIs in LLVM]: https://youtu.be/wyAbV8AM9PM

‎docs/README.md

+4-6
Original file line numberDiff line numberDiff line change
@@ -252,12 +252,10 @@ They are preserved mostly for historical interest.
252252

253253
## External Resources
254254

255-
The official [Swift blog](https://swift.org/blog/) contains a lot of useful
256-
information, such as how library evolution works and how the compiler's new
257-
diagnostic architecture is structured, helping us provide more precise
258-
diagnostics.
259-
260-
TODO: Add a new document ExternalResources.md.
255+
External resources are listed in [docs/ExternalResources.md](ExternalResources.md).
256+
These cover a variety of topics,
257+
such as the design of different aspects of the Swift compiler and runtime
258+
and contributing to the project more effectively.
261259

262260
## Uncategorized
263261

0 commit comments

Comments
 (0)