Skip to content

Latest commit

 

History

History
323 lines (274 loc) · 14.4 KB

README.md

File metadata and controls

323 lines (274 loc) · 14.4 KB

Documentation Index

This page describes the overall organization of documentation for the Swift toolchain. It is divided into the following sections:

  • Tutorials gently guide you towards achieving introductory tasks, while assuming minimal background knowledge.
  • How-To Guides help you complete specific tasks in a step-by-step fashion.
  • Explanations discuss key subsystems and concepts, at a high level. They also provide background information and talk about design tradeoffs.
  • Reference Guides contain a thorough technical reference for complex topics. They assume some overall understanding of surrounding subsystems.
  • Recommended Practices suggests guidelines for writing code and diagnostics.
  • Project Information tracks continuous integration (CI), branching and release history.
  • Evolution Documents includes proposals and manifestos for changes to Swift.
  • The External Resources section provides links to valuable discussions about Swift development, in the form of talks and blog posts.
  • The Uncategorized section is for documentation which does not fit neatly into any of the above categories. We would like minimize items in this section; avoid adding new documentation here.

Sometimes documentation is not enough. Especially if you are a new contributor, you might run into roadblocks which are not addressed by the existing documentation. Or they are addressed somewhere but you cannot find the relevant bits. If you are stuck, please use the development category on the Swift forums to ask for help!

Lastly, note that we are slowly moving towards a more structured form of documentation, inspired by the Django project [1] [2]. Hence parts of this page are aspirational and do not reflect how much of the existing documentation is written. Pull requests to clean up the Uncategorized section, or generally fill gaps in the documentation are very welcome. If you would like to make major changes, such as adding entire new pieces of documentation, please create a thread on the Swift forums under the development category to discuss your proposed changes.

Tutorials

How-To Guides

Explanations

  • ByteTree.md: Describes the ByteTree binary format used for serializing syntax trees in libSyntax.

Compiler and Runtime Subsystems

  • Driver:
    • Driver.md: Provides an overview of the driver, compilation model, and the compiler's command-line options. Useful for integration into build systems other than SwiftPM or Xcode.
    • DriverInternals.md: Provides a bird's eye view of the driver's implementation.
  • DependencyAnalysis.md: Describes different kinds of dependencies across files in the same module, important for understanding incremental builds.
  • C and ObjC interoperability: Clang Importer and PrintAsObjC
  • Type-checking and inference:
    • TypeChecker.rst: Provides an overview of how type-checking and inference work.
    • RequestEvaluator.md: Describes the request evaluator architecture, which is used for lazy type-checking and efficient caching.
    • Literal.md: Describes type-checking and inference specifically for literals.
  • Serialization.rst: Gives an overview of the LLVM bitcode format used for swiftmodules.
    • StableBitcode.md: Describes how to maintain compatibility when changing the serialization format.
  • SIL and SIL Optimizations:
    • SILProgrammersManual.md: Provides an overview of the implementation of SIL in the compiler.
    • OptimizerDesign.md: Describes the design of the optimizer pipeline.
    • HighLevelSILOptimizations.rst: Describes how the optimizer understands the semantics of high-level operations on currency data types and optimizes accordingly. Includes a thorough discussion of the @_semantics attribute.

SourceKit subsystems

Language subsystems

Stdlib Design

Reference Guides

  • DriverParseableOutput.md: Describes the output format of the driver's -parseable-output flag, which is suitable for consumption by editors and IDEs.
  • ObjCInterop.md Documents how Swift interoperates with ObjC code and the ObjC runtime.
  • LibraryEvolution.rst: Specifies what changes can be made without breaking binary compatibility.
  • SIL.rst: Documents the Swift Intermediate Language (SIL).
  • Runtime.md: Describes the ABI interface to the Swift runtime.
  • Lexicon.md: Canonical reference for terminology used throughout the project.

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

  • 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

The official Swift blog contains a lot of useful information, such as how library evolution works and how the compiler's new diagnostic architecture is structured, helping us provide more precise diagnostics.

TODO: Add a new document ExternalResources.md.

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 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