Skip to content

Commit a40edb9

Browse files
martinboehmemartinboehme
authored
Merge branch 'master' into martinboehme-patch-2
2 parents f025dea + 98522b0 commit a40edb9

File tree

171 files changed

+2983
-611
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

171 files changed

+2983
-611
lines changed

‎README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,9 @@ Once you are able to build things successfully and have a compile-test-debug
8585
loop going, check out the [development tips](docs/DevelopmentTips.md) for
8686
better productivity while working on the compiler.
8787

88+
You can also skim [docs/README.md](/docs/README.md) to understand what
89+
high-level documentation is available.
90+
8891
### System Requirements
8992

9093
macOS, Ubuntu Linux LTS, and the latest Ubuntu Linux release are currently

‎docs/Lexicon.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,12 @@ and *zero* protocols; the latter is the `Any` type).
167167
Describes a type or function where making changes will break binary
168168
compatibility. See [LibraryEvolution.rst](LibraryEvolution.rst).
169169

170+
## gardening
171+
172+
Describes contributions which fix code that is not executed
173+
(such as in a manifesto or README) and written text
174+
(correcting typos and grammatical errors).
175+
170176
## generic environment
171177

172178
Provides context for interpreting a type that may have generic parameters

‎docs/README.md

Lines changed: 320 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,320 @@
1+
# Documentation Index
2+
3+
This page describes the overall organization of documentation for the Swift toolchain.
4+
It is divided into the following sections:
5+
6+
- [Tutorials](#tutorials)
7+
gently guide you towards achieving introductory tasks,
8+
while assuming minimal background knowledge.
9+
- [How-To Guides](#how-to-guides)
10+
help you complete specific tasks in a step-by-step fashion.
11+
- [Explanations](#explanations)
12+
discuss key subsystems and concepts, at a high level.
13+
They also provide background information and talk about design tradeoffs.
14+
- [Reference Guides](#reference-guides)
15+
contain a thorough technical reference for complex topics.
16+
They assume some overall understanding of surrounding subsystems.
17+
- [Recommended Practices](#recommended-practices)
18+
suggests guidelines for writing code and diagnostics.
19+
- [Project Information](#project-information)
20+
tracks continuous integration (CI), branching and release history.
21+
- [Evolution Documents](#evolution-documents)
22+
includes proposals and manifestos for changes to Swift.
23+
- The [External Resources](#external-resources) section provides links to
24+
valuable discussions about Swift development, in the form of talks
25+
and blog posts.
26+
- The [Uncategorized](#uncategorized) section is for documentation which does
27+
not fit neatly into any of the above categories. We would like minimize
28+
items in this section; avoid adding new documentation here.
29+
30+
Sometimes documentation is not enough.
31+
Especially if you are a new contributor, you might run into roadblocks
32+
which are not addressed by the existing documentation.
33+
Or they are addressed somewhere but you cannot find the relevant bits.
34+
If you are stuck, please use the [development category][] on the Swift forums
35+
to ask for help!
36+
37+
Lastly, note that we are slowly moving towards a more structured form of
38+
documentation, inspired by the Django project [[1][Django-docs-1]]
39+
[[2][Django-docs-2]]. Hence parts of this page are aspirational
40+
and do not reflect how much of the existing documentation is written.
41+
Pull requests to clean up the [Uncategorized](#uncategorized) section,
42+
or generally fill gaps in the documentation are very welcome.
43+
If you would like to make major changes, such as adding entire new pieces of
44+
documentation, please create a thread on the Swift forums under the
45+
[development category][] to discuss your proposed changes.
46+
47+
[development category]: https://forums.swift.org/c/development
48+
[Django-docs-1]: https://docs.djangoproject.com/
49+
[Django-docs-2]: https://documentation.divio.com/#the-documentation-system
50+
51+
## Tutorials
52+
53+
- [libFuzzerIntegration.md](/docs/libFuzzerIntegration.md):
54+
Using `libFuzzer` to fuzz Swift code.
55+
56+
## How-To Guides
57+
58+
- [DebuggingTheCompiler.md](/docs/DebuggingTheCompiler.md):
59+
Describes a variety of techniques for debugging.
60+
- Building for Android:
61+
- [Android.md](/docs/Android.md):
62+
How to run some simple programs and the Swift test suite on an Android device.
63+
- [AndroidBuild.md](/docs/AndroidBuild.md):
64+
How to build the Swift SDK for Android on Windows.
65+
- Building for Windows:
66+
- [Windows.md](/docs/Windows.md):
67+
Overview on how to build Swift for Windows.
68+
- [WindowsBuild.md](/docs/WindowsBuild.md):
69+
How to build Swift on Windows using Visual Studio.
70+
- [WindowsCrossCompile.md](/docs/WindowsCrossCompile.md):
71+
How to cross compile Swift for Windows on a non-Windows host OS.
72+
73+
## Explanations
74+
75+
- [ByteTree.md](/docs/ByteTree.md):
76+
Describes the ByteTree binary format used for serializing syntax trees
77+
in `libSyntax`.
78+
79+
### Compiler and Runtime Subsystems
80+
81+
- Driver:
82+
- [Driver.md](/docs/Driver.md):
83+
Provides an overview of the driver, compilation model, and the compiler's
84+
command-line options. Useful for integration into build systems other than
85+
SwiftPM or Xcode.
86+
- [DriverInternals.md](/docs/DriverInternals.md):
87+
Provides a bird's eye view of the driver's implementation.
88+
<!-- NOTE: Outdated -->
89+
- [DependencyAnalysis.md](/docs/DependencyAnalysis.md):
90+
Describes different kinds of dependencies across files in the same module,
91+
important for understanding incremental builds.
92+
- C and ObjC interoperability: Clang Importer and PrintAsObjC
93+
- [CToSwiftNameTranslation.md](/docs/CToSwiftNameTranslation.md):
94+
Describes how C and ObjC entities are imported into Swift
95+
by the Clang Importer.
96+
- [CToSwiftNameTranslation-OmitNeedlessWords.md](/docs/CToSwiftNameTranslation-OmitNeedlessWords.md):
97+
Describes how the "Omit Needless Words" algorithm works,
98+
making imported names more idiomatic.
99+
- Type-checking and inference:
100+
- [TypeChecker.rst](/docs/TypeChecker.rst):
101+
Provides an overview of how type-checking and inference work.
102+
- [RequestEvaluator.md](/docs/RequestEvaluator.md):
103+
Describes the request evaluator architecture, which is used for
104+
lazy type-checking and efficient caching.
105+
- [Literal.md](/docs/Literal.md):
106+
Describes type-checking and inference specifically for literals.
107+
- [Serialization.rst](/docs/Serialization.rst):
108+
Gives an overview of the LLVM bitcode format used for swiftmodules.
109+
- [StableBitcode.md](/docs/StableBitcode.md):
110+
Describes how to maintain compatibility when changing the serialization
111+
format.
112+
- SIL and SIL Optimizations:
113+
- [SILProgrammersManual.md](/docs/SILProgrammersManual.md):
114+
Provides an overview of the implementation of SIL in the compiler.
115+
- [OptimizerDesign.md](/docs/OptimizerDesign.md):
116+
Describes the design of the optimizer pipeline.
117+
- [HighLevelSILOptimizations.rst](docs/HighLevelSILOptimizations.rst):
118+
Describes how the optimizer understands the semantics of high-level
119+
operations on currency data types and optimizes accordingly.
120+
Includes a thorough discussion of the `@_semantics` attribute.
121+
122+
### SourceKit subsystems
123+
124+
- [SwiftLocalRefactoring.md](/docs/refactoring/SwiftLocalRefactoring.md):
125+
Describes how refactorings work and how they can be tested.
126+
127+
### Language subsystems
128+
129+
- Swift's Object Model
130+
- [LogicalObjects.md]():
131+
Describes the differences between logical and physical objects and
132+
introduces materialization and writeback.
133+
- [MutationModel.rst]() <!--: NOTE: Outdated -->
134+
- [DocumentationComments.md](/docs/DocumentationComments.md):
135+
Describes the format of Swift's documentation markup, including
136+
specially-recognized sections.
137+
138+
### Stdlib Design
139+
140+
- [SequencesAndCollections.rst](/docs/SequencesAndCollections.rst):
141+
Provides background on the design of different collection-related protocols.
142+
- [StdlibRationales.rst](/docs/StdlibRationales.rst):
143+
Provides rationale for common questions/complaints regarding design decisions
144+
in the Swift stdlib.
145+
146+
## Reference Guides
147+
148+
- [DriverParseableOutput.md](/docs/DriverParseableOutput.md):
149+
Describes the output format of the driver's `-parseable-output` flag,
150+
which is suitable for consumption by editors and IDEs.
151+
- [ObjCInterop.md](/docs/ObjCInterop.md)
152+
Documents how Swift interoperates with ObjC code and the ObjC runtime.
153+
- [LibraryEvolution.rst](/docs/LibraryEvolution.rst):
154+
Specifies what changes can be made without breaking binary compatibility.
155+
- [SIL.rst](/docs/SIL.rst):
156+
Documents the Swift Intermediate Language (SIL).
157+
- [TransparentAttr.md](/docs/TransparentAttr.md):
158+
Documents the semantics of the `@_transparent` attribute.
159+
- [Runtime.md](/docs/Runtime.md):
160+
Describes the ABI interface to the Swift runtime.
161+
<!-- NOTE: Outdated -->
162+
- [Lexicon.md](/docs/Lexicon.md):
163+
Canonical reference for terminology used throughout the project.
164+
165+
## Recommended Practices
166+
167+
### Coding
168+
169+
- [AccessControlInStdlib.rst](/docs/AccessControlInStdlib.rst):
170+
Describes the policy for access control modifiers and related naming
171+
conventions in the stdlib.
172+
<!-- NOTE: Outdated -->
173+
- [IndexInvalidation.md](/docs/IndexInvalidation.md):
174+
Describes the expected behavior of indexing APIs exposed by the stdlib.
175+
- [StdlibAPIGuidelines.rst](/docs/StdlibAPIGuidelines.rst):
176+
Provides guidelines for designing stdlib APIs.
177+
<!-- NOTE: Outdated -->
178+
- [StandardLibraryProgrammersManual](/docs/StandardLibraryProgrammersManual.md):
179+
Provides guidelines for working code in the stdlib.
180+
- [OptimizationTips.rst](/docs/OptimizationTips.rst):
181+
Provides guidelines for writing high-performance Swift code.
182+
183+
### Diagnostics
184+
185+
## Project Information
186+
187+
- [Branches.md](/docs/Branches.md):
188+
Describes how different branches are setup and what the automerger does.
189+
- [ContinuousIntegration.md](ContinuousIntegration.md):
190+
Describes the continuous integration setup, including the `@swift_ci` bot.
191+
192+
## Evolution Documents
193+
194+
### Manifestos
195+
196+
- ABI Stability and Library Evolution
197+
- [ABIStabilityManifesto.md](/docs/ABIStabilityManifesto.md):
198+
Describes the goals and design for ABI stability.
199+
- [LibraryEvolutionManifesto.md](/docs/LibraryEvolutionManifesto.md):
200+
Describes the goals and design for Library Evolution.
201+
- [BuildManifesto.md](BuildManifesto.md):
202+
Provides an outline for modularizing the build system for the Swift toolchain.
203+
- [CppInteroperabilityManifesto.md](CppInteroperabilityManifesto.md):
204+
Describes the motivation and design for first-class Swift-C++ interoperability.
205+
- [DifferentiableProgramming.md](/docs/DifferentiableProgramming.md):
206+
Outlines a vision and design for first-class differentiable programming in Swift.
207+
- [GenericsManifesto.md](/docs/GenericsManifesto.md):
208+
Communicates a vision for making the generics system in Swift more powerful.
209+
- [OwnershipManifesto.md](/docs/OwnershipManifesto.md):
210+
Provides a framework for understanding ownership in Swift,
211+
and highlights potential future directions for the language.
212+
- [StringManifesto.md](/docs/StringManifesto.md):
213+
Provides a long-term vision for the `String` type.
214+
215+
### Proposals
216+
217+
Old proposals are present in the [/docs/proposals](/docs/proposals) directory.
218+
More recent proposals are located in the [apple/swift-evolution][] repository.
219+
You can see the status of different proposals at
220+
<https://apple.github.io/swift-evolution/>.
221+
222+
[swift-evolution]: https://github.com/apple/swift-evolution
223+
224+
### Surveys
225+
226+
- [ErrorHandlingRationale.rst](/docs/ErrorHandlingRationale.rst):
227+
Surveys error-handling in a variety of languages, and describes the rationale
228+
behind the design of error handling in Swift.
229+
- [weak.rst](/docs/weak.rst):
230+
Discusses weak references, including the designs in different languages,
231+
and proposes changes to Swift (pre-1.0).
232+
<!-- NOTE: Outdated -->
233+
234+
### Archive
235+
236+
These documents are known to be out-of-date and are superseded by other
237+
documentation, primarily [The Swift Programming Language (TSPL)][].
238+
They are preserved mostly for historical interest.
239+
240+
- [AccessControl.rst](/docs/AccessControl.swift)
241+
- [Arrays.rst](/docs/Arrays.rst)
242+
<!-- Has additional notes on bridging that may be of general interest? -->
243+
- [Generics.rst](/docs/Generics.rst)
244+
- [ErrorHandling.rst](/docs/ErrorHandling.rst)
245+
- [StringDesign.rst](/docs/StringDesign.rst)
246+
- [TextFormatting.rst](/docs/TextFormatting.rst)
247+
248+
[The Swift Programming Language]: https://docs.swift.org/swift-book
249+
250+
## External Resources
251+
252+
The official [Swift blog](https://swift.org/blog/) contains a lot of useful
253+
information, such as how library evolution works and how the compiler's new
254+
diagnostic architecture is structured, helping us provide more precise
255+
diagnostics.
256+
257+
TODO: Add a new document ExternalResources.md.
258+
259+
## Uncategorized
260+
261+
### Needs refactoring
262+
263+
The documents in this section might be worth breaking up into several documents,
264+
and linking one document from the other. Breaking up into components will
265+
provide greater clarity to contributors wanting to add new documentation.
266+
267+
- [ARCOptimization.rst](/docs/ARCOptimization.rst):
268+
Covers how ARC optimization works, with several examples.
269+
TODO: Not clear if this is intended to be an explanation or a reference guide.
270+
- [CompilerPerformance.md](/docs/CompilerPerformance.md):
271+
Thoroughly discusses different ways of measuring compiler performance
272+
and common pitfalls.
273+
TODO: Consider breaking up into one high-level explanation explaining key
274+
concepts and individual how-to guides that can be expanded independently.
275+
Also, it's not the right place to explain details of different compiler modes.
276+
- [DevelopmentTips.md](/docs/DevelopmentTips.md):
277+
Contains an assortment of tips for better productivity when working on the
278+
compiler.
279+
TODO: Might be worthwhile to make a dedicated how-to guide or explanation.
280+
It might also be valuable to introduce the tips in context, and have the
281+
explanation link to all the different tips.
282+
- [Diagnostics.md](/docs/Diagnostics.md):
283+
Describes how to write diagnostic messages and associated educational notes.
284+
TODO: Consider splitting into how-tos and recommended practices.
285+
For example, we could have a how-to guide on adding a new diagnostic,
286+
and have a recommended practices page which explains the writing style
287+
for diagnostics and educational notes.
288+
- [HowSwiftImportsCAPIs.md](/docs/HowSwiftImportsCAPIs.md):
289+
Contains a thorough description of the mapping between C/ObjC entities and
290+
Swift entities.
291+
TODO: Not clear if this is intended to be language documentation
292+
(for Swift developers), an explanation or a reference guide.
293+
- [OptimizerCountersAnalysis.md](/docs/OptimizerCountersAnalysis.md):
294+
TODO: Consider breaking up into a how-to guide
295+
on dumping and analyzing the counters
296+
and an explanation for the the counter collection system.
297+
- [Testing.md](/docs/Testing.md):
298+
TODO: Consider splitting into a how-to guide on writing a new test case
299+
and an explanation for how the compiler is tested.
300+
- [SwiftIndent.md](/docs/SwiftIndent.md):
301+
TODO: Unclear if this is intended to be an explanation or a reference guide.
302+
- [Random.md](/docs/Random.md): Stub.
303+
304+
### Archive
305+
306+
- [FailableInitializers.rst](/docs/FailableInitializers.rst):
307+
Superseded by documentation in [The Swift Programming Language][].
308+
- [InitializerProblems.rst](/docs/InitializerProblems.rst):
309+
Describes some complexities around initialization in Swift.
310+
TODO: It would be great to have an explanation, say `InitializationModel.md`,
311+
that covers the initialization model and new attributes like
312+
`@_hasMissingDesignatedInitializers`. Some of this is covered in
313+
[TSPL's initialization section][] but that doesn't include newly added
314+
attributes.
315+
- [Modules.rst](/docs/Module.rst): for Swift pre-1.0.
316+
- [Swift3Compatibility.md](/docs/Swift3Compatibility.md):
317+
Discusses the Swift 3 -> Swift 4 migration.
318+
- [StoredAndComputedVariables.rst](): for Swift pre-1.0.
319+
320+
[TSPL's initialization section]: https://docs.swift.org/swift-book/LanguageGuide/Initialization.html

‎docs/WindowsBuild.md

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,22 +2,33 @@
22

33
Visual Studio 2017 or newer is needed to build Swift on Windows. The free Community edition is sufficient to build Swift.
44

5-
The following must take place in the **developer command prompt** (provided by Visual Studio). This shows up as "x64 Native Tools Command Prompt for VS2017" (or VS2019, VS2019 Preview depending on the Visual Studio that you are using) in the Start Menu.
5+
The commands below (with the exception of installing Visual Studio) must be entered in the "**x64 Native** Tools Command Prompt for VS2017" (or VS2019, VS2019 Preview depending on the Visual Studio that you are using) in the Start Menu. This sets environment variables to select the correct target platform.
66

77
## Install dependencies
88

9-
- Install the latest version of [Visual Studio](https://www.visualstudio.com/downloads/)
10-
- Make sure to include "Programming Languages|Visual C++" and "Windows and Web Development|Universal Windows App Development|Windows SDK" in your installation. The following components are required:
9+
### Visual Studio
1110

12-
1. Microsoft.VisualStudio.Component.Windows10SDK
13-
2. Microsoft.VisualStudio.Component.Windows10SDK.17763
14-
3. Microsoft.VisualStudio.Component.VC.Tools.x86.x64
11+
An easy way to get most of the tools to build Swift is using the [Visual Studio installer](https://www.visualstudio.com/downloads/). This command installs all needed Visual Studio components as well as Python and Git:
12+
13+
```
14+
vs_community ^
15+
--add Component.CPython2.x86 ^
16+
--add Component.CPython3.x64 ^
17+
--add Microsoft.VisualStudio.Component.Git ^
18+
--add Microsoft.VisualStudio.Component.VC.ATL ^
19+
--add Microsoft.VisualStudio.Component.VC.CMake.Project ^
20+
--add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^
21+
--add Microsoft.VisualStudio.Component.Windows10SDK ^
22+
--add Microsoft.VisualStudio.Component.Windows10SDK.17763
23+
```
24+
25+
If you prefer you can install everything by hand, but make sure to include "Programming Languages|Visual C++" and "Windows and Web Development|Universal Windows App Development|Windows SDK" in your installation. The components listed above are required.
1526

1627
The following [link](https://docs.microsoft.com/visualstudio/install/workload-component-id-vs-build-tools?view=vs-2019) helps in finding the component name given its ID for Visual Studio 2019.
1728

1829
### Python
1930

20-
In the Visual Studio installation program, under *Individual Components*
31+
The command above already installs Python 2 and 3. Alternatively, in the Visual Studio installation program, under *Individual Components*
2132

2233
1. Install *Python 2*, either the 32-bit version (C:\Python27\\) or the 64-bit version (C:\Python27amd64\\)
2334

‎include/swift/AST/ASTTypeIDZone.def

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ SWIFT_TYPEID_NAMED(PatternBindingEntry *, PatternBindingEntry)
5757
SWIFT_TYPEID_NAMED(PostfixOperatorDecl *, PostfixOperatorDecl)
5858
SWIFT_TYPEID_NAMED(PrecedenceGroupDecl *, PrecedenceGroupDecl)
5959
SWIFT_TYPEID_NAMED(PrefixOperatorDecl *, PrefixOperatorDecl)
60+
SWIFT_TYPEID_NAMED(ProtocolConformance *, ProtocolConformance)
6061
SWIFT_TYPEID_NAMED(ProtocolDecl *, ProtocolDecl)
6162
SWIFT_TYPEID_NAMED(SourceFile *, SourceFile)
6263
SWIFT_TYPEID_NAMED(TypeAliasDecl *, TypeAliasDecl)

0 commit comments

Comments
 (0)