SPM: cos'è, Swift Package Manager e Package.swift

Cos'è SPM?

SPM (Swift Package Manager) è il gestore di pacchetti ufficiale per il linguaggio Swift, integrato nel compilatore swiftc e nell'ambiente di sviluppo Xcode. Consente agli sviluppatori di aggiungere librerie di terze parti, gestire le loro versioni e pubblicare i propri pacchetti. SPM è apparso per la prima volta in Swift 3.0 (settembre 2016) come strumento a riga di comando e, a partire da Xcode 11 (2019), ha ricevuto l'integrazione completa con l'interfaccia grafica — le dipendenze vengono ora aggiunte tramite il menu File → Add Packages.

SPM scarica automaticamente il codice sorgente delle dipendenze dai repository Git, le compila in parallelo con il progetto principale e memorizza nella cache i risultati per velocizzare le compilazioni successive. A differenza di CocoaPods, SPM non genera un workspace separato (xcworkspace) — le dipendenze diventano parte del progetto Xcode principale. Secondo il sondaggio Swift.org Developer Survey (2024), il 67% degli sviluppatori iOS utilizza SPM, rendendolo lo strumento di gestione delle dipendenze più popolare nell'ecosistema Swift.

SPM supporta tre piattaforme: Apple (iOS, macOS, tvOS, watchOS, visionOS), Linux (Ubuntu, CentOS, Amazon Linux) e Swift lato server (Vapor, Kitura). Su Linux, SPM funziona interamente tramite riga di comando senza Xcode.

Come funziona Swift Package Manager

SPM è costruito attorno a tre concetti chiave: pacchetti (packages), prodotti (products) e target (targets). Un pacchetto è un repository Git con un manifesto Package.swift. Un prodotto è il risultato della compilazione (una libreria o un eseguibile). Un target è un modulo all'interno del pacchetto che viene compilato in un'unità di build.

Quando uno sviluppatore aggiunge una dipendenza a Package.swift, SPM esegue i seguenti passaggi:

1. Clonazione — SPM scarica il repository Git della dipendenza dall'URL specificato.
2. Risoluzione delle versioni — analizza i tag SemVer (ad esempio 2.1.3) e seleziona la versione appropriata nell'intervallo specificato.
3. Risoluzione transitiva — verifica le dipendenze delle dipendenze e costruisce un grafo di versioni senza conflitti.
4. Cache — salva il codice sorgente scaricato in ~Library/Caches/org.swift.swiftpm/.
5. Compilazione — compila tutti i target del pacchetto con i flag del progetto principale.

Il file Package.resolved fissa le versioni esatte di tutte le dipendenze in modo che il team di sviluppo lavori con un set identico di librerie. Questo file deve essere aggiunto al controllo versione (git).

Un vantaggio chiave di SPM rispetto alle alternative è l'assenza di un registro centralizzato. I pacchetti possono risiedere in qualsiasi repository Git pubblico: GitHub, GitLab, Bitbucket, oltre che su server Git privati aziendali. Da Swift 5.2, SPM supporta dipendenze binarie (binary targets) — librerie chiuse distribuite come XCFramework senza fornire codice sorgente.

Package.swift — manifesto del progetto

Package.swift è un file Swift che descrive la struttura del pacchetto e le sue dipendenze. Il file è scritto in Swift stesso (non JSON o YAML), consentendo l'uso di logica condizionale, costanti calcolate e funzioni all'interno del manifesto.

Struttura di base di Package.swift:

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "MyLibrary",
    platforms: [
        .iOS(.v16),
        .macOS(.v13)
    ],
    products: [
        .library(
            name: "MyLibrary",
            targets: ["MyLibrary"]
        ),
    ],
    dependencies: [
        .package(url: "https://github.com/Alamofire/Alamofire.git",
                 from: "5.9.0"),
        .package(url: "https://github.com/onevcat/Kingfisher.git",
                 from: "7.12.0"),
    ],
    targets: [
        .target(
            name: "MyLibrary",
            dependencies: [
                "Alamofire",
                "Kingfisher"
            ]
        ),
        .testTarget(
            name: "MyLibraryTests",
            dependencies: ["MyLibrary"]
        ),
    ]
)

Analizziamo gli elementi chiave:

• // swift-tools-version: 5.9 — direttiva che specifica la versione di SPM; da essa dipende la sintassi disponibile del manifesto.
• name — nome del pacchetto, visualizzato in Xcode e utilizzato nei collegamenti delle dipendenze.
• platforms — versioni minime delle piattaforme; SPM non consentirà di compilare il pacchetto su una versione di SO più vecchia.
• products — ciò che il pacchetto "esporta": una libreria (.library) o un eseguibile (.executable).
• dependencies — elenco di pacchetti esterni con URL e versione; supporta from:, exact:, branch:, revision:.
• targets — target di compilazione; ogni target contiene un elenco di dipendenze, risorse e file Swift dalla directory corrispondente (Sources/TargetName/).

