Szoftver

Hogyan írjunk saját Swift csomagot a Package Manager segítségével?

iranyonline 0

Üdvözöllek a Swift fejlesztés izgalmas világában! Ha valaha is azon gondolkodtál, hogyan tehetnéd újrafelhasználhatóvá a kódodat, hogyan oszthatnád meg másokkal, vagy hogyan szervezhetnéd projektjeidet modulárisabban, akkor jó helyen jársz. A válasz a Swift Package Manager (SPM) és a Swift csomagok használatában rejlik. Ebben az átfogó útmutatóban lépésről lépésre végigvezetlek a saját Swift csomagod létrehozásának, konfigurálásának, tesztelésének és megosztásának folyamatán. Készen állsz, hogy magasabb szintre emeld a Swift fejlesztési képességeidet?

A moduláris fejlesztés napjainkban már nem csupán egy divatos kifejezés, hanem egy elengedhetetlen gyakorlat a skálázható, karbantartható és hatékony szoftverek építéséhez. A Swift Package Manager ehhez nyújt egy robusztus, natív megoldást, amely tökéletesen integrálódik az Xcode-ba és a Swift toolchainbe. Lássuk is, hogyan tehetjük magunkévá ezt az eszközt!

Miért érdemes saját Swift csomagot írni?

Mielőtt belevágnánk a technikai részletekbe, érdemes megérteni, miért olyan értékesek a Swift csomagok:

  • Újrafelhasználhatóság: Írj meg egy kódrészletet egyszer, és használd fel bármennyi projektedben. Ez rendkívül sok időt és energiát spórol meg.
  • Moduláris felépítés: Bonyolult projektek esetén segítenek a kód logikai egységekre bontásában, javítva az átláthatóságot és a karbantarthatóságot.
  • Megosztás: Könnyedén megoszthatod a munkádat más fejlesztőkkel, legyen szó belső csapatról vagy a nyílt forráskódú közösségről.
  • Függőségkezelés: Az SPM nem csak a te csomagjaidat kezeli, hanem a külső függőségeidet is, egyszerűsítve a projektbe való integrálásukat.
  • Xcode integráció: Zökkenőmentesen működik együtt az Xcode-dal, így a fejlesztési élmény rendkívül kényelmes.

Előfeltételek és az első lépések

Mielőtt belevágnál, győződj meg róla, hogy a következőkre van szükséged:

  • Egy telepített Xcode verzió, amely tartalmazza a legújabb Swift fordítót és a Command Line Tools-t.
  • Alapvető ismeretek a Git verziókezelő rendszerről, mivel a Swift csomagok általában Git repókon keresztül kerülnek megosztásra.

A Csomag Inicializálása

Kezdjük a legalapvetőbbel: egy üres Swift csomag létrehozásával. Nyisd meg a Terminált, navigálj oda, ahol a csomagot tárolni szeretnéd, majd futtasd a következő parancsot:

mkdir MyAwesomePackage
cd MyAwesomePackage
swift package init --type library

A `–type library` paraméterrel egy tipikus kódtárat hozunk létre. Választhatnál `–type executable`-t is, ha egy önállóan futtatható parancssori eszközt szeretnél fejleszteni. A parancs futtatása után a következő fájlstruktúrát fogod látni:

MyAwesomePackage/
├── Sources/
│   └── MyAwesomePackage/
│       └── MyAwesomePackage.swift
├── Tests/
│   └── MyAwesomePackageTests/
│       └── MyAwesomePackageTests.swift
├── .gitignore
├── Package.swift
└── README.md

Nézzük meg röviden, mit jelentenek ezek a fájlok és mappák:

  • Sources/: Itt található a csomagod tényleges forráskódja. Az alapértelmezett beállítás szerint létrejön egy mappa, amelynek neve megegyezik a csomag nevével (MyAwesomePackage), és azon belül egy .swift fájl. Ez lesz a csomagod fő modulja.
  • Tests/: Ebben a könyvtárban helyezkednek el a csomagod tesztjei, az XCTest keretrendszert használva.
  • .gitignore: A Git számára tájékoztató fájl, hogy mely fájlokat és mappákat hagyja figyelmen kívül a verziókövetés során (pl. build output).
  • Package.swift: Ez a legfontosabb fájl! Ez a manifest fájl írja le a csomagot, annak termékeit (products), céljait (targets), függőségeit (dependencies) és egyéb konfigurációs beállításait.
  • README.md: Egy rövid leírás a csomagodról, általában Markdown formátumban. Nagyon hasznos a felhasználók számára.

A Package.swift fájl mélyreható elemzése

Nyisd meg a Package.swift fájlt az Xcode-ban vagy egy tetszőleges szövegszerkesztővel. Valami ilyesmit fogsz látni:

