diff --git a/.gitignore b/.gitignore index bd9bbcfcec8cb..09c11acabc75d 100644 --- a/.gitignore +++ b/.gitignore @@ -33,6 +33,7 @@ tags #==============================================================================# # Generated docs docs/_build +docs/.docc-build # Finder metadata .DS_Store diff --git a/docs/ABI/GenericSignature.md b/docs/ABI/GenericSignature.md index 5690f994480d7..0eb755c323bda 100644 --- a/docs/ABI/GenericSignature.md +++ b/docs/ABI/GenericSignature.md @@ -1,8 +1,9 @@ # Generic Signatures A generic signature describes a set of generic type parameters along with -a set of constraints on those parameters. Generic entities in Swift -have a corresponding generic signature. For example, the following generic function: +a set of constraints on those parameters. + +Generic entities in Swift have a corresponding generic signature. For example, the following generic function: ```swift func foo(c1: C1, c2: C2) diff --git a/docs/ABI/KeyPaths.md b/docs/ABI/KeyPaths.md index d742ab50c5296..0b9280359d3a9 100644 --- a/docs/ABI/KeyPaths.md +++ b/docs/ABI/KeyPaths.md @@ -2,7 +2,9 @@ **Key path objects** are laid out at runtime as a heap object with a variable-sized payload containing a sequence of encoded components describing -how the key path traverses a value. When the compiler sees a key path literal, +how the key path traverses a value. + +When the compiler sees a key path literal, it generates a **key path pattern** that can be efficiently interpreted by the runtime to instantiate a key path object when needed. This document describes the layout of both. The key path pattern layout is designed in such a diff --git a/docs/DebuggingTheCompiler.md b/docs/DebuggingTheCompiler.md index 3180d890066d6..b220721b8935a 100644 --- a/docs/DebuggingTheCompiler.md +++ b/docs/DebuggingTheCompiler.md @@ -1,7 +1,8 @@ +# Debugging The Compiler -

Debugging The Compiler

