Merge main to 6.2

.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+xcode_trim_whitespace_on_empty_lines = true
+
+[*.{yml,yaml}]
+indent_size = 2

CONTRIBUTING.md

@@ -88,7 +88,7 @@ $> swift --version
 Apple Swift version 5.3
 ```
 
-Note: Alternatively use tools like [swiftenv](https://github.com/kylef/swiftenv) that help manage toolchains versions.
+Note: Alternatively use tools like [swiftly](https://www.swift.org/swiftly/documentation/swiftlydocs/) that help manage toolchains versions.
 
 ## Local Development
 

Documentation/Usage.md

@@ -497,7 +497,7 @@ This feature is intended for use in the following scenarios:
 
 It is *not* expected that the packages would ever use this feature unless absolutely
 necessary to support existing clients. Specifically, packages *should not*
-adopt this syntax for tagging versions supporting the _latest GM_ Swift
+adopt this syntax for tagging versions supporting the _latest released_ Swift
 version.
 
 The package manager supports looking for any of the following marked tags, in
@@ -511,7 +511,7 @@ order of preference:
 
 The package manager will additionally look for a version-specific marked
 manifest version when loading the particular version of a package, by searching
-for a manifest in the form of `Package@swift-3.swift`. The set of markers
+for a manifest in the form of `Package@swift-6.swift`. The set of markers
 looked for is the same as for version-specific tag selection.
 
 This feature is intended for use in cases where a package wishes to maintain
@@ -521,20 +521,28 @@ changes in the manifest API).
 
 It is *not* expected the packages would ever use this feature unless absolutely
 necessary to support existing clients. Specifically, packages *should not*
-adopt this syntax for tagging versions supporting the _latest GM_ Swift
+adopt this syntax for tagging versions supporting the _latest released_ Swift
 version.
 
 In case the current Swift version doesn't match any version-specific manifest,
 the package manager will pick the manifest with the most compatible tools
 version. For example, if there are three manifests:
 
-`Package.swift` (tools version 3.0)
-`Package@swift-4.swift` (tools version 4.0)
-`Package@swift-4.2.swift` (tools version 4.2)
+- `Package.swift` (tools version 6.0)
+- `Package@swift-5.10.swift` (tools version 5.10)
+- `Package@swift-5.9.swift` (tools version 5.9)
 
-The package manager will pick `Package.swift` on Swift 3, `Package@swift-4.swift` on
-Swift 4, and `Package@swift-4.2.swift` on Swift 4.2 and above because its tools
-version will be most compatible with future version of the package manager.
+The package manager will pick `Package.swift` on Swift 6 and above, because its
+tools version will be most compatible with future version of the package manager.
+When using Swift 5.10, it will pick `Package@swift-5.10.swift`. Otherwise, when
+using Swift 5.9 it will pick `Package@swift-5.9.swift`, and this is the minimum
+tools version this package may be used with.
+
+A package may have versioned manifest files which specify newer tools versions
+than its unversioned `Package.swift` file[^1]. In this scenario, the manifest
+corresponding to the newest-compatible tools version will be used.
+
+[^1]: Support for having a versioned manifest file with a _newer_ tools version was required when the feature was first introduced, because prior versions of the package manager were not aware of the concept and only knew to look for the unversioned `Package.swift`. This is still supported, but there have been many Swift releases since the feature was introduced and it is now considered best practice to have `Package.swift` declare the newest-supported tools version and for versioned manifest files to only specifer older versions.
 
 ## Editing a Package
 

IntegrationTests/Sources/IntegrationTestSupport/Helpers.swift

@@ -14,6 +14,8 @@ import TSCBasic
 import TSCTestSupport
 import enum TSCUtility.Git
 
+public typealias ShReturnType = (stdout: String, stderr: String, returnCode: ProcessResult.ExitStatus)
+
 public let sdkRoot: AbsolutePath? = {
     if let environmentPath = ProcessInfo.processInfo.environment["SDK_ROOT"] {
         return try! AbsolutePath(validating: environmentPath)
@@ -106,7 +108,7 @@ public let lldb: AbsolutePath = {
 }()
 
 public let swiftpmBinaryDirectory: AbsolutePath = {
-    if let environmentPath = ProcessInfo.processInfo.environment["SWIFTPM_BIN_DIR"] {
+    if let environmentPath = ProcessInfo.processInfo.environment["SWIFTPM_CUSTOM_BIN_DIR"] {
         return try! AbsolutePath(validating: environmentPath)
     }
 
@@ -131,7 +133,7 @@ public func sh(
     env: [String: String] = [:],
     file: StaticString = #file,
     line: UInt = #line
-) throws -> (stdout: String, stderr: String) {
+) throws -> ShReturnType {
     let result = try _sh(arguments, env: env, file: file, line: line)
     let stdout = try result.utf8Output()
     let stderr = try result.utf8stderrOutput()
@@ -145,7 +147,7 @@ public func sh(
             )
     }
 
-    return (stdout, stderr)
+    return (stdout, stderr, result.exitStatus)
 }
 
 @discardableResult
@@ -154,7 +156,7 @@ public func shFails(
     env: [String: String] = [:],
     file: StaticString = #file,
     line: UInt = #line
-) throws -> (stdout: String, stderr: String) {
+) throws -> ShReturnType {
     let result = try _sh(arguments, env: env, file: file, line: line)
     let stdout = try result.utf8Output()
     let stderr = try result.utf8stderrOutput()
@@ -168,7 +170,7 @@ public func shFails(
             )
     }
 
-    return (stdout, stderr)
+    return (stdout, stderr, result.exitStatus)
 }
 
 @discardableResult
@@ -385,4 +387,4 @@ extension ProcessResult {
         \((try? utf8stderrOutput()) ?? "")
         """
     }
-}
+}

IntegrationTests/Tests/IntegrationTests/BasicTests.swift

@@ -94,7 +94,7 @@ private struct BasicTests {
     }
 
     @Test(
-        .skipHostOS(.windows, "'try!' expression unexpectedly raised an error: TSCBasic.Process.Error.missingExecutableProgram(program: \"which\")"),
+        .skipHostOS(.windows, "'try!' expression unexpectedly raised an error: TSCBasic.Process.Error.missingExecutableProgram(program: \"which\")")
     )
     func testSwiftCompiler() throws {
         try withTemporaryDirectory { tempDir in
@@ -124,22 +124,22 @@ private struct BasicTests {
             let packagePath = tempDir.appending(component: "Project")
             try localFileSystem.createDirectory(packagePath)
             try sh(swiftPackage, "--package-path", packagePath, "init", "--type", "executable")
-            let buildOutput = try sh(swiftBuild, "--package-path", packagePath).stdout
+            let packageOutput = try sh(swiftBuild, "--package-path", packagePath)
 
             // Check the build log.
-            let checker = StringChecker(string: buildOutput)
-            #expect(checker.check(.regex("Compiling .*Project.*")))
-            #expect(checker.check(.regex("Linking .*Project")))
-            #expect(checker.check(.contains("Build complete")))
+            let checker = StringChecker(string: packageOutput.stdout)
+            #expect(checker.check(.regex("Compiling .*Project.*")), "stdout: '\(packageOutput.stdout)'\n stderr:'\(packageOutput.stderr)'")
+            #expect(checker.check(.regex("Linking .*Project")), "stdout: '\(packageOutput.stdout)'\n stderr:'\(packageOutput.stderr)'")
+            #expect(checker.check(.contains("Build complete")), "stdout: '\(packageOutput.stdout)'\n stderr:'\(packageOutput.stderr)'")
 
             // Verify that the tool was built and works.
             let toolOutput = try sh(packagePath.appending(components: ".build", "debug", "Project"))
                 .stdout
             #expect(toolOutput.lowercased().contains("hello, world!"))
 
             // Check there were no compile errors or warnings.
-            #expect(buildOutput.contains("error") == false)
-            #expect(buildOutput.contains("warning") == false)
+            #expect(packageOutput.stdout.contains("error") == false)
+            #expect(packageOutput.stdout.contains("warning") == false)
         }
     }
 
@@ -151,17 +151,19 @@ private struct BasicTests {
             try localFileSystem.createDirectory(packagePath)
             withKnownIssue("error: no tests found; create a target in the 'Tests' directory") {
                 try sh(swiftPackage, "--package-path", packagePath, "init", "--type", "executable")
-                let testOutput = try sh(swiftTest, "--package-path", packagePath).stdout
+                let packageOutput = try sh(swiftTest, "--package-path", packagePath, "--vv")
 
                 // Check the test log.
-                let checker = StringChecker(string: testOutput)
-                #expect(checker.check(.regex("Compiling .*ProjectTests.*")))
-                #expect(checker.check("Test Suite 'All tests' passed"))
-                #expect(checker.checkNext("Executed 1 test"))
+                let checker = StringChecker(string: packageOutput.stdout)
+                #expect(checker.check(.regex("Compiling .*ProjectTests.*")), "stdout: '\(packageOutput.stdout)'\n stderr:'\(packageOutput.stderr)'")
+                #expect(checker.checkNext("Executed 1 test"), "stdout: '\(packageOutput.stdout)'\n stderr:'\(packageOutput.stderr)'")
+
+                // Check the return code
+                #expect(packageOutput.returnCode == .terminated(code: 0))
 
                 // Check there were no compile errors or warnings.
-                #expect(testOutput.contains("error") == false)
-                #expect(testOutput.contains("warning") == false)
+                #expect(packageOutput.stdout.contains("error") == false)
+                #expect(packageOutput.stdout.contains("warning") == false)
             }
         }
     }
@@ -192,17 +194,14 @@ private struct BasicTests {
             let packagePath = tempDir.appending(component: "Project")
             try localFileSystem.createDirectory(packagePath)
             try sh(swiftPackage, "--package-path", packagePath, "init", "--type", "library")
-            let testOutput = try sh(swiftTest, "--package-path", packagePath).stdout
+            let shOutput = try sh(swiftTest, "--package-path", packagePath)
 
-            // Check the test log.
-            let checker = StringChecker(string: testOutput)
-            #expect(checker.check(.contains("Test Suite 'All tests' started")))
-            #expect(checker.check(.contains("Test example() passed after")))
-            #expect(checker.checkNext(.contains("Test run with 1 test passed after")))
+            // Check the return code
+            #expect(shOutput.returnCode == .terminated(code: 0))
 
             // Check there were no compile errors or warnings.
-            #expect(testOutput.contains("error") == false)
-            #expect(testOutput.contains("warning") == false)
+            #expect(shOutput.stdout.contains("error") == false)
+            #expect(shOutput.stdout.contains("warning") == false)
         }
     }
 
@@ -248,11 +247,11 @@ private struct BasicTests {
             #expect(buildOutput.contains("Build complete"))
 
             // Verify that the tool exists and works.
-            let toolOutput = try sh(
+            let shOutput = try sh(
                 packagePath.appending(components: ".build", "debug", "special tool")
             ).stdout
 
-            #expect(toolOutput == "HI\(ProcessInfo.EOL)")
+            #expect(shOutput == "HI\(ProcessInfo.EOL)")
         }
     }
 
@@ -281,17 +280,20 @@ private struct BasicTests {
                     """
                 )
             )
-            let (runOutput, runError) = try sh(
+            let shOutput = try sh(
                 swiftRun, "--package-path", packagePath, "secho", "1", #""two""#
             )
 
             // Check the run log.
-            let checker = StringChecker(string: runError)
-            #expect(checker.check(.regex("Compiling .*secho.*")))
-            #expect(checker.check(.regex("Linking .*secho")))
-            #expect(checker.check(.contains("Build of product 'secho' complete")))
+            let checker = StringChecker(string: shOutput.stderr)
+            #expect(checker.check(.regex("Compiling .*secho.*")), "stdout: '\(shOutput.stdout)'\n stderr:'\(shOutput.stderr)'")
+            #expect(checker.check(.regex("Linking .*secho")),  "stdout: '\(shOutput.stdout)'\n stderr:'\(shOutput.stderr)'")
+            #expect(checker.check(.contains("Build of product 'secho' complete")),  "stdout: '\(shOutput.stdout)'\n stderr:'\(shOutput.stderr)'")
+
+            #expect(shOutput.stdout == "1 \"two\"\(ProcessInfo.EOL)")
 
-            #expect(runOutput == "1 \"two\"\(ProcessInfo.EOL)")
+            // Check the return code
+            #expect(shOutput.returnCode == .terminated(code: 0))
         }
     }
 
@@ -318,16 +320,16 @@ private struct BasicTests {
                     """
                 )
             )
-            let testOutput = try sh(
+            let shOutput = try sh(
                 swiftTest, "--package-path", packagePath, "--filter", "MyTests.*", "--skip",
-                "testBaz"
-            ).stderr
+                "testBaz", "--vv"
+            )
 
             // Check the test log.
-            let checker = StringChecker(string: testOutput)
-            #expect(checker.check(.contains("Test Suite 'MyTests' started")))
-            #expect(checker.check(.contains("Test Suite 'MyTests' passed")))
-            #expect(checker.check(.contains("Executed 2 tests, with 0 failures")))
+            let checker = StringChecker(string: shOutput.stderr)
+            #expect(checker.check(.contains("Test Suite 'MyTests' started")), "stdout: '\(shOutput.stdout)'\n stderr:'\(shOutput.stderr)'")
+            #expect(checker.check(.contains("Test Suite 'MyTests' passed")), "stdout: '\(shOutput.stdout)'\n stderr:'\(shOutput.stderr)'")
+            #expect(checker.check(.contains("Executed 2 tests, with 0 failures")), "stdout: '\(shOutput.stdout)'\n stderr:'\(shOutput.stderr)'")
         }
     }
 
@@ -410,15 +412,15 @@ private struct BasicTests {
                 )
             )
 
-            let testOutput = try sh(
-                swiftTest, "--package-path", packagePath, "--filter", "MyTests.*"
-            ).stdout
+            let shOutput = try sh(
+                swiftTest, "--package-path", packagePath, "--filter", "MyTests.*", "--vv"
+            )
 
             // Check the test log.
-            let checker = StringChecker(string: testOutput)
-            #expect(checker.check(.contains("Test Suite 'MyTests' started")))
-            #expect(checker.check(.contains("Test Suite 'MyTests' passed")))
-            #expect(checker.check(.contains("Executed 2 tests, with 0 failures")))
+            let checker = StringChecker(string: shOutput.stdout)
+            #expect(checker.check(.contains("Test Suite 'MyTests' started")), "stdout: '\(shOutput.stdout)'\n stderr:'\(shOutput.stderr)'")
+            #expect(checker.check(.contains("Test Suite 'MyTests' passed")), "stdout: '\(shOutput.stdout)'\n stderr:'\(shOutput.stderr)'")
+            #expect(checker.check(.contains("Executed 2 tests, with 0 failures")), "stdout: '\(shOutput.stdout)'\n stderr:'\(shOutput.stderr)'")
         }
     }
 }