Documentation Index

This page contains a curated index of the documentation found in the Swift compiler repository.

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. If you are stuck, please use the development category on the Swift forums to ask for help!

Building the Toolchain

• GettingStarted.md: Describes how to set up a working Swift development environment for Linux and macOS, and get an edit-build-test-debug loop going.
• Building for Android:
  • Android.md: How to run some simple programs and the Swift test suite on an Android device.
  • AndroidBuild.md: How to build the Swift SDK for Android on Windows.
• Building for Windows:
  • WindowsBuild.md: How to build Swift on Windows using Visual Studio.
• Building for OpenBSD:
  • OpenBSD.md: Overview of specific steps for building on OpenBSD.

Contributing

• FirstPullRequest.md: Describes how to submit your first pull request. This is the place to start if you're new to the project!
• 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.
• DebuggingTheCompiler.md: Describes a variety of techniques for debugging.
• FAQ.md: Answers "How do I do X?" for a variety of common tasks.
• Lexicon.md: Canonical reference for terminology used throughout the project.
• Testing.md: Information about running and developing tests in the compiler's test suite.

Reference Guides

• Backtracing.rst: Describes Swift's backtracing and crash reporting support.
• CompilerPerformance.md: Thoroughly discusses different ways of measuring compiler performance and common pitfalls.
• Generics/: "Compiling Swift Generics", a book about the implementation of parameteric polymorphism in the Swift compiler. Also covers the compilation pipeline, request evaluator, and type system in general.
• LibraryEvolution.rst: Specifies what changes can be made without breaking binary compatibility.
• RequestEvaluator.md: Describes the request evaluator architecture, which is used for lazy type-checking and efficient caching.
• SIL/: Documentation about SIL, the Swift intermediate language.
• TypeChecker.md: Provides an overview of the expression type checker.
• UnderscoredAttributes.md: Documents semantics for underscored (unstable) attributes in the language.

The Swift ABI

• CallingConventionSummary.rst: A concise summary of the calling conventions used for C/C++, Objective-C and Swift on Apple platforms. Contains references to source documents, where further detail is required.
• CallingConvention.rst: This whitepaper discusses the Swift calling convention (high-level semantics; ownership transfer; physical representation; function signature lowering).
• KeyPaths.md: Describes the layout of key path objects (instantiated by the runtime, and therefore not strictly ABI).
  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.
• 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.

SIL Optimizer

• 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.
• HowToUpdateDebugInfo.md: A guide for SIL optimization pass authors for how to properly update debug info in SIL program transformations.
• 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.
• TransparentAttr.md: Documents the semantics of the @_transparent attribute.

Swift 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. <!-- NOTE: Outdated -->
• DriverParseableOutput.md: Describes the output format of the driver's -parseable-output flag, which is suitable for consumption by editors and IDEs.
• DependencyAnalysis.md: Describes different kinds of dependencies across files in the same module, important for understanding incremental builds.

Objective-C Interop

• ObjCInterop.md Documents how Swift interoperates with ObjC code and the ObjC runtime.
• CToSwiftNameTranslation.md: Describes how C and ObjC entities are imported into Swift by the Clang Importer.
• CToSwiftNameTranslation-OmitNeedlessWords.md: Describes how the "Omit Needless Words" algorithm works, making imported names more idiomatic.
• HowSwiftImportsCAPIs.md: Contains a thorough description of the mapping between C/ObjC entities and Swift entities.

Rationales and Manifestos

• ABIStabilityManifesto.md: Describes the goals and design for ABI stability.
• LibraryEvolutionManifesto.md: Describes the goals and design for Library Evolution.
• BuildManifesto.md: Provides an outline for modularizing the build system for the Swift toolchain.
• CppInteroperabilityManifesto.md: Describes the motivation and design for first-class Swift-C++ interoperability.
• DifferentiableProgramming.md: Outlines a vision and design for first-class differentiable programming in Swift.
• ErrorHandlingRationale.md: Surveys error-handling in a variety of languages, and describes the rationale behind the design of error handling in Swift.
• OwnershipManifesto.md: Provides a framework for understanding ownership in Swift, and highlights potential future directions for the language.
• SequencesAndCollections.rst: Provides background on the design of different collection-related protocols.
• StdlibRationales.rst: Provides rationale for common questions/complaints regarding design decisions in the Swift stdlib.
• StringManifesto.md: Provides a long-term vision for the String type.
• WeakReferences.md: Discusses weak references, including the designs in different languages, and proposes changes to Swift (pre-1.0). <!-- NOTE: Outdated -->

Uncategorized

• Diagnostics.md: Describes how to write diagnostic messages and associated documentation.
• DifferentiableProgrammingImplementation.md: Describes how automatic differentiation is implemented in the Swift compiler.
• DocumentationComments.md: Describes the format of Swift's documentation markup, including specially-recognized sections.
• ExternalResources.md: Contains links to various materials found outside of the Swift repository.
• Literals.md: Describes type-checking and inference specifically for literals.
• Serialization.md: Gives an overview of the LLVM bitcode format used for swiftmodules.
  • StableBitcode.md: Describes how to maintain compatibility when changing the serialization format.
• SwiftLocalRefactoring.md: Describes how refactorings work and how they can be tested.
• RunningIncludeWhatYouUse.md: Describes how to run include-what-you-use on the Swift project.
• libFuzzerIntegration.md: Using libFuzzer to fuzz Swift code.
• DynamicCasting.md: Behavior of the dynamic casting operators is, as?, and as!.
• WebAssembly.md: Explains some decisions that were made while implementing the WebAssembly target.