SPM Migration Guide

This document describes the migration of isar_plus_flutter_libs from CocoaPods to Swift Package Manager (SPM) and the introduction of a unified Darwin shared structure for iOS and macOS.

Overview

Prior to this migration, the plugin used separate CocoaPods podspecs for iOS and macOS, with distinct native source directories for each platform. The new structure:

• Uses a single Package.swift at the plugin root for SPM configuration
• Shares all Darwin (iOS + macOS) native source code under darwin/Classes/
• Ships a unified IsarPlusCore.xcframework containing slices for iOS device, iOS simulator, and macOS
• Removes all CocoaPods artifacts (.podspec files, Podfile, Pods/ directories)

New Darwin Shared Structure

packages/isar_plus_flutter_libs/
├── darwin/
│   └── Classes/
│       ├── binding.h                       ← FFI declarations (shared)
│       └── IsarPlusFlutterLibsPlugin.swift ← Unified plugin (iOS + macOS)
├── Package.swift                           ← SPM manifest
└── pubspec.yaml                            ← Flutter plugin config

The darwin/Classes/ directory is the single source of truth for all Apple platform native code. Platform-specific imports (UIKit vs Cocoa) are handled via Swift conditional compilation (#if os(iOS) / #elseif os(macOS)).

Unified XCFramework Structure

The native Isar Core library is distributed as a single IsarPlusCore.xcframework containing three slices:

All slices use static archives (.a), which is required for SPM vendored binary support. The macOS slice is no longer a .dylib.

Installation and Setup

New Projects

For new projects, no special setup is required. Add the dependency to your pubspec.yaml and Flutter's tooling will automatically resolve the plugin via SPM:

dependencies:
  isar_plus: ^1.2.6
  isar_plus_flutter_libs: ^1.2.6

Upgrading from CocoaPods

For most Flutter projects, migrating to Swift Package Manager does not require changing your application code unless your project has custom Xcode configurations or dependencies that make heavy use of CocoaPods install scripts. Updating to the latest version of the plugin will automatically migrate your underlying dependency manager on Apple platforms to Swift Package Manager.

If you are managing other non-Flutter dependencies via CocoaPods, you may need to migrate those manually or keep them. If you want to fully remove CocoaPods from your project, follow these steps:

cd ios
pod deintegrate
rm -rf Podfile Podfile.lock Pods Runner.xcworkspace
cd ..

rm -rf ~/Library/Developer/Xcode/DerivedData

flutter pub get

flutter run