+This document contains some useful information for debugging. -This document contains some useful information for debugging: +With this document you can learn how to debug: * The Swift compiler. * Intermediate output of the Swift Compiler. @@ -10,55 +11,6 @@ This document contains some useful information for debugging: Please feel free to add any useful tips that one finds to this document for the benefit of all Swift developers. -**Table of Contents** - -- [Debugging the Compiler Itself](#debugging-the-compiler-itself) - - [Basic Utilities](#basic-utilities) - - [Printing the Intermediate Representations](#printing-the-intermediate-representations) - - [Debugging Diagnostic Emission](#debugging-diagnostic-emission) - - [Asserting on first emitted Warning/Assert Diagnostic](#asserting-on-first-emitted-warningassert-diagnostic) - - [Finding Diagnostic Names](#finding-diagnostic-names) - - [Debugging the Type Checker](#debugging-the-type-checker) - - [Enabling Logging](#enabling-logging) - - [Debugging on SIL Level](#debugging-on-sil-level) - - [Options for Dumping the SIL](#options-for-dumping-the-sil) - - [Getting CommandLine for swift stdlib from Ninja to enable dumping stdlib SIL](#getting-commandline-for-swift-stdlib-from-ninja-to-enable-dumping-stdlib-sil) - - [Dumping the SIL and other Data in LLDB](#dumping-the-sil-and-other-data-in-lldb) - - [Debugging and Profiling on SIL level](#debugging-and-profiling-on-sil-level) - - [SIL source level profiling using -sil-based-debuginfo](#sil-source-level-profiling) - - [ViewCFG: Regex based CFG Printer for SIL/LLVM-IR](#viewcfg-regex-based-cfg-printer-for-silllvm-ir) - - [Debugging the Compiler using advanced LLDB Breakpoints](#debugging-the-compiler-using-advanced-lldb-breakpoints) - - [Debugging the Compiler using LLDB Scripts](#debugging-the-compiler-using-lldb-scripts) - - [Custom LLDB Commands](#custom-lldb-commands) - - [Debugging at LLVM Level](#debugging-at-llvm-level) - - [Options for Dumping LLVM IR](#options-for-dumping-llvm-ir) - - [Bisecting Compiler Errors](#bisecting-compiler-errors) - - [Bisecting on SIL optimizer pass counts to identify optimizer bugs](#bisecting-on-sil-optimizer-pass-counts-to-identify-optimizer-bugs) - - [Using git-bisect in the presence of branch forwarding/feature branches](#using-git-bisect-in-the-presence-of-branch-forwardingfeature-branches) - - [Reducing SIL test cases using bug_reducer](#reducing-sil-test-cases-using-bug_reducer) - - [Disabling PCH Verification](#disabling-pch-verification) - - [Diagnosing LSAN Failures in the Compiler](#diagnosing-lsan-failures-in-the-compiler) -- [Debugging the Compiler Build](#debugging-the-compiler-build) - - [Build Dry Run](#build-dry-run) -- [Debugging the Compiler Driver](#debugging-the-compiler-driver-build) - - [Swift Compiler Driver F.A.Q](#swift-compiler-driver-f.a.q.) - - [Building the compiler without using the standalone driver](#building-the-compiler-without-the-standalone-driver) - - [Invoking the compiler without forwarding to the standalone driver](#invoking-the-compiler-without-forwarding-to-the-standalone-driver) - - [Reproducing the Compiler Driver build steps](#reproducing-the-compiler-driver-build-steps) - - [Installing the Compiler Driver](#installing-the-compiler-driver) -- [Debugging Swift Executables](#debugging-swift-executables) - - [Determining the mangled name of a function in LLDB](#determining-the-mangled-name-of-a-function-in-lldb) - - [Manually symbolication using LLDB](#manually-symbolication-using-lldb) - - [Viewing allocation history, references, and page-level info](#viewing-allocation-history-references-and-page-level-info) - - [Printing memory contents](#printing-memory-contents) - - [Windows Error Codes](#windows-error-codes) -- [Debugging LLDB failures](#debugging-lldb-failures) - - ["Types" Log](#types-log) - - ["Expression" Log](#expression-log) - - [Multiple Logs at a Time](#multiple-logs-at-a-time) -- [Compiler Tools/Options for Bug Hunting](#compiler-toolsoptions-for-bug-hunting) - - [Using `clang-tidy` to run the Static Analyzer](#using-clang-tidy-to-run-the-static-analyzer) - # Debugging the Compiler Itself ## Basic Utilities diff --git a/docs/GenericsManifesto.md b/docs/GenericsManifesto.md index 77fe7774c91b5..c5ba0225da12e 100644 --- a/docs/GenericsManifesto.md +++ b/docs/GenericsManifesto.md @@ -1,3 +1,5 @@ +# Swift Generics Manifesto + (Source: https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160229/011666.html, authored by Douglas Gregor) ## Introduction diff --git a/docs/OptimizerDesign.md b/docs/OptimizerDesign.md index e6e767ad0bf7b..954433a5eeeab 100644 --- a/docs/OptimizerDesign.md +++ b/docs/OptimizerDesign.md @@ -1,13 +1,11 @@ - -### Design of the Swift optimizer +# Design of the Swift optimizer This document describes the design of the Swift Optimizer. It is intended for developers who wish to debug, improve or simply understand what the Swift optimizer does. Basic familiarity with the Swift programming language and knowledge of compiler optimizations is required. - -### Optimization pipeline overview +## Optimization pipeline overview The Swift compiler translates textual Swift programs into LLVM-IR and uses multiple representations in between. The Swift frontend is responsible for @@ -47,7 +45,7 @@ higher-level optimizations. For example, the ARC optimizer and devirtualizer need SSA representation to analyze the program, and dead-code-elimination is a prerequisite to the array optimizations. -### The Swift Pass Manager +## The Swift Pass Manager The Swift pass manager is the unit that executes optimization passes on the functions in the Swift module. Unlike the LLVM optimizer, the @@ -71,7 +69,7 @@ after specific optimizations and to measure how much time is spent in each pass. -### Optimization passes +## Optimization passes There are two kind of optimization passes in Swift: Function passes, and Module passes. Function passes can inspect the entire module but can only modify a @@ -102,7 +100,7 @@ This is the structure of a simple function pass: ``` -### Analysis Invalidation +## Analysis Invalidation Swift Analysis are very different from LLVM analysis. Swift analysis are simply a cache behind some utility that performs computation. For example, the @@ -159,7 +157,7 @@ The invalidation traits that passes can invalidate are: 3. Branches - branches in the code were added, deleted or modified. 4. Functions - Some functions were added or deleted. -### Semantic Tags +## Semantic Tags The Swift optimizer has optimization passes that target specific data structures in the Swift standard library. For example, one optimization can remove the @@ -192,7 +190,7 @@ pipeline. Please refer to the document "High-Level SIL Optimizations" for more details. -### Instruction Invalidation in SIL +## Instruction Invalidation in SIL Swift Passes and Analysis often keep instruction pointers in internal data structures such as Map or Set. A good example of such data structure is a list @@ -231,14 +229,14 @@ following virtual method: } ``` -### Debugging the optimizer +## Debugging the optimizer TODO. -### Whole Module Optimizations +## Whole Module Optimizations TODO. -### List of passes +## List of passes The updated list of passes is available in the file "Passes.def". diff --git a/docs/README.md b/docs/README.md index 74a03b8e7ee3b..b3faf274345ba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,29 +1,33 @@ -# Documentation Index +# Swift Compiler Documentation + +@Metadata { + @TechnologyRoot +} This page describes the overall organization of documentation for the Swift toolchain. It is divided into the following sections: -- [Tutorials](#tutorials) +- [Tutorials](#Tutorials) gently guide you towards achieving introductory tasks, while assuming minimal background knowledge. -- [How-To Guides](#how-to-guides) +- [How-To Guides](#How-To-Guides) help you complete specific tasks in a step-by-step fashion. -- [Explanations](#explanations) +- [Explanations](#Explanations) discuss key subsystems and concepts, at a high level. They also provide background information and talk about design tradeoffs. -- [Reference Guides](#reference-guides) +- [Reference Guides](#Reference-Guides) contain a thorough technical reference for complex topics. They assume some overall understanding of surrounding subsystems. -- [Recommended Practices](#recommended-practices) +- [Recommended Practices](#Recommended-Practices) suggests guidelines for writing code and diagnostics. -- [Project Information](#project-information) +- [Project Information](#Project-Information) tracks continuous integration (CI), branching and release history. -- [Evolution Documents](#evolution-documents) +- [Evolution Documents](#Evolution-Documents) includes proposals and manifestos for changes to Swift. -- The [External Resources](#external-resources) section provides links to +- The [External Resources](#External-Resources) section provides links to valuable discussions about Swift development, in the form of talks and blog posts. -- The [Uncategorized](#uncategorized) section is for documentation which does +- The [Uncategorized](#Uncategorized) section is for documentation which does not fit neatly into any of the above categories. We would like to minimize items in this section; avoid adding new documentation here. @@ -38,7 +42,7 @@ Lastly, note that we are slowly moving towards a more structured form of documentation, inspired by the Django project [[1][Django-docs-1]] [[2][Django-docs-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](#uncategorized) section, +Pull requests to clean up the [Uncategorized](#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 @@ -50,84 +54,84 @@ documentation, please create a thread on the Swift forums under the ## Tutorials -- [libFuzzerIntegration.md](/docs/libFuzzerIntegration.md): +- : Using `libFuzzer` to fuzz Swift code. ## How-To Guides -- [FAQ.md](/docs/HowToGuides/FAQ.md): +- : Answers "How do I do X?" for a variety of common tasks. -- [FirstPullRequest.md](/docs/HowToGuides/FirstPullRequest.md): +- : Describes how to submit your first pull request. This is the place to start if you're new to the project! -- [GettingStarted.md](/docs/HowToGuides/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. -- [DebuggingTheCompiler.md](/docs/DebuggingTheCompiler.md): +- : Describes a variety of techniques for debugging. - Building for Android: - - [Android.md](/docs/Android.md): + - : How to run some simple programs and the Swift test suite on an Android device. - - [AndroidBuild.md](/docs/AndroidBuild.md): + - : How to build the Swift SDK for Android on Windows. - Building for Windows: - - [Windows.md](/docs/Windows.md): + - : Overview on how to build Swift for Windows. - - [WindowsBuild.md](/docs/WindowsBuild.md): + - : How to build Swift on Windows using Visual Studio. - - [WindowsCrossCompile.md](/docs/WindowsCrossCompile.md): + - : How to cross compile Swift for Windows on a non-Windows host OS. - Building for OpenBSD: - - [OpenBSD.md](/docs/OpenBSD.md): + - : Overview of specific steps for building on OpenBSD. -- [RunningIncludeWhatYouUse.md](/docs/HowToGuides/RunningIncludeWhatYouUse.md): +- : Describes how to run [include-what-you-use](https://include-what-you-use.org) on the Swift project. ## Explanations -- [WebAssembly.md](/docs/WebAssembly.md): +- : Explains some decisions that were made while implementing the WebAssembly target. ### Compiler and Runtime Subsystems - Driver: - - [Driver.md](/docs/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](/docs/DriverInternals.md): + - : Provides a bird's eye view of the driver's implementation. -- [DependencyAnalysis.md](/docs/DependencyAnalysis.md): +- : Describes different kinds of dependencies across files in the same module, important for understanding incremental builds. -- [DifferentiableProgrammingImplementation.md](/docs/DifferentiableProgrammingImplementation.md): +- : Describes how automatic differentiation is implemented in the Swift compiler. - C and ObjC interoperability: Clang Importer and PrintAsClang - - [CToSwiftNameTranslation.md](/docs/CToSwiftNameTranslation.md): + - : Describes how C and ObjC entities are imported into Swift by the Clang Importer. - - [CToSwiftNameTranslation-OmitNeedlessWords.md](/docs/CToSwiftNameTranslation-OmitNeedlessWords.md): + - : Describes how the "Omit Needless Words" algorithm works, making imported names more idiomatic. - Type-checking and inference: - - [TypeChecker.md](/docs/TypeChecker.md): + - : Provides an overview of how type-checking and inference work. - - [RequestEvaluator.md](/docs/RequestEvaluator.md): + - : Describes the request evaluator architecture, which is used for lazy type-checking and efficient caching. - - [Literals.md](/docs/Literals.md): + - : Describes type-checking and inference specifically for literals. -- [Serialization.md](/docs/Serialization.md): +- : Gives an overview of the LLVM bitcode format used for swiftmodules. - - [StableBitcode.md](/docs/StableBitcode.md): + - : Describes how to maintain compatibility when changing the serialization format. - SIL and SIL Optimizations: - - [SILFunctionConventions.md](/docs/SIL/SILFunctionConventions.md): - - [SILMemoryAccess.md](/docs/SIL/SILMemoryAccess.md): - - [OptimizerDesign.md](/docs/OptimizerDesign.md): + - : + - : + - : Describes the design of the optimizer pipeline. - [HighLevelSILOptimizations.rst](/docs/HighLevelSILOptimizations.rst): Describes how the optimizer understands the semantics of high-level @@ -143,18 +147,18 @@ documentation, please create a thread on the Swift forums under the ### SourceKit subsystems -- [SwiftLocalRefactoring.md](/docs/refactoring/SwiftLocalRefactoring.md): +- : Describes how refactorings work and how they can be tested. ### Language subsystems - Swift's Object Model - - [LogicalObjects.md](/docs/LogicalObjects.md): + - : Describes the differences between logical and physical objects and introduces materialization and writeback. - [MutationModel.rst](/docs/MutationModel.rst): Outdated. -- [DocumentationComments.md](/docs/DocumentationComments.md): +- : Describes the format of Swift's documentation markup, including specially-recognized sections. @@ -168,25 +172,25 @@ documentation, please create a thread on the Swift forums under the ## Reference Guides -- [DriverParseableOutput.md](/docs/DriverParseableOutput.md): +- : Describes the output format of the driver's `-parseable-output` flag, which is suitable for consumption by editors and IDEs. -- [ObjCInterop.md](/docs/ObjCInterop.md) +- Documents how Swift interoperates with ObjC code and the ObjC runtime. - [LibraryEvolution.rst](/docs/LibraryEvolution.rst): Specifies what changes can be made without breaking binary compatibility. - [SIL.md](/docs/SIL/SIL.md): Documents the Swift Intermediate Language (SIL). - - [TransparentAttr.md](/docs/TransparentAttr.md): + - : Documents the semantics of the `@_transparent` attribute. -- [DynamicCasting.md](/docs/DynamicCasting.md): +- : Behavior of the dynamic casting operators `is`, `as?`, and `as!`. -- [Runtime.md](/docs/Runtime.md): +- : Describes the ABI interface to the Swift runtime. -- [Lexicon.md](/docs/Lexicon.md): +- : Canonical reference for terminology used throughout the project. -- [UnderscoredAttributes.md](/docs/ReferenceGuides/UnderscoredAttributes.md): +- : Documents semantics for underscored (unstable) attributes. ### ABI @@ -197,10 +201,10 @@ documentation, please create a thread on the Swift forums under the where further detail is required. - [CallingConvention.rst](/docs/ABI/CallingConvention.rst): Describes in detail the Swift calling convention. -- [GenericSignature.md](/docs/ABI/GenericSignature.md): +- : Describes what generic signatures are and how they are used in the ABI, including the algorithms for minimization and canonicalization. -- [KeyPaths.md](/docs/ABI/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, @@ -219,16 +223,16 @@ documentation, please create a thread on the Swift forums under the ### Coding -- [AccessControlInStdlib.md](/docs/AccessControlInStdlib.md): +- : Describes the policy for access control modifiers and related naming conventions in the stdlib. -- [IndexInvalidation.md](/docs/IndexInvalidation.md): +- : Describes the expected behavior of indexing APIs exposed by the stdlib. - [StdlibAPIGuidelines.rst](/docs/StdlibAPIGuidelines.rst): Provides guidelines for designing stdlib APIs. -- [StandardLibraryProgrammersManual.md](/docs/StandardLibraryProgrammersManual.md): +- : Provides guidelines for working code in the stdlib. - [OptimizationTips.rst](/docs/OptimizationTips.rst): Provides guidelines for writing high-performance Swift code. @@ -237,9 +241,9 @@ documentation, please create a thread on the Swift forums under the ## Project Information -- [Branches.md](/docs/Branches.md): +- : Describes how different branches are setup and what the automerger does. -- [ContinuousIntegration.md](/docs/ContinuousIntegration.md): +- : Describes the continuous integration setup, including the `@swift_ci` bot. ## Evolution Documents @@ -247,22 +251,22 @@ documentation, please create a thread on the Swift forums under the ### Manifestos - ABI Stability and Library Evolution - - [ABIStabilityManifesto.md](/docs/ABIStabilityManifesto.md): + - : Describes the goals and design for ABI stability. - - [LibraryEvolutionManifesto.md](/docs/LibraryEvolutionManifesto.md): + - : Describes the goals and design for Library Evolution. -- [BuildManifesto.md](/docs/BuildManifesto.md): +- : Provides an outline for modularizing the build system for the Swift toolchain. -- [CppInteroperabilityManifesto.md](/docs/CppInteroperability/CppInteroperabilityManifesto.md): +- : Describes the motivation and design for first-class Swift-C++ interoperability. -- [DifferentiableProgramming.md](/docs/DifferentiableProgramming.md): +- : Outlines a vision and design for first-class differentiable programming in Swift. -- [GenericsManifesto.md](/docs/GenericsManifesto.md): +- : Communicates a vision for making the generics system in Swift more powerful. -- [OwnershipManifesto.md](/docs/OwnershipManifesto.md): +- : Provides a framework for understanding ownership in Swift, and highlights potential future directions for the language. -- [StringManifesto.md](/docs/StringManifesto.md): +- : Provides a long-term vision for the `String` type. ### Proposals @@ -279,10 +283,10 @@ You can see the status of different proposals at - [CallingConvention.rst](/docs/ABI/CallingConvention.rst): This whitepaper discusses the Swift calling convention (high-level semantics; ownership transfer; physical representation; function signature lowering). -- [ErrorHandlingRationale.md](/docs/ErrorHandlingRationale.md): +- : Surveys error-handling in a variety of languages, and describes the rationale behind the design of error handling in Swift. -- [WeakReferences.md](/docs/WeakReferences.md): +- : Discusses weak references, including the designs in different languages, and proposes changes to Swift (pre-1.0). @@ -293,11 +297,11 @@ 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. -- [AccessControl.md](/docs/AccessControl.md) -- [Arrays.md](/docs/Arrays.md) +- +- - [Generics.rst](/docs/archive/Generics.rst) -- [ErrorHandling.md](/docs/ErrorHandling.md) +- - [StringDesign.rst](/docs/StringDesign.rst) - [TextFormatting.rst](/docs/TextFormatting.rst) @@ -305,7 +309,7 @@ They are preserved mostly for historical interest. ## External Resources -External resources are listed in [ExternalResources.md](/docs/ExternalResources.md). +External resources are listed in . 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. @@ -318,47 +322,47 @@ 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.md](/docs/SIL/ARCOptimization.md): +- : 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](/docs/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](/docs/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](/docs/Diagnostics.md): +- : Describes how to write diagnostic messages and associated documentation. 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 diagnostic groups. -- [HowSwiftImportsCAPIs.md](/docs/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. -- [Modules.md](/docs/Modules.md): was written for Swift pre-1.0, but is still +- : was written for Swift pre-1.0, but is still relevant and covers behavior that's underspecified in either TSPL or the language reference. -- [OptimizerCountersAnalysis.md](/docs/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](/docs/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. -- [Random.md](/docs/Random.md): Stub. +- : Stub. ### Archive -- [FailableInitializers.md](/docs/FailableInitializers.md): +- : Superseded by documentation in [The Swift Programming Language][]. - [InitializerProblems.rst](/docs/InitializerProblems.rst): Describes some complexities around initialization in Swift. @@ -367,7 +371,7 @@ provide greater clarity to contributors wanting to add new documentation. `@_hasMissingDesignatedInitializers`. Some of this is covered in [TSPL's initialization section][] but that doesn't include newly added attributes. -- [Swift3Compatibility.md](/docs/Swift3Compatibility.md): +- : Discusses the Swift 3 -> Swift 4 migration. - [StoredAndComputedVariables.rst](/docs/StoredAndComputedVariables.rst): for Swift pre-1.0. diff --git a/docs/Swift3Compatibility.md b/docs/Swift3Compatibility.md index 23d52a870a5f3..d3d6cfa20cac1 100644 --- a/docs/Swift3Compatibility.md +++ b/docs/Swift3Compatibility.md @@ -1,4 +1,8 @@ -Background: We expect many changes in Objective-C APIs between Swift 3 and Swift 4, but our primary goal is to allow an app to upgrade to Swift 4 without having to update its dependencies. This necessarily means that a Swift 4 app needs to be able to use Swift 3 APIs, where "use" includes: +# Swift 3 Compatibility + +Background: We expect many changes in Objective-C APIs between Swift 3 and Swift 4. + +Our primary goal is to allow an app to upgrade to Swift 4 without having to update its dependencies. This necessarily means that a Swift 4 app needs to be able to use Swift 3 APIs, where "use" includes: - call (a method, property accessor, etc) - subclass (an open class) diff --git a/test/Documentation/docc.swift b/test/Documentation/docc.swift new file mode 100644 index 0000000000000..72ef6f944bdc0 --- /dev/null +++ b/test/Documentation/docc.swift @@ -0,0 +1,13 @@ +// REQUIRES: OS=macosx + +// RUN: %empty-directory(%t) +// RUN: mv "$(dirname %utils)/docs" "$(dirname %utils)/docs.docc" +// RUN: plutil -create xml1 "$(dirname %utils)/docs.docc/Info.plist" +// RUN: plutil -insert CFBundleDisplayName -string "Swift Compiler Documentation" "$(dirname %utils)/docs.docc/Info.plist" +// RUN: plutil -insert CFBundleIdentifier -string "org.swift.compiler-documentation" "$(dirname %utils)/docs.docc/Info.plist" +// RUN: xcrun docc convert --output-path %t $(dirname %utils)/docs.docc +// RUN: mv $(dirname %utils)/docs.docc $(dirname %utils)/docs + +// the generated bundle should be at least as big as all of the markdown files in the source directory +// RUN: test $(du -c %t | tail -1 | awk '{ print $1 }') -gt $(du -c $(dirname %utils)/docs/*.md | tail -1 | awk '{ print $1 }') && echo success +// CHECK: success