https://github.com/adyen/adyen-swift-public-api-diff
This tool allows comparing 2 versions of a swift (sdk) project and lists all changes in a human readable way.
https://github.com/adyen/adyen-swift-public-api-diff
adyen api-diffs diff sdk swift swift-api
Last synced: 7 months ago
JSON representation
This tool allows comparing 2 versions of a swift (sdk) project and lists all changes in a human readable way.
- Host: GitHub
- URL: https://github.com/adyen/adyen-swift-public-api-diff
- Owner: Adyen
- License: mit
- Created: 2024-08-16T11:48:26.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-27T13:10:01.000Z (about 1 year ago)
- Last Synced: 2024-12-01T01:33:18.019Z (about 1 year ago)
- Topics: adyen, api-diffs, diff, sdk, swift, swift-api
- Language: Swift
- Homepage:
- Size: 2.27 MB
- Stars: 10
- Watchers: 8
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://github.com/Adyen/adyen-swift-public-api-diff/actions/workflows/run-tests.yml)
[](https://swiftpackageindex.com/Adyen/adyen-swift-public-api-diff)
[](https://swiftpackageindex.com/Adyen/adyen-swift-public-api-diff)
# Swift Public API diff
This tool allows comparing 2 versions of a swift (sdk) project and lists all changes in a human readable way.
It makes use of `.swiftinterface` files that get produced during the archiving of a swift project and parses them using [`swift-syntax`](https://github.com/swiftlang/swift-syntax).
## Contributing
We strongly encourage you to contribute to our repository. Find out more in our [contribution guidelines](https://github.com/Adyen/.github/blob/master/CONTRIBUTING.md)
## Requirements
- **Xcode** >= 16.0 (incl. Xcode command line tools)
- **Swift** >= 5.9
## Usage
### From Project to Output
- Build using the iOS sdk (Requires an iOS Simulator to be installed)
```bash
swift run public-api-diff \
project \
--platform iOS \
--new "develop~https://github.com/Adyen/adyen-ios.git" \
--old "5.12.0~https://github.com/Adyen/adyen-ios.git"
```
- Build using the macOS sdk
```bash
swift run public-api-diff \
project \
--platform macOS \
--new "main~https://github.com/Adyen/adyen-swift-public-api-diff" \
--old "0.4.0~https://github.com/Adyen/adyen-swift-public-api-diff"
```
--help:
```
USAGE: public-api-diff project --new --old --platform [--scheme ] [--swift-interface-type ] [--output ] [--log-output ] [--log-level ]
OPTIONS:
--new Specify the updated version to compare to
--old Specify the old version to compare to
--platform The platform to build the project for (iOS/macOS)
--scheme [Optional] Which scheme to build (Needed when
comparing 2 xcode projects)
--swift-interface-type
[Optional] Specify the type of .swiftinterface you
want to compare (public/private) (default: public)
--output [Optional] Where to output the result (File path)
--log-output
[Optional] Where to output the logs (File path)
--log-level [Optional] The log level to use during execution
(default: default)
-h, --help Show help information.
```
### From `.swiftinterface` to Output
**1.** Build 2 versions of your project with `BUILD_LIBRARY_FOR_DISTRIBUTION=YES`
```bash
xcodebuild clean build \
-scheme "YOUR_TARGET_NAME" \
-derivedDataPath .build \
-sdk "$(xcrun --sdk iphonesimulator --show-sdk-path)" \
-destination "generic/platform=iOS" \
BUILD_LIBRARY_FOR_DISTRIBUTION=YES
```
**2.** Provide the `.swiftinterface` files to the public api diff
```bash
swift run public-api-diff \
swift-interface \
--new "new/path/to/project.swiftinterface" \
--old "old/path/to/project.swiftinterface"
```
--help:
```
USAGE: public-api-diff swift-interface --new --old [--target-name ] [--old-version-name ] [--new-version-name ] [--output ] [--log-output ] [--log-level ]
OPTIONS:
--new Specify the updated .swiftinterface file to compare to
--old Specify the old .swiftinterface file to compare to
--target-name
[Optional] The name of your target/module to show in
the output
--old-version-name
[Optional] The name of your old version (e.g. v1.0 /
main) to show in the output
--new-version-name
[Optional] The name of your new version (e.g. v2.0 /
develop) to show in the output
--output [Optional] Where to output the result (File path)
--log-output
[Optional] Where to output the logs (File path)
--log-level [Optional] The log level to use during execution
(default: default)
-h, --help Show help information.
```
### From `.framework` to Output
```bash
swift run public-api-diff \
framework \
--target-name "TargetName" \
--new "new/path/to/project.framework" \
--old "old/path/to/project.framework"
```
--help:
```
USAGE: public-api-diff framework --new --old --target-name [--swift-interface-type ] [--old-version-name ] [--new-version-name ] [--output ] [--log-output ] [--log-level ]
OPTIONS:
--new Specify the updated .framework to compare to
--old Specify the old .framework to compare to
--target-name
The name of your target/module to show in the output
--swift-interface-type
[Optional] Specify the type of .swiftinterface you
want to compare (public/private) (default: public)
--old-version-name
[Optional] The name of your old version (e.g. v1.0 /
main) to show in the output
--new-version-name
[Optional] The name of your new version (e.g. v2.0 /
develop) to show in the output
--output [Optional] Where to output the result (File path)
--log-output
[Optional] Where to output the logs (File path)
--log-level [Optional] The log level to use during execution
(default: default)
-h, --help Show help information.
```
## Release Build
### Create
```bash
swift build --configuration release
```
### Run
```bash
./public-api-diff \
project \
--new "develop~https://github.com/Adyen/adyen-ios.git" \
--old "5.12.0~https://github.com/Adyen/adyen-ios.git"
```
```bash
./public-api-diff \
swift-interface \
--new "new/path/to/project.swiftinterface" \
--old "old/path/to/project.swiftinterface"
```
```bash
./public-api-diff \
framework \
--target-name "TargetName" \
--new "new/path/to/project.framework" \
--old "old/path/to/project.framework"
```
## Github Action
The public-api-diff can be used easily via the provided github action, which creates a comment on a PR (if applicable) and also adds it to the Github step summary.
```bash
- name: 🔍 Detect Changes
uses: Adyen/adyen-swift-public-api-diff@0.4.0
with:
platform: "iOS"
new: "develop~https://github.com/Adyen/adyen-ios.git"
old: "5.12.0~https://github.com/Adyen/adyen-ios.git"
```
See: [example workflow](https://github.com/Adyen/adyen-swift-public-api-diff/blob/main/Examples/github-workflow.yml)
## Alternatives
- **swift-api-digester**
- `xcrun swift-api-digester -dump-sdk`
- `xcrun swift-api-digester -diagnose-sdk`
## Projects using `public-api-diff`
- [Adyen iOS Checkout](https://github.com/Adyen/adyen-ios)
## Inspiration
- https://github.com/sdidla/Hatch/blob/main/Sources/Hatch/SymbolParser.swift
- For parsing swift files using [swift-syntax](https://github.com/swiftlang/swift-syntax)'s [`SyntaxVisitor`](https://github.com/swiftlang/swift-syntax/blob/main/Sources/SwiftSyntax/generated/SyntaxVisitor.swift)
## Support
If you have a feature request, or spotted a bug or a technical problem, create a GitHub issue.
## License
MIT license. For more information, see the LICENSE file.