Esempio di specifica di versione esatta, branch e commit:

dependencies: [
    .package(url: "https://github.com/pointfreeco/swift-snapshot-testing.git",
             exact: "1.17.3"),
    .package(url: "https://github.com/pointfreeco/swift-composable-architecture.git",
             branch: "main"),
    .package(url: "https://github.com/apple/swift-log.git",
             revision: "e5c6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4"),
]

Da Swift 5.9, Package.swift ha aggiunto il supporto per static framework e linkerSettings, consentendo una configurazione più precisa del linker per librerie statiche e dinamiche.

Comandi SPM di base

Swift Package Manager fornisce un insieme di comandi per lavorare tramite terminale. I comandi vengono eseguiti dalla directory principale del pacchetto (dove si trova Package.swift).

# Creare un nuovo pacchetto con una libreria
swift package init --type library

# Creare un pacchetto eseguibile (applicazione console)
swift package init --type executable

# Compilare il progetto
swift build

# Compilare in configurazione release
swift build -c release

# Eseguire i test
swift test

# Eseguire un test specifico
swift test --filter "MyLibraryTests/testExample"

# Scaricare e risolvere le dipendenze
swift package resolve

# Aggiornare le dipendenze alle ultime versioni disponibili
swift package update

# Mostrare il grafo delle dipendenze
swift package show-dependencies

# Pulire la cache di compilazione
swift package clean

# Generare il progetto Xcode (prima di Xcode 11)
swift package generate-xcodeproj

Quando si lavora all'interno di Xcode, la maggior parte di questi comandi viene eseguita automaticamente: le dipendenze vengono risolte all'apertura del progetto, la compilazione si avvia con ⌘B, i test con ⌘U. Tuttavia, la conoscenza dei comandi da terminale è necessaria per le pipeline CI/CD (GitHub Actions, GitLab CI, Jenkins) dove Xcode non è disponibile.

Il comando swift package resolve crea o aggiorna il file Package.resolved. Questo file fissa le versioni esatte di tutte le dipendenze, incluse quelle transitive, e deve essere aggiunto a git. Si consiglia di eseguire swift package update prima di ogni nuovo branch di funzionalità per lavorare con versioni aggiornate delle librerie.

Creazione del tuo pacchetto

Creare il proprio pacchetto SPM è utile per incapsulare la logica di business in progetti multi-modulo e per pubblicare librerie open source. Vediamo il processo passo dopo passo.

Passo 1: Inizializzazione

mkdir MyNetworkKit
cd MyNetworkKit
swift package init --type library

Passo 2: Struttura delle directory

Il comando swift package init crea la seguente struttura:

MyNetworkKit/
├── Package.swift
├── README.md
├── Sources/
│   └── MyNetworkKit/
│       └── MyNetworkKit.swift
└── Tests/
    └── MyNetworkKitTests/
        └── MyNetworkKitTests.swift

SPM scansiona automaticamente le directory Sources/ e Tests/: ogni sottodirectory all'interno di Sources corrisponde a un target.

Passo 3: Modificare Package.swift

Aggiungiamo le dipendenze e configuriamo le piattaforme target:

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "MyNetworkKit",
    platforms: [
        .iOS(.v15),
        .macOS(.v12)
    ],
    products: [
        .library(
            name: "MyNetworkKit",
            targets: ["MyNetworkKit"]
        ),
    ],
    dependencies: [
        .package(url: "https://github.com/Alamofire/Alamofire.git",
                 from: "5.9.0"),
    ],
    targets: [
        .target(
            name: "MyNetworkKit",
            dependencies: ["Alamofire"]
        ),
        .testTarget(
            name: "MyNetworkKitTests",
            dependencies: ["MyNetworkKit"]
        ),
    ]
)

Passo 4: Scrivere il codice

// Sources/MyNetworkKit/MyNetworkKit.swift
import Foundation
import Alamofire

public struct NetworkClient {
    private let session: Session

    public init() {
        let configuration = URLSessionConfiguration.default
        configuration.timeoutIntervalForRequest = 30
        self.session = Session(configuration: configuration)
    }

    public func fetchData(from url: String) async throws -> Data {
        let response = try await session.request(url).serializingData().value
        return response
    }
}

Passo 5: Pubblicazione