TODO: The layout of key path patterns (emitted by the compiler, to represent key path literals) isn't documented yet.Mangling.rst: Describes the stable mangling scheme, which produces unique symbols for ABI-public declarations.RegisterUsage.md: Summarizes the register allocation for ARM64 and x86_64 calling conventions, including the context register (self) and error return register.TypeLayout.rst: Describes the algorithms/strategies for fragile struct and tuple layout; class layout; fragile enum layout; and existential container layout.TypeMetadata.rst: Describes the fields, values, and layout of metadata records, which can be used (by reflection and debugger tools) to discover information about types.Recommended Practices
Coding
Diagnostics
Project Information
- Branches.md: Describes how different branches are setup and what the automerger does.
- ContinuousIntegration.md: Describes the continuous integration setup, including the
@swift_ci
bot.
Evolution Documents
Manifestos
Proposals
Old proposals are present in the /docs/proposals directory. More recent proposals are located in the apple/swift-evolution repository. You can see the status of different proposals at https://apple.github.io/swift-evolution/.
Surveys
- CallingConvention.rst: This whitepaper discusses the Swift calling convention (high-level semantics; ownership transfer; physical representation; function signature lowering).
- ErrorHandlingRationale.rst: Surveys error-handling in a variety of languages, and describes the rationale behind the design of error handling in Swift.
- weak.rst: Discusses weak references, including the designs in different languages, and proposes changes to Swift (pre-1.0).
Archive
These documents are known to be out-of-date and are superseded by other documentation, primarily The Swift Programming Language (TSPL). They are preserved mostly for historical interest.
External Resources
External resources are listed in ExternalResources.md. These cover a variety of topics, such as the design of different aspects of the Swift compiler and runtime and contributing to the project more effectively.
Uncategorized
Needs refactoring
The documents in this section might be worth breaking up into several documents, and linking one document from the other. Breaking up into components will provide greater clarity to contributors wanting to add new documentation.
- ARCOptimization.rst: Covers how ARC optimization works, with several examples. TODO: Not clear if this is intended to be an explanation or a reference guide.
- CompilerPerformance.md: Thoroughly discusses different ways of measuring compiler performance and common pitfalls. TODO: Consider breaking up into one high-level explanation explaining key concepts and individual how-to guides that can be expanded independently. Also, it's not the right place to explain details of different compiler modes.
- DevelopmentTips.md: Contains an assortment of tips for better productivity when working on the compiler. TODO: Might be worthwhile to make a dedicated how-to guide or explanation. It might also be valuable to introduce the tips in context, and have the explanation link to all the different tips.
- Diagnostics.md: Describes how to write diagnostic messages and associated educational notes. TODO: Consider splitting into how-tos and recommended practices. For example, we could have a how-to guide on adding a new diagnostic, and have a recommended practices page which explains the writing style for diagnostics and educational notes.
- HowSwiftImportsCAPIs.md: Contains a thorough description of the mapping between C/ObjC entities and Swift entities. TODO: Not clear if this is intended to be language documentation (for Swift developers), an explanation or a reference guide.
- OptimizerCountersAnalysis.md: TODO: Consider breaking up into a how-to guide on dumping and analyzing the counters and an explanation for the counter collection system.
- Testing.md: TODO: Consider splitting into a how-to guide on writing a new test case and an explanation for how the compiler is tested.
- SwiftIndent.md: TODO: Unclear if this is intended to be an explanation or a reference guide.
- Random.md: Stub.
Archive