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.

Contributing

We strongly encourage you to contribute to our repository. Find out more in our contribution guidelines

Requirements

• Xcode >= 16.0 (incl. Xcode command line tools)
• Swift >= 5.9
• macOS >= 13.0

Installation

Swift Package Manager (as a dependency)

Add the package to your Package.swift:

dependencies: [
    .package(url: "https://github.com/Adyen/adyen-swift-public-api-diff", from: "0.10.1")
]

Available library products:

• SwiftInterfaceDiff - Core diffing functionality for .swiftinterface files
• PublicApiDiff - Full API including project building, package analysis, and output generation

Install via Mint

mint install Adyen/adyen-swift-public-api-diff

Build from Source

git clone https://github.com/Adyen/adyen-swift-public-api-diff.git
cd adyen-swift-public-api-diff
swift build --configuration release

The binary will be available at .build/release/public-api-diff.

Usage

From Project to Output

• Build using the iOS sdk (Requires an iOS Simulator to be installed)

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

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 <new> --old <old> --platform <platform> [--scheme <scheme>] [--swift-interface-type <swift-interface-type>] [--output <output>] [--log-output <log-output>] [--log-level <log-level>]

OPTIONS:
  --new <new>             Specify the updated version to compare to
  --old <old>             Specify the old version to compare to
  --platform <platform>   The platform to build the project for (iOS/macOS)
  --scheme <scheme>       [Optional] Which scheme to build (Needed when
                          comparing 2 xcode projects)
  --swift-interface-type <swift-interface-type>
                          [Optional] Specify the type of .swiftinterface you
                          want to compare (public/private) (default: public)
  --output <output>       [Optional] Where to output the result (File path)
  --log-output <log-output>
                          [Optional] Where to output the logs (File path)
  --log-level <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

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

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 <new> --old <old> [--target-name <target-name>] [--old-version-name <old-version-name>] [--new-version-name <new-version-name>] [--output <output>] [--log-output <log-output>] [--log-level <log-level>]

OPTIONS:
  --new <new>             Specify the updated .swiftinterface file to compare to
  --old <old>             Specify the old .swiftinterface file to compare to
  --target-name <target-name>
                          [Optional] The name of your target/module to show in
                          the output
  --old-version-name <old-version-name>
                          [Optional] The name of your old version (e.g. v1.0 /
                          main) to show in the output
  --new-version-name <new-version-name>
                          [Optional] The name of your new version (e.g. v2.0 /
                          develop) to show in the output
  --output <output>       [Optional] Where to output the result (File path)
  --log-output <log-output>
                          [Optional] Where to output the logs (File path)
  --log-level <log-level> [Optional] The log level to use during execution
                          (default: default)
  -h, --help              Show help information.

From .framework to Output

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 <new> --old <old> --target-name <target-name> [--swift-interface-type <swift-interface-type>] [--old-version-name <old-version-name>] [--new-version-name <new-version-name>] [--output <output>] [--log-output <log-output>] [--log-level <log-level>]

OPTIONS:
  --new <new>             Specify the updated .framework to compare to
  --old <old>             Specify the old .framework to compare to
  --target-name <target-name>
                          The name of your target/module to show in the output
  --swift-interface-type <swift-interface-type>
                          [Optional] Specify the type of .swiftinterface you
                          want to compare (public/private) (default: public)
  --old-version-name <old-version-name>
                          [Optional] The name of your old version (e.g. v1.0 /
                          main) to show in the output
  --new-version-name <new-version-name>
                          [Optional] The name of your new version (e.g. v2.0 /
                          develop) to show in the output
  --output <output>       [Optional] Where to output the result (File path)
  --log-output <log-output>
                          [Optional] Where to output the logs (File path)
  --log-level <log-level> [Optional] The log level to use during execution
                          (default: default)
  -h, --help              Show help information.

Release Build

Create

swift build --configuration release

Run

./public-api-diff \
    project \
    --new "develop~https://github.com/Adyen/adyen-ios.git" \ 
    --old "5.12.0~https://github.com/Adyen/adyen-ios.git"

./public-api-diff \
    swift-interface \
    --new "new/path/to/project.swiftinterface" \
    --old "old/path/to/project.swiftinterface"

./public-api-diff \
    framework \
    --target-name "TargetName" \
    --new "new/path/to/project.framework" \
    --old "old/path/to/project.framework"

Output Format

The tool generates a Markdown report showing all public API changes, organized by module/target:

# 👀 3 public changes detected
_Comparing `develop` to `5.12.0`_

---
## `ModuleName`
#### ❇️ Added
\`\`\`swift
public func newFunction()
\`\`\`
#### 🔀 Changed
\`\`\`swift
// From
public func existingFunction(param: String)

// To
public func existingFunction(param: String, newParam: Int)
\`\`\`
#### 😶‍🌫️ Removed
\`\`\`swift
public func deprecatedFunction()
\`\`\`

The output can be written to a file using the --output flag or printed to stdout.

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.

- name: 🔍 Detect Changes
  uses: Adyen/adyen-swift-public-api-diff@0.10.1
  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

Alternatives

• swift-api-digester
  • xcrun swift-api-digester -dump-sdk
  • xcrun swift-api-digester -diagnose-sdk

Projects using public-api-diff

• Adyen iOS Checkout

Inspiration

• https://github.com/sdidla/Hatch/blob/main/Sources/Hatch/SymbolParser.swift
  • For parsing swift files using swift-syntax's SyntaxVisitor

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.