CocoaPods Trunk: mi ez, kódtárak közzététele a Trunk segítségével

Mi az a CocoaPods Trunk?

CocoaPods Trunk — egy 2015-ben indított szerver-infrastruktúra a pod-kódtárak központosított közzétételére. A Trunk megjelenése előtt minden pod Git tárolón keresztül került terjesztésre: a fejlesztőnek létre kellett hoznia egy nyilvános tárhelyet, hozzáadnia egy podspec fájlt, és Pull Request-et kellett küldenie a központi CocoaPods/Specs tárolóba. Ez a megközelítés kézi moderálást igényelt, és késedelmeket okozott a frissítések közzétételében.

A Trunk megoldotta ezeket a problémákat azáltal, hogy egységes API-t biztosított a pod-ok közzétételéhez, frissítéséhez és törléséhez. A szolgáltatás négy kulcsfontosságú összetevőből áll:

• Hitelesítés — regisztráció e-mail megerősítéssel és munkamenet-tokenek kezelése. Minden fejlesztő egyedi tokent kap, amely a fiókjához és eszközeihez van kötve.
• Érvényesítés — a podspec automatikus ellenőrzése közzététel előtt, beleértve a szintaktikai elemzést, a függőségek lintingjét és a platformkompatibilitás ellenőrzését.
• Üzemeltetés — a pod-ok metaadatainak és verzióinak tárolása a CocoaPods szerverein. A forráskód továbbra is a fejlesztő Git tárolójában marad, a Trunk csak a podspec fájlokat és hivatkozásokat tárolja.
• Hozzáférés-kezelés — lehetőség pod-tulajdonosok hozzáadására és eltávolítására, közzétételi jogok átruházására, pod-ok elavulttá nyilvánítására.

A Trunk architektúrája Ruby on Rails stack-re épül PostgreSQL adatbázissal. A szolgáltatás HTTP API-t használ JSON formátumban minden művelethez, a pod trunk CLI kliens pedig a CocoaPods disztribúció része, és a fő cocoapods gem-mel együtt települ.

Jelenleg több mint 100 000 pod-ot tettek közzé a Trunk segítségével, a letöltések teljes száma meghaladja az 50 milliárdot. A szolgáltatás naponta több ezer közzétételi és frissítési kérelmet dolgoz fel a világ minden tájáról érkező fejlesztőktől.

Regisztráció és hitelesítés

A pod közzététele előtt regisztrálnia kell a Trunk-ban. A folyamat egyetlen lépésből áll — a pod trunk register parancsból:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, iOS fejlesztés'

A parancs végrehajtása után a megadott e-mail címre egy megerősítő linket tartalmazó levél érkezik. A linkre kattintva aktiválódik a fiók, és létrejön egy munkamenet-token, amely a rendszer kulcstartójában (Keychain macOS-en, gnome-keyring vagy megfelelője Linuxon) tárolódik. A token automatikusan használatos minden további pod trunk műveletnél.

A --description paraméter opcionális, de ajánlott — segít azonosítani a munkamenetet az aktív munkamenetek pod trunk me segítségével történő megtekintésekor. Ha több gépen dolgozik (munkaállomás, CI-szerver), a leírás lehetővé teszi az egyik munkamenet megkülönböztetését a másiktól.

A hitelesítési állapot ellenőrzéséhez a következő parancs használható:

pod trunk me

A kimenet megjeleníti az e-mailt, nevet, a pod-ok listáját (ha már tett közzé) és az aktív munkameneteket. Példa az eredményre:

  - Name: Your Name
  - Email: your@email.com
  - Since: 2024-03-15 10:30 UTC
  - Pods:
    - MyLibrary
    - AnotherPod
  - Sessions:
    - 2024-03-15 10:30 UTC - MacBook Pro, iOS-fejlesztés

CI-szervereken (GitHub Actions, GitLab CI, Jenkins) a hitelesítés a COCOAPODS_TRUNK_TOKEN környezeti változón keresztül átadott token segítségével történik. A token a következő paranccsal szerezhető meg:

pod trunk me --token-only

Ez a token titkos változóként tárolódik a CI beállításaiban, és a közzétételi szakaszban újraregisztráció nélkül használatos. Példa GitHub Actions esetén:

env:
  COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}

Fontos: a token teljes hozzáférést biztosít a fiókhoz kötött pod-ok kezeléséhez. Soha ne tegye közzé nyilvános tárolókban, és ne adja át harmadik félnek. Kompromittálódás esetén a token visszavonható a pod trunk remove-session paranccsal, vagy az összes munkamenet törölhető a CocoaPods weboldalán található vezérlőpulton keresztül.

Podspec előkészítése

