From 0e9b8cf2893f7943d5be79cff450532b68ca8289 Mon Sep 17 00:00:00 2001 From: Felix Herrmann Date: Sun, 11 Feb 2024 20:34:33 +0100 Subject: [PATCH 1/2] Add SwiftPackageList 4 Migration Guide --- .../SwiftPackageList 4 Migration Guide.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 Documentation/Migrations/SwiftPackageList 4 Migration Guide.md diff --git a/Documentation/Migrations/SwiftPackageList 4 Migration Guide.md b/Documentation/Migrations/SwiftPackageList 4 Migration Guide.md new file mode 100644 index 0000000..acf6600 --- /dev/null +++ b/Documentation/Migrations/SwiftPackageList 4 Migration Guide.md @@ -0,0 +1,138 @@ +# SwiftPackageList 4 Migration Guide + +This guide eases the transition of the existing apps that use SwiftPackageList 3.x to the +latest version of the tool. + +### Minimum Requirements + +```diff +- Swift 5.7 ++ Swift 5.9 + + macOS 10.15 + Mac Catalyst 13.0 + iOS 13.0 + tvOS 13.0 + watchOS 6.0 ++ visionOS 1.0 +``` + +## `generate`/`scan` Subcommands and `stdout` Output Type + +The `generate` and `scan` command got merged together. This means there is no need for a +dedicated subcommand anymore and the CLI interface works like before the `scan` command +introduction: + +```shell +// SwiftPackageList 3 +swift-package-list generate Test.xcodeproj + +// SwiftPackageList 4 +swift-package-list Test.xcodeproj --output-type json +``` + +To provide the existing functionality from the `scan` command there is a new `stdout` +output-type which will print the output in JSON format to the console: + +```shell +// SwiftPackageList 3 +swift-package-list scan Test.xcodeproj + +// SwiftPackageList 4 +swift-package-list Test.xcodeproj --output-type stdout +``` +> [!IMPORTANT] +> `stdout` is now the default option so it is necessary to specify `--output-type json` +> for existing setups. + +## `Package.name` and `Package.identity` + +The behavior of the `name` field has changed, it will now use the name defined in the +Package.swift manifest instead of constructing it from the repository URL. This means that +the name is no longer guaranteed to be unique and should not be used for identification +purposes; to offer and alternative there is a new `identity` field, exposed from SPM: + +```json +// SwiftPackageList 3 +[ + { + "license" : "...", + "name" : "swift-package-manager", + "repositoryURL" : "https:\/\/github.com\/apple\/swift-package-manager", + "revision" : "f5ea3972d7d6c574e8bb16a19b2a7bca98ea131b", + "version" : "0.6.0" + } +] + +// SwiftPackageList 4 +[ + { + "identity" : "swift-package-manager", + "license" : "...", + "name" : "SwiftPM", + "repositoryURL" : "https:\/\/github.com\/apple\/swift-package-manager", + "revision" : "f5ea3972d7d6c574e8bb16a19b2a7bca98ea131b", + "version" : "0.6.0" + } +] +``` + +## `packageList()` and `PackageProvider` + +The top-level `packageList()` function in the `SwiftPackageList` module got removed in +favor of a `PackageProvider` protocol with dedicated implementations for JSON and +Property-Lists: + +```swift +// SwiftPackageList 3 +let packages = try packageList(bundle: .main, fileName: "package-list") + +// SwiftPackageList 4 +let packageProvider = JSONPackageProvider(bundle: .main, fileName: "package-list") +let packages = try packageProvider.packages() +``` + +This new protocol is also used in the `SwiftPackageListUI` module to provide the same +level of flexibility from this new approach: + +```swift +// SwiftPackageList 3 +var body: some View { + AcknowledgmentsList(packageListBundle: .main, packageListFileName: "package-list") +} + +// SwiftPackageList 4 +var body: some View { + AcknowledgmentsList(packageProvider: .json(bundle: .main, fileName: "package-list")) +} +``` + +## Swift Package Plugins and `swift-package-list-config.json` + +The `SwiftPackageListJSONPlugin`, `SwiftPackageListPropertyListPlugin`, +`SwiftPackageListPDFPlugin` and `SwiftPackageListSettingsBundlePlugin` got replaced by a +single `SwiftPackageListPlugin`. Open the target's **Build Phase** section, remove the +existing plugin from the **Run Build Tool Plug-ins** section and add the +`SwiftPackageListPlugin`: + +Screenshot 2024-02-11 at 20 13 43 +Screenshot 2024-02-11 at 20 07 07 + + +By default this new plugin will use the JSON output-type. To configure this, create a +`swift-package-list-config.json` in the project's root with the following format: + +```json +{ + "project" : { + "outputType" : "pdf" + } +} +``` + +## Objective-C Support Removed + +The `SwiftPackageListObjc` module got removed without a replacement. + +`SPLAcknowledgmentsTableViewController` is also no longer exposed to the Objective-C +runtime due to its added generic constraint. From 674960aa0cb593dc421e4c3c775a33c2bde55cb3 Mon Sep 17 00:00:00 2001 From: Felix Herrmann Date: Sun, 11 Feb 2024 20:34:48 +0100 Subject: [PATCH 2/2] Remove white-spaces --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 31773a1..56c0f27 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ By default this will use the JSON output with `--requires-license` but you can c Once added and configured the file(s) will get generated during every build process and are available in the App's bundle. You can then open them manually or use the various options in the included [Swift Package](#swift-package). -> [!NOTE] +> [!NOTE] > When using Xcode Cloud add `defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES` > to `ci_post_clone.sh` which disables the plugin validation.