Merge branch 'master' into verifier-wording-fix

Author: owenv

.gitignore

@@ -22,6 +22,7 @@
 #==============================================================================#
 # Explicit files to ignore (only matches one).
 #==============================================================================#
+Brewfile.lock.json
 cscope.files
 cscope.out
 .vimrc

Brewfile

@@ -0,0 +1,2 @@
+brew "cmake"
+brew "ninja"

CHANGELOG.md

@@ -6,7 +6,8 @@ CHANGELOG
 
 | Version                | Released   | Toolchain   |
 | :--------------------- | :--------- | :---------- |
-| [Swift 5.2](#swift-52) |            |             |
+| [Swift 5.3](#swift-53) |            |             |
+| [Swift 5.2](#swift-52) | 2020-03-24 | Xcode 11.4  |
 | [Swift 5.1](#swift-51) | 2019-09-20 | Xcode 11.0  |
 | [Swift 5.0](#swift-50) | 2019-03-25 | Xcode 10.2  |
 | [Swift 4.2](#swift-42) | 2018-09-17 | Xcode 10.0  |
@@ -23,9 +24,25 @@ CHANGELOG
 
 </details>
 
-Swift Next
+Swift 5.3
 ----------
 
+* [SE-0280][]:
+  
+  Enum cases can now satisfy static protocol requirements. A static get-only property of type `Self` can be witnessed by an enum case with no associated values and a static function with arguments and returning `Self` can be witnessed by an enum case with associated values.
+  
+  ```swift
+  protocol P {
+    static var foo: Self { get }
+    static func bar(value: Int) -> Self
+  }
+  
+  enum E: P {
+    case foo // matches 'static var foo'
+    case bar(value: Int) // matches 'static func bar(value:)'
+  }
+  ```
+
 * [SE-0267][]:
 
   Non-generic members that support a generic parameter list, including nested type declarations, are now allowed to carry a contextual `where` clause against outer generic parameters. Previously, such declarations could only be expressed by placing the member inside a dedicated constrained extension.
@@ -49,15 +66,15 @@ Swift Next
 
 * [SR-75][]:
 
-  Unapplied references to protocol methods methods are now supported. Previously this
+  Unapplied references to protocol methods are now supported. Previously this
   only worked for methods defined in structs, enums and classes.
 
   ```swift
   protocol Cat {
     func play(catToy: Toy)
   }
 
-  let fn = Cat.play
+  let fn = Cat.play(catToy:)
   fn(myCat)(myToy)
   ```
 
@@ -97,9 +114,13 @@ Swift Next
   closure's capture list in addition to the existing 'use `self.` explicitly'
   fix-it.
 
+**Add new entries to the top of this section, not here!**
+
 Swift 5.2
 ---------
 
+### 2020-03-24 (Xcode 11.4)
+
 * [SR-11841][]:
 
   When chaining calls to `filter(_:)` on a lazy sequence or collection, the
@@ -292,8 +313,6 @@ Swift 5.2
   print(s[0])
   ```
 
-**Add new entries to the top of this section, not here!**
-
 Swift 5.1
 ---------
 
@@ -7951,6 +7970,7 @@ Swift 1.0
 [SE-0266]: <https://github.com/apple/swift-evolution/blob/master/proposals/0266-synthesized-comparable-for-enumerations.md>
 [SE-0267]: <https://github.com/apple/swift-evolution/blob/master/proposals/0267-where-on-contextually-generic.md>
 [SE-0269]: <https://github.com/apple/swift-evolution/blob/master/proposals/0269-implicit-self-explicit-capture.md>
+[SE-0280]: <https://github.com/apple/swift-evolution/blob/master/proposals/0280-enum-cases-as-protocol-witnesses.md>
 
 [SR-75]: <https://bugs.swift.org/browse/SR-75>
 [SR-106]: <https://bugs.swift.org/browse/SR-106>

CMakeLists.txt

@@ -1027,13 +1027,11 @@ if(SWIFT_BUILD_SYNTAXPARSERLIB OR SWIFT_BUILD_SOURCEKIT)
       set(SOURCEKIT_RUNTIME_DIR lib)
     endif()
     add_dependencies(sourcekit-inproc BlocksRuntime dispatch)
-    if("${SWIFT_HOST_VARIANT_SDK}" MATCHES "OSX|WINDOWS")
-      swift_install_in_component(FILES
-                                   $<TARGET_FILE:dispatch>
-                                   $<TARGET_FILE:BlocksRuntime>
-                                 DESTINATION ${SOURCEKIT_RUNTIME_DIR}
-                                 COMPONENT sourcekit-inproc)
-    endif()
+    swift_install_in_component(FILES
+                                 $<TARGET_FILE:dispatch>
+                                 $<TARGET_FILE:BlocksRuntime>
+                               DESTINATION ${SOURCEKIT_RUNTIME_DIR}
+                               COMPONENT sourcekit-inproc)
     if(SWIFT_HOST_VARIANT_SDK STREQUAL WINDOWS)
       swift_install_in_component(FILES
                                    $<TARGET_LINKER_FILE:dispatch>

README.md

@@ -91,7 +91,7 @@ Please make sure you use Python 2.x. Python 3.x is not supported currently.
 
 #### macOS
 
-To build for macOS, you need [Xcode 11.3](https://developer.apple.com/xcode/downloads/).
+To build for macOS, you need [Xcode 11.4](https://developer.apple.com/xcode/downloads/).
 The required version of Xcode changes frequently, and is often a beta release.
 Check this document or the host information on <https://ci.swift.org> for the
 current required version.
@@ -102,6 +102,12 @@ which can be installed via a package manager:
 **[Homebrew](https://brew.sh/)**
 
     brew install cmake ninja
+    
+You can also use [homebrew-bundle](https://github.com/Homebrew/homebrew-bundle)
+from the root of this repository's working directory to install all of these
+dependencies:
+
+    brew bundle
 
 **[MacPorts](https://macports.org)**
 
@@ -359,7 +365,7 @@ expressed today.
 
 ### CMake
 [CMake](https://cmake.org) is the core infrastructure used to configure builds of
-Swift and its companion projects; at least version 3.4.3 is required.
+Swift and its companion projects; at least version 3.16.5 is required.
 
 On macOS, you can download the [CMake Binary Distribution](https://cmake.org/download),
 bundled as an application, copy it to `/Applications`, and add the embedded

benchmark/utils/ObjectiveCTests/module.map renamed to benchmark/utils/ObjectiveCTests/module.modulemap

@@ -517,6 +517,10 @@ Types
   FUNCTION-KIND ::= 'C'                      // C function pointer type
   FUNCTION-KIND ::= 'A'                      // @auto_closure function type (escaping)
   FUNCTION-KIND ::= 'E'                      // function type (noescape)
+  FUNCTION-KIND ::= 'F'                      // @differentiable function type
+  FUNCTION-KIND ::= 'G'                      // @differentiable function type (escaping)
+  FUNCTION-KIND ::= 'H'                      // @differentiable(linear) function type
+  FUNCTION-KIND ::= 'I'                      // @differentiable(linear) function type (escaping)
 
   function-signature ::= params-type params-type throws? // results and parameters
 
@@ -585,14 +589,18 @@ mangled in to disambiguate.
   impl-function-type ::= type* 'I' FUNC-ATTRIBUTES '_'
   impl-function-type ::= type* generic-signature 'I' FUNC-ATTRIBUTES '_'
 
-  FUNC-ATTRIBUTES ::= PATTERN-SUBS? INVOCATION-SUBS? PSEUDO-GENERIC? CALLEE-ESCAPE? CALLEE-CONVENTION FUNC-REPRESENTATION? COROUTINE-KIND? PARAM-CONVENTION* RESULT-CONVENTION* ('Y' PARAM-CONVENTION)* ('z' RESULT-CONVENTION)?
+  FUNC-ATTRIBUTES ::= PATTERN-SUBS? INVOCATION-SUBS? PSEUDO-GENERIC? CALLEE-ESCAPE? DIFFERENTIABILITY-KIND? CALLEE-CONVENTION FUNC-REPRESENTATION? COROUTINE-KIND? PARAM-CONVENTION* RESULT-CONVENTION* ('Y' PARAM-CONVENTION)* ('z' RESULT-CONVENTION)?
 
   PATTERN-SUBS ::= 's'                       // has pattern substitutions
   INVOCATION-SUB ::= 'I'                     // has invocation substitutions
   PSEUDO-GENERIC ::= 'P'
 
   CALLEE-ESCAPE ::= 'e'                      // @escaping (inverse of SIL @noescape)
 
+  DIFFERENTIABILITY-KIND ::= DIFFERENTIABLE | LINEAR
+  DIFFERENTIABLE ::= 'd'                     // @differentiable
+  LINEAR ::= 'l'                             // @differentiable(linear)
+
   CALLEE-CONVENTION ::= 'y'                  // @callee_unowned
   CALLEE-CONVENTION ::= 'g'                  // @callee_guaranteed
   CALLEE-CONVENTION ::= 'x'                  // @callee_owned

docs/ABI/Mangling.rst

@@ -570,7 +570,7 @@ compilers on hand while you're working.
     Total Execution Time: 0.0876 seconds (0.0877 wall clock)
 
      ---User Time---   --System Time--   --User+System--   ---Wall Time---  --- Name ---
-     0.0241 ( 53.9%)   0.0394 ( 92.0%)   0.0635 ( 72.5%)   0.0635 ( 72.5%)  Name binding
+     0.0241 ( 53.9%)   0.0394 ( 92.0%)   0.0635 ( 72.5%)   0.0635 ( 72.5%)  Import resolution
      0.0170 ( 38.0%)   0.0025 (  5.8%)   0.0195 ( 22.3%)   0.0195 ( 22.2%)  Type checking / Semantic analysis
      0.0013 (  3.0%)   0.0004 (  0.8%)   0.0017 (  1.9%)   0.0017 (  1.9%)  LLVM output
      0.0010 (  2.3%)   0.0003 (  0.7%)   0.0013 (  1.5%)   0.0013 (  1.5%)  SILGen

docs/CompilerPerformance.md

@@ -1103,7 +1103,7 @@ public:
 // C++ header imported in Swift.
 
 struct Employee {
-  func mutable_name() -> UnsafeMutablePointer<std.string>
+  func mutable_company() -> UnsafeMutablePointer<std.string>
 }
 ```
 
@@ -1536,7 +1536,7 @@ public moveonly struct File {
 
 func useArrayOfFiles() {
   var files: [File] = ...
-  consumeFile(files[0].move())
+  consumeFile(files[0].cxxMove())
 }
 ```
 

docs/CppInteroperabilityManifesto.md

@@ -164,22 +164,66 @@ Debugging on SIL Level
 Options for Dumping the SIL
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Often it is not sufficient to dump the SIL at the beginning or end of the
-optimization pipeline.
-The SILPassManager supports useful options to dump the SIL also between
-pass runs.
+Often it is not sufficient to dump the SIL at the beginning or end of
+the optimization pipeline. The SILPassManager supports useful options
+to dump the SIL also between pass runs.
 
-The option ``-Xllvm -sil-print-all`` dumps the whole SIL module after all
-passes. Although it prints only functions which were changed by a pass, the
-output can get *very* large.
+The SILPassManager's SIL dumping options vary along two orthogonal
+functional axes:
 
-It is useful if you identified a problem in the final SIL and you want to
-check which pass did introduce the wrong SIL.
+1. Options that control if functions/modules are printed.
+2. Options that filter what is printed at those points.
 
-There are several other options available, e.g. to filter the output by
-function names (``-Xllvm -sil-print-only-function``/``s``) or by pass names
-(``-Xllvm -sil-print-before``/``after``/``around``).
-For details see ``PassManager.cpp``.
+One generally always specifies an option of type 1 and optionally adds
+an option of type 2 to filter the output.
+
+A short (non-exhaustive) list of type 1 options:
+
+* ``-Xllvm -sil-print-all``: Print functions/modules when ever a
+  function pass modifies a function and Print the entire module
+  (modulo filtering) if a module pass modifies a SILModule.
+
+A short (non-exhaustive) list of type 2 options:
+
+* ``-Xllvm -sil-print-around=$PASS_NAME``: Print a function/module
+  before and after a function pass with name ``$PASS_NAME`` runs on a
+  function/module or dump a module before a module pass with name
+  ``$PASS_NAME`` runs on a module.
+
+* ``-Xllvm -sil-print-before=$PASS_NAME``: Print a function/module
+  before a function pass with name ``$PASS_NAME`` runs on a
+  function/module or dump a module before a module pass with name
+  ``$PASS_NAME`` runs on a module. NOTE: This happens even without
+  sil-print-all set!
+
+* ``-Xllvm -sil-print-after=$PASS_NAME``: Print a function/module
+  after a function pass with name ``$PASS_NAME`` runs on a
+  function/module or dump a module before a module pass with name
+  ``$PASS_NAME`` runs on a module.
+
+* ``-Xllvm '-sil-print-only-function=SWIFT_MANGLED_NAME'``: When ever
+  one would print a function/module, only print the given function.
+
+These options together allow one to visualize how a
+SILFunction/SILModule is optimized by the optimizer as each
+optimization pass runs easily via formulations like::
+
+    swiftc -Xllvm '-sil-print-only-function=$myMainFunction' -Xllvm -sil-print-all
+
+NOTE: This may emit a lot of text to stderr, so be sure to pipe the
+output to a file.
+
+Getting CommandLine for swift stdlib from Ninja
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If one builds swift using ninja and wants to dump the SIL of the
+stdlib using some of the SIL dumping options from the previous
+section, one can use the following one-liner::
+
+  ninja -t commands | grep swiftc | grep Swift.o | grep " -c "
+
+This should give one a single command line that one can use for
+Swift.o, perfect for applying the previous sections options to.
 
 Dumping the SIL and other Data in LLDB
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -359,6 +403,17 @@ we know to ignore swift_getGenericMetadata 84 times, i.e.::
 
     (lldb) br set -i 84 -n GlobalARCOpts::run
 
+A final trick is that one can use the -R option to stop at a relative assembly
+address in lldb. Specifically, lldb resolves the breakpoint normally and then
+just adds the argument -R to the address. So for instance, if I want to stop at
+the address at +38 in the function with the name 'foo', I would write::
+
+    (lldb) br set -R 38 -n foo
+
+Then lldb would add 38 to the offset of foo and break there. This is really
+useful in contexts where one wants to set a breakpoint at an assembly address
+that is stable across multiple different invocations of lldb.
+
 LLDB Scripts
 ~~~~~~~~~~~~
 

docs/DebuggingTheCompiler.rst

@@ -92,23 +92,34 @@ Most diagnostics have no reason to change behavior under editor mode. An example
 
 ### Educational Notes ###
 
-**Note**: This feature is currently experimental. It can be enabled by passing the `-Xfrontend -enable-descriptive-diagnostics` flag.
+Educational notes are short-form documentation attached to a diagnostic which explain relevant language concepts. They are intended to further Swift's goal of progressive disclosure by providing a learning resource at the point of use when encountering an error message for the first time. In very limited circumstances, they also allow the main diagnostic message to use precise terminology (e.g. nominal types) which would otherwise be too unfriendly for beginners.
 
-Educational notes are small snippets of documentation attached to a diagnostic which explain relevant language concepts. They are intended to further Swift's goal of progressive disclosure by providing a learning resource at the point of use for users encountering a new error message for the first time. In very limited circumstances, they also allow the main diagnostic message to use more precise and correct terminology (e.g. nominal types) which would otherwise be too unfriendly for beginners.
+When outputting diagnostics on the command line, educational notes will be printed after the main diagnostic body if enabled using the `-print-educational-notes` driver option. When presented in an IDE, it's expected they will be collapsed under a disclosure arrow, info button, or similar to avoid cluttering output.
 
-When outputting diagnostics on the command line, educational notes will be printed after the main diagnostic body if descriptive diagnostics are enabled. When presented in an IDE, it's expected they will be collapsed under a disclosure arrow, info button, or similar to avoid cluttering output.
-
-Generally speaking, a diagnostic should try to provide educational notes for any concepts/terminology which is difficult to understand from context or is especially subtle. Educational notes should:
-- Explain a single language concept. This makes them easy to reuse across diagnostics and helps keep them clear, concise, and easy to understand.
-- Be written in unabbreviated English. These are longer form messages compared to the main diagnostic, so there is no need to omit needless words and punctuation.
-- Not generally exceed 3-4 paragraphs. Educational notes should be clear and easily digestible. Messages which are too long also have the potential to create diagnostics UX issues in some contexts.
+Educational notes should:
+- Explain a single language concept. This makes them easy to reuse across related diagnostics and helps keep them clear, concise, and easy to understand.
+- Be written in unabbreviated English. These are longer-form messages compared to the main diagnostic, so there's no need to omit needless words and punctuation.
+- Not generally exceed 3-4 paragraphs. Educational notes should be clear and easily digestible. Messages which are too long also have the potential to create UX issues on the command line.
 - Be accessible. Educational notes should be beginner friendly and avoid assuming unnecesary prior knowledge. The goal is not only to help users understand what a diagnostic is telling them, but also to turn errors and warnings into "teachable moments".
-- Include references to relevant chapters of _The Swift Programming Language_ if applicable.
-- Be written in Markdown, but avoid excessive markup to avoid impacting the terminal UX. 
+- Include references to relevant chapters of _The Swift Programming Language_.
+- Be written in Markdown, but avoid excessive markup which negatively impacts the terminal UX.
+
+### Quick-Start Guide for Contributing New Educational Notes ###
+
+Adding new educational notes is a great way to get familiar with the process of contributing to Swift, while also making a big impact!
 
 To add a new educational note:
-1. Add a new Markdown file in the `userdocs/diagnostics/` directory containing the contents of the note. 
-2. Associate the note with one or more diagnostics in EducationalNotes.def.
+1. Follow the [directions in the README](https://github.com/apple/swift#getting-sources-for-swift-and-related-projects) to checkout the Swift sources locally. Being able to build the Swift compiler is recommended, but not required, when contributing a new note.
+2. Identify a diagnostic to write an educational note for. To associate an educational note with a diagnostic name, you'll need to know its internal identifier. The easiest way to do this is to write a small program which triggers the diagnostic, and run it using the `-debug-diagnostic-names` compiler flag. This flag will cause the internal diagnostic identifier to be printed after the diagnostic message in square brackets.
+3. Find any closely related diagnostics. Sometimes, what appears to be one diagnostic from a user's perspective may have multiple variations internally. After determining a diagnostic's internal identifier, run a search for it in the compiler source. You should find:
+    - An entry in a `Diagnostics*.def` file describing the diagnostic. If there are any closely related diagnostics the note should also be attached to, they can usually be found nearby.
+    - Each point in the compiler source where the diagnostic is emitted. This can be helpful in determining the exact circumstances which cause it to be emitted.
+4. Add a new Markdown file in the `userdocs/diagnostics/` directory in the swift repository containing the contents of the note. When writing a note, keep the writing guidelines from the section above in mind. The existing notes in the directory are another useful guide.
+5. Associate the note with the appropriate diagnostics in `EducationalNotes.def`. An entry like `EDUCATIONAL_NOTES(property_wrapper_failable_init, "property-wrapper-requirements.md")` will associate the note with filename `property-wrapper-requirements.md` with the diagnostic having an internal identifier of `property_wrapper_failable_init`.
+6. If possible, rebuild the compiler and try recompiling your test program with `-print-educational-notes`. Your new note should appear after the diagnostic in the terminal.
+7. That's it! The new note is now ready to be submitted as a pull request on GitHub.
+
+If you run into any issues or have questions while following the steps above, feel free to post a question on the Swift forums or open a work-in-progress pull request on GitHub.
 
 ### Format Specifiers ###