// swift-tools-version:5.9
// The swift-tools-version declares the minimum version of Swift tools required to build this package.

import PackageDescription

let package = Package(
    name: "MyAwesomePackage",
    products: [
        // Products define the executables and libraries a package produces, making them visible to other packages.
        .library(
            name: "MyAwesomePackage",
            targets: ["MyAwesomePackage"]),
    ],
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        // .package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0"),
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages this package depends on.
        .target(
            name: "MyAwesomePackage",
            dependencies: []),
        .testTarget(
            name: "MyAwesomePackageTests",
            dependencies: ["MyAwesomePackage"]),
    ]
)

Nézzük meg részletesebben a kulcsfontosságú részeket:

swift-tools-version

Ez a kommentben szereplő sor jelzi a Swift Package Managernek, hogy milyen minimális verziójú Swift toolchainre van szükség a csomag buildeléséhez. Fontos, hogy ez a verzió megegyezzen azzal a Swift verzióval, amit használsz, vagy egy korábbival. A legtöbb esetben az Xcode verziójához igazodik.

PackageDescription

Ez egy speciális modul, amelyet az SPM használ a Package.swift fájl értelmezésére. Mindig szerepelnie kell!

name

A csomagod egyedi neve. Ennek kell megegyeznie a Git repository nevével, ha később publikálni szeretnéd.

products

A termékek azok a dolgok, amelyeket a csomagod „gyárt”, és amelyek elérhetővé válnak más projektek vagy csomagok számára. Két fő típusa van:

  • .library: Egy kódtár, amelyet más Swift projektek importálhatnak. Ez a leggyakoribb típus. Megadhatod a nevét és azokat a célokat (targets), amelyekből felépül.
  • .executable: Egy önállóan futtatható program, például egy parancssori eszköz.

Például, ha egy segédprogram csomagot készítesz, ami két különálló, de kapcsolódó modulból áll, mindkettőt felveheted termékként:

products: [
    .library(name: "MyAwesomeUtils", targets: ["MyAwesomeUtils"]),
    .library(name: "AnotherHelper", targets: ["AnotherHelper"]),
],

dependencies

Itt deklarálhatod azokat a külső függőségeket, amelyekre a saját csomagodnak szüksége van. Ezek lehetnek más Swift csomagok, amelyeket GitHub-ról vagy más Git szolgáltatásból tölt be az SPM.

A leggyakoribb forma a .package(url: "URL_a_repohoz", from: "minimum_verzió"). Példa egy népszerű nyílt forráskódú könyvtár hozzáadására:

dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git", from: "5.8.0"),
    .package(url: "https://github.com/kishikawakatsumi/KeychainAccess.git", .upToNextMajor(from: "4.2.2"))
],

A verziókezelésre többféle módon is hivatkozhatsz:

  • .from("1.0.0"): Legalább 1.0.0, de annál újabb major verziókat is engedélyez.
  • .upToNextMajor(from: "1.0.0"): Legalább 1.0.0, de csak az 1.x.x verziókat engedélyezi, a 2.0.0-t már nem. Ez a legbiztonságosabb és leggyakoribb.
  • .upToNextMinor(from: "1.0.0"): Legalább 1.0.0, de csak az 1.0.x verziókat engedélyezi.
  • .exact("1.2.3"): Pontosan az adott verziót igényli.
  • .branch("main"): Egy adott branch-et használ.
  • .revision("abcdef12345"): Egy adott commit-ra hivatkozik.

targets

A célok (targets) a csomagod alapvető építőkövei. Egy cél lehet egy forráskód-modul (.target) vagy egy tesztgyűjtemény (.testTarget). A célokhoz hozzárendelhetők függőségek, amelyek lehetnek a saját csomagon belüli más célok, vagy a dependencies szakaszban deklarált külső csomagok termékei.

A MyAwesomePackage példában van egy MyAwesomePackage nevű forráskód cél, és egy MyAwesomePackageTests nevű teszt cél, amely függ a MyAwesomePackage forráskód céltól.

Ha további modulokat szeretnél a csomagodban, egyszerűen létrehozol egy új mappát a Sources/ könyvtárban (pl. Sources/MyUtils), majd hozzáadsz egy új .target definíciót a Package.swift-hez:

targets: [
    .target(
        name: "MyAwesomePackage",
        dependencies: ["MyUtils"]), // Mostantól függ a MyUtils-tól
    .target(
        name: "MyUtils",
        dependencies: []),
    .testTarget(
        name: "MyAwesomePackageTests",
        dependencies: ["MyAwesomePackage", "MyUtils"]),
]

Fontos, hogy minden forráskód fájl (.swift) egy célhoz tartozzon, és hogy a célok közötti függőségeket megfelelően deklaráld. Ha egy cél függ egy másiktól, azt bele kell írni a dependencies tömbjébe a cél definícióján belül.

A Csomag Tartalmának Kialakítása

Forráskód elhelyezése és hozzáférés

Ahogy már említettük, a kódodat a Sources/ mappán belül, a megfelelő célmappában helyezd el. Például, ha a csomagod neve MyAwesomePackage, a kódod a Sources/MyAwesomePackage/ mappába kerül. Ide veheted fel a .swift fájljaidat, és itt írhatod meg a modulodat.

A hozzáférés-vezérlés (access control) kiemelt fontosságú a csomagoknál. Alapértelmezetten minden internal, ami azt jelenti, hogy csak a saját modulján belül látható. Ahhoz, hogy a csomagod felhasználói láthassák és használhassák a funkcióidat, azokat public-ként kell deklarálnod:

// Sources/MyAwesomePackage/MyAwesomePackage.swift

public struct MyAwesomePackage {
    public private(set) var text = "Hello, World!"

    public init() {
    }

    public func sayHello(to name: String) -> String {
        return "Hello, (name) from MyAwesomePackage!"
    }
}

public class MyUsefulClass {
    // ...
}

Ne felejtsd el, ami nem public, az nem lesz elérhető a csomagot használók számára!

Erőforrások (Resources)

Ha a csomagodnak szüksége van erőforrásokra, mint például képekre, JSON fájlokra, lokalizációs stringekre, azokat is hozzáadhatod. Ezt a cél definíciójában teheted meg:

.target(
    name: "MyAwesomePackage",
    dependencies: [],
    resources: [
        .process("Resources/Data.json"),
        .copy("Resources/Image.png")
    ]
),

Az erőforrásokat a célmappán belüli Resources/ mappába helyezd. A .process optimalizálja az erőforrásokat (pl. méretezés), míg a .copy egyszerűen bemásolja őket.

Tesztelés: A Minőség Alapja

Egy jó minőségű csomag nem létezhet megfelelő tesztelés nélkül. Az SPM natívan támogatja az XCTest-et. Amikor inicializálod a csomagot, egy teszt cél (MyAwesomePackageTests) és egy alapvető tesztfájl (MyAwesomePackageTests.swift) jön létre a Tests/ mappában.

Teszt írása

Nyisd meg a Tests/MyAwesomePackageTests/MyAwesomePackageTests.swift fájlt. Valami ilyesmit fogsz látni:

import XCTest
@testable import MyAwesomePackage // Fontos a tesztelt modul importálása

final class MyAwesomePackageTests: XCTestCase {
    func testExample() throws {
        // This is an example of a functional test case.
        // Use XCTAssert and related functions to verify your tests produce the correct
        // results.
        let sut = MyAwesomePackage() // System Under Test
        XCTAssertEqual(sut.text, "Hello, World!")
        XCTAssertEqual(sut.sayHello(to: "User"), "Hello, User from MyAwesomePackage!")
    }

    // Új teszt metódusok is ide írhatók
    func testAnotherFunctionality() {
        // ...
    }
}

A @testable import MyAwesomePackage direktíva lehetővé teszi, hogy hozzáférj az internal típusokhoz és metódusokhoz is a tesztelt modulban, ami nagyon hasznos. A XCTAssert függvények segítségével ellenőrizheted, hogy a kódod a várt módon működik-e.

Teszt futtatása

A teszteket a Terminálból a következő parancs segítségével futtathatod:

swift test

Xcode-ban pedig egyszerűen válaszd ki a teszt célt, és futtasd onnan, vagy használd a teszt gombokat a teszt metódusok mellett.

A Swift Csomag Használata

Helyi használat Xcode projektben

Ha egy Xcode projektben szeretnéd használni a frissen írt csomagodat, ez rendkívül egyszerű:

  1. Nyisd meg az Xcode projektet.
  2. Menj a File > Add Packages... menüpontra.
  3. A megjelenő ablakban válaszd a Add Local... lehetőséget (ha az Xcode 14.3+ verziót használod) vagy egyszerűen drag-and-drop módszerrel húzd be a csomagot tartalmazó mappát a projekt navigátorba. Alternatív megoldásként add meg a helyi mappa elérési útját a keresőmezőbe.
  4. Válaszd ki a hozzáadni kívánt célokat (targets).

Ezután már importálhatod a csomagodat a kódban, és használhatod a public elemeket:

import MyAwesomePackage

let myPackageInstance = MyAwesomePackage()
print(myPackageInstance.sayHello(to: "Developer"))

Helyi használat másik Swift csomagban

Ha egy másik Swift csomagban szeretnéd használni a sajátodat, akkor a Package.swift fájljában add hozzá a függőségekhez:

dependencies: [
    .package(path: "../MyAwesomePackage") // Relatív vagy abszolút útvonal a helyi csomaghoz
],
targets: [
    .target(
        name: "MyOtherPackage",
        dependencies: ["MyAwesomePackage"]), // Add hozzá mint függőséget
],

Csomag publikálása és távoli használata

Ahhoz, hogy mások (vagy te magad más projektekben) könnyedén használhassák a csomagodat, fel kell töltened egy Git repository-ba, például GitHub-ra, GitLab-ra vagy Bitbucket-re. Az alábbi lépéseket kell követned:

  1. Inicializáld a Git repository-t: 
    git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/YourUsername/MyAwesomePackage.git
git push -u origin main

    Természetesen a YourUsername és a repository URL-je helyére a saját adataidat írd.

  2. Hozd létre az első verziót (tag):
    A verziózás kritikus fontosságú. A Swift Package Manager a Git tag-eket használja a verziók azonosítására. Javasolt a Szemantikus Verziózás (Semantic Versioning) használata (Major.Minor.Patch, pl. 1.0.0).

    git tag 1.0.0
git push origin 1.0.0 --tags

    Minden nagyobb változás, hibajavítás vagy új funkció esetén adj ki egy új tag-et.

  3. Csomag használata más projektekben:
    Amint a csomagod feltöltésre került a Git repository-ba és rendelkezik tag-ekkel, bárki hozzáadhatja a projektjéhez vagy más csomagjához.

    dependencies: [
            .package(url: "https://github.com/YourUsername/MyAwesomePackage.git", from: "1.0.0"),
        ],
        targets: [
            .target(
                name: "MyApp",
                dependencies: ["MyAwesomePackage"]),
        ]

    Ismét, cseréld le a URL-t a saját repository URL-jére.

Fejlettebb témák és tippek

Platform-specifikus kód

Előfordulhat, hogy a csomagodnak különböző kódra van szüksége különböző platformokon (pl. iOS, macOS, watchOS, tvOS, Linux). Ezt a feltételes fordítási direktívákkal érheted el:

#if os(iOS)
import UIKit
public func doSomethingiOSSpecific() { /* ... */ }
#elseif os(macOS)
import AppKit
public func doSomethingmacOSSpecific() { /* ... */ }
#else
// Kód más platformokra
#endif

Dokumentáció

Egy jól dokumentált csomag sokkal használhatóbb. Használj Xcode Markup-ot a kódod kommentelésére, hogy az Xcode gyors súgójában és a generált dokumentációban is megjelenjenek az információk:

/// A struct that provides awesome functionalities.
///
/// Use this struct to say hello to the world or any specific name.
public struct MyAwesomePackage {

    /// The default greeting text.
    public private(set) var text = "Hello, World!"

    /// Initializes a new instance of `MyAwesomePackage`.
    public init() { }

    /// Says hello to a specific name.
    /// - Parameter name: The name to greet.
    /// - Returns: A greeting string.
    public func sayHello(to name: String) -> String {
        return "Hello, (name) from MyAwesomePackage!"
    }
}

Emellett egy részletes README.md fájl is elengedhetetlen a repository gyökerében, amely tartalmazza a telepítési útmutatót, használati példákat, API leírást és licencinformációkat.

Hibaelhárítás

Néhány gyakori SPM parancs, ami segíthet a problémák megoldásában:

  • swift package update: Frissíti a függőségeket a Package.swift-ben megadott verziósávok szerint.
  • swift package clean: Törli az összes build cache-t, ami megoldhatja a furcsa buildelési problémákat.
  • swift package resolve: Feloldja a függőségeket, de nem frissíti őket.
  • swift package describe --full: Részletes információt ad a csomagról és annak függőségeiről.

Összegzés

Gratulálok! Most már rendelkezel azokkal az ismeretekkel, amelyek segítségével létrehozhatod, konfigurálhatod, tesztelheted és megoszthatod saját Swift csomagodat a Swift Package Manager segítségével. Ez a tudás kulcsfontosságú a modern Swift fejlesztésben, lehetővé téve a kód újrafelhasználhatóságát, a moduláris architektúrákat és a hatékony együttműködést. Ne félj kísérletezni, építsd meg az első segédprogramjaidat, és oszd meg őket a közösséggel!

A Swift Package Manager egy folyamatosan fejlődő, erőteljes eszköz, amely jelentősen megkönnyíti a függőségkezelést és a moduláris kód szervezését. Kezdd el még ma, és fedezd fel, mennyi időt és energiát spórolhatsz meg hosszú távon! Boldog kódolást!

Kapcsolódó

Leave a Reply

Az e-mail címet nem tesszük közzé. A kötelező mezőket * karakterrel jelöltük