A podspec fájl (.podspec vagy .podspec.json) — a kódtár manifesztje, amely metaadatokat, függőségeket, platformokkal és forráskóddal kapcsolatos információkat tartalmaz. A Trunk ezt a fájlt használja a pod érvényesítéséhez és regisztrálásához. A közzétételhez minimális podspec így néz ki:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'A kódtár rövid leírása'
  s.description  = 'Részletes leírás a képességek magyarázatával'
  s.homepage     = 'https://github.com/username/MyLibrary'
  s.license      = { :type => 'MIT', :file => 'LICENSE' }
  s.author       = { 'Your Name' => 'your@email.com' }
  s.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => s.version.to_s }
  s.source_files = 'Sources/**/*.{swift,h,m}'
  s.platform     = :ios, '12.0'
  s.swift_version = '5.7'
end

A podspec kulcsfontosságú mezői:

• name — a pod neve, amelynek egyedinek kell lennie a Trunk nyilvántartásában. A nevek a 'ki előbb jön, előbb visz' elv alapján kerülnek regisztrálásra — ha a név foglalt, a közzététel elutasításra kerül.
• version — szemantikus verzió MAJOR.MINOR.PATCH formátumban. A Trunk nem fogadja el ugyanazon verzió újbóli közzétételét — növelni kell a számot.
• source — hivatkozás a Git tárolóra és a tag-re. A Trunk nem tárolja a forráskódot, ezért a tárolónak elérhetőnek kell lennie a klónozáshoz.
• platform — célplatform (iOS, macOS, tvOS, watchOS) és minimális SDK-verzió.
• license — licenc típusa. Ajánlott a MIT, Apache-2.0, BSD vagy más nyílt licenc megadása.

Közzététel előtt a podspec-et ellenőrizni kell a linter segítségével:

pod lib lint MyLibrary.podspec

A linter ellenőrzi a szintaxist, a kötelező mezők meglétét, a fájlútvonalak helyességét és a függőségek feloldhatóságát. Ha a lintelés során privát források (private specs) kerülnek használatra, a --sources zászló kerül hozzáadásra. A hálózati letöltés kihagyásához (csak helyi ellenőrzés) a --local-only zászló használatos.

Közzététel pod trunk push segítségével

A pod közzétételének fő parancsa — pod trunk push. Ez elküldi a podspec fájlt a Trunk szerverre, ahol teljes érvényesítésen esik át, és regisztrálásra kerül a nyilvános nyilvántartásban. Szintaxis:

pod trunk push MyLibrary.podspec

A --allow-warnings zászló engedélyezi a közzétételt figyelmeztetések esetén. Alapértelmezés szerint bármely figyelmeztetés (warning) blokkolja a közzétételt. Ha a kódtárnak ismert, a funkciót nem befolyásoló figyelmeztetései vannak, használhatja ezt a zászlót. Fontos: a hibák (errors) mindig blokkolják a közzétételt, a zászlóktól függetlenül.

A --synchronous zászló szinkronná teszi a kérést — a terminál megvárja az érvényesítés befejeződését a szerveren. Alapértelmezés szerint a parancs az elküldés után azonnal visszaadja a vezérlést, a szerver pedig aszinkron módon dolgozza fel a közzétételt. A szinkron mód CI/CD-ben hasznos, amikor a pipeline következő lépése a közzététel sikerességétől függ.

A --skip-import-validation zászló kihagyja a kódtár importjának ellenőrzését egy tesztprojektben. Ez felgyorsítja a közzétételt, de nem garantálja, hogy a kódtár ténylegesen lefordul. Csak akkor használja ezt a zászlót, ha biztos a build helyességében.

Példa közzétételre tipikus opciókkal:

pod trunk push MyLibrary.podspec \
  --allow-warnings \
  --synchronous \
  --skip-import-validation

Sikeres közzététel után a Trunk egy JSON-t ad vissza részletekkel:

  Congrats

  MyLibrary (0.1.0) successfully published

  Pod URL: https://cocoapods.org/pods/MyLibrary

A kódtár elérhetővé válik bármely iOS vagy macOS projekt Podfile-ján keresztül történő telepítéshez. Általában a CocoaPods keresési index adatai néhány percen belül frissülnek, de ritka esetekben az indexelés akár egy óráig is tarthat.

Fontos korlátozás: egy egyszer közzétett pod verzió nem törölhető. Ez azért van, hogy megakadályozza a már ezt a verziót használó projektek meghibásodását. Ha a közzététel hibával zárult, közzéteheti a következő verziót javítással, de a visszavonás lehetetlen. Kivétel — a pod trunk delete, amely csak a CocoaPods alkalmazottai számára elérhető, és szélsőséges esetekben alkalmazandó (licencsértés, rosszindulatú kód).

Kiadások és hozzáférés kezelése

A CocoaPods Trunk több parancsot biztosít a közzétett pod-ok adminisztrálásához:

Tulajdonosok hozzáadása

A pod közzétételi jogának másik fejlesztőre ruházásához a következő parancs használatos:

pod trunk add-owner MyLibrary developer@email.com

A végrehajtás után az új tulajdonos teljes hozzáférést kap a pod kezeléséhez: új verziók közzététele, más tulajdonosok hozzáadása és eltávolítása, a pod elavulttá nyilvánítása. Tulajdonos bármely regisztrált Trunk-felhasználó lehet — az előzetes regisztráció kötelező.

Tulajdonosok eltávolítása

Ha egy fejlesztő elhagyta a projektet, vagy többé nem rendelkezhet hozzáféréssel a pod-hoz:

pod trunk remove-owner MyLibrary developer@email.com

Tulajdonost csak a jelenlegi tulajdonos távolíthat el. A pod utolsó tulajdonosa nem távolítható el — először hozzá kell adni egy újat. Ez megakadályozza, hogy a pod tulajdonos nélkül maradjon.

Pod elavulttá nyilvánítása

Ha egy kódtár már nem támogatott, elavulttá (deprecated) nyilvánítható. Ez nem távolítja el a pod-ot a nyilvántartásból, de figyelmeztetést ad a felhasználóknak telepítéskor:

pod trunk deprecate MyLibrary

Opcionálisan megadható egy helyettesítő pod:

pod trunk deprecate MyLibrary --in-favor-of=NewLibrary

Elavult pod telepítésekor a CocoaPods figyelmeztetést jelenít meg a terminálban, és javasolja a megadott helyettesítőre való áttérést. Ez a helyes módja a kódtár támogatása befejezésének anélkül, hogy megtörné a meglévő projektek buildjét.

Pod információinak megtekintése

A pod-ral kapcsolatos információk a pod trunk info parancson keresztül érhetők el:

pod trunk info MyLibrary

A parancs megjeleníti a pod összes verzióját, a közzététel dátumát, a tulajdonosok listáját és az állapotot (aktív/elavult). Egy adott verzió részleteinek megtekintéséhez a pod spec cat MyLibrary 0.1.0 használatos.

Hibák és megoldásuk

A Trunk használata során a fejlesztők gyakran találkoznak tipikus hibákkal. Tekintsük át a leggyakoribbakat:

Hitelesítési hiba

Tünet: [!] Authentication failed. You need to register a session first.
Ok: A munkamenet-token hiányzik vagy lejárt. A tokenek korlátozott érvényességi idővel rendelkeznek (alapértelmezés szerint 30 nap inaktivitás után).
Megoldás: Futtassa újra a pod trunk register your@email.com 'Your Name' parancsot. Ha CI-t használ, ellenőrizze a COCOAPODS_TRUNK_TOKEN változó aktualitását, és szükség esetén generáljon új tokent.

Verzióütközés

Tünet: [!] You have already pushed version 0.1.0 for MyLibrary.
Ok: Megkísérelte egy létező verzió újbóli közzétételét. A Trunk nem engedélyezi a verziók felülírását.
Megoldás: Növelje a verziót a podspec-ben a szemantikus verziókezelésnek megfelelően. Ha hibát követett el a podspec-ben, tegye közzé a következő verziót a javítással.

Podspec érvényesítési hiba

Tünet: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Ok: A forrásfájlok elérési útja a source_files mezőben helytelenül van megadva.
Megoldás: Ellenőrizze az útvonalakat a podspec-ben, futtassa a pod lib lint parancsot lokálisan az összes hiba megszüntetéséig, majd ismételje meg a közzétételt. Használjon glob-mintákat: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Kapcsolódási időtúllépés

Tünet: [!] Connection to trunk.cocoapods.org failed. Timeout.
Ok: Hálózati problémák vagy a Trunk szerver átmeneti elérhetetlensége.
Megoldás: Ellenőrizze a szerver elérhetőségét: curl -I https://trunk.cocoapods.org. Ha a szerver válaszol, ismételje meg a parancsot néhány perc múlva. Lehet, hogy az IP-címe blokkolva van — próbálja más kapcsolatról vagy VPN-en keresztül.

Nincs hozzáférés a pod-hoz

Tünet: [!] You do not have permission to push to MyLibrary.
Ok: Nem Ön a pod tulajdonosa. Ez akkor történik, ha valaki már regisztrált egy pod-ot ezzel a névvel.
Megoldás: Lépjen kapcsolatba a pod jelenlegi tulajdonosával (a pod trunk info MyLibrary segítségével megtudható), és kérje meg, hogy adja hozzá Önt a pod trunk add-owner paranccsal. Ha a pod neve foglalt, fontoljon meg egy alternatív nevet.