Merge pull request #143 from bnbarham/swiftpm-version-details

Add more details for packages that need to support old Swift versions

Author: ktoso

Guide.docc/Swift6Mode.md

@@ -25,12 +25,10 @@ invocation using the `-Xswiftc` flag:
 
 ### Package manifest
 
-A `Package.swift` file that uses `swift-tools-version` of `6.0` will enable
-the Swift 6 language mode for all targets.
-You can still set the language mode for the package as a whole using the 
-`swiftLanguageVersions` property of `Package`.
-However, you can now also change the language mode as needed on a
-per-target basis using the new `swiftLanguageVersion` build setting:
+A `Package.swift` file that uses `swift-tools-version` of `6.0` will enable the Swift 6 language
+mode for all targets. You can still set the language mode for the package as a whole using the
+`swiftLanguageModes` property of `Package`. However, you can now also change the language mode as
+needed on a per-target basis using the new `swiftLanguageMode` build setting:
 
 ```swift
 // swift-tools-version: 6.0
@@ -41,7 +39,7 @@ let package = Package(
         // ...
     ],
     targets: [
-        // Uses the default tools language mode
+        // Uses the default tools language mode (6)
         .target(
             name: "FullyMigrated",
         ),
@@ -56,9 +54,79 @@ let package = Package(
 )
 ```
 
+Note that if your package needs to continue supporting earlier Swift toolchain versions and you want
+to use per-target `swiftLanguageMode`, you will need to create a version-specific manifest for pre-6
+toolchains. For example, if you'd like to continue supporting 5.9 toolchains and up, you could have
+one manifest `[email protected]`:
+```swift
+// swift-tools-version: 5.9
+
+let package = Package(
+    name: "MyPackage",
+    products: [
+        // ...
+    ],
+    targets: [
+        .target(
+            name: "FullyMigrated",
+        ),
+        .target(
+            name: "NotQuiteReadyYet",
+        )
+    ]
+)
+```
+
+And another `Package.swift` for Swift toolchains 6.0+:
+```swift
+// swift-tools-version: 6.0
+
+let package = Package(
+    name: "MyPackage",
+    products: [
+        // ...
+    ],
+    targets: [
+        // Uses the default tools language mode (6)
+        .target(
+            name: "FullyMigrated",
+        ),
+        // Still requires 5
+        .target(
+            name: "NotQuiteReadyYet",
+            swiftSettings: [
+                .swiftLanguageMode(.v5)
+            ]
+        )
+    ]
+)
+```
+
+If instead you would just like to use Swift 6 language mode when it's available (while still
+continuing to support older modes) you can keep a single `Package.swift` and specify the version in
+a compatible manner:
+```swift
+// swift-tools-version: 5.9
+
+let package = Package(
+    name: "MyPackage",
+    products: [
+        // ...
+    ],
+    targets: [
+        .target(
+            name: "FullyMigrated",
+        ),
+    ],
+    // `swiftLanguageVersions` and `.version("6")` to support pre 6.0 swift-tools-version.
+    swiftLanguageVersions: [.version("6"), .v5]
+)
+```
+
+
 ## Using Xcode
 
-### Build Settings 
+### Build Settings
 
 You can control the language mode for an Xcode project or target by setting
 the "Swift Language Version" build setting to "6".