Gym (Fastlane): mi ez, IPA-építés és automatizálás az alkalmazásfejlesztésben

Mi az a Gym (Fastlane)?

Gym (Fastlane) a Fastlane ökoszisztéma egyik összetevője, amely lehetővé teszi iOS-alkalmazások IPA formátumba építését egyetlen terminálparanccsal. Elvonatkoztatja az xcodebuild több tucat jelzővel történő meghívásának összetett folyamatát, és egyszerű felületet biztosít a fejlesztőnek ésszerű alapértelmezett értékekkel.

Az Xcode-ban az IPA építéséhez meg kell nyitni a projektet, ki kell választani a sémát, be kell állítani az Archive és Export funkciót, meg kell adni a terjesztési módot és várni a befejezésre. Az építés automatizálása a Gym-en keresztül kiküszöböli a kézi lépéseket és garantálja, hogy minden építés azonos paraméterekkel történik — ez kritikus a CI/CD pipeline kiszámíthatóságához.

A SwiftLee (2024) szerint a Gym-et használó csapatok 40%-kal kevesebb időt töltenek a kiadási folyamat beállításával a manuális, Xcode Organizeren keresztüli exportáláshoz képest. A Gym részletes építési naplókat is generál az egyes xcodebuild lépések jelzésével, ami leegyszerűsíti a sikertelen build-ek hibakeresését és a fordítási hibák elemzését.

Használja a Gym-et bármely iOS-projektben, amely rendszeres IPA-építést igényel teszteléshez vagy publikáláshoz — ez az egyetlen módja az azonos építési konfiguráció garantálásának a csapat összes gépén.

Hogyan épít a Gym IPA-t: folyamat és paraméterek

Az IPA-építés folyamata Gym-en keresztül

Az IPA-építés a Gym-en keresztül három egymást követő szakaszból áll: a projekt archiválása xcodebuild-en keresztül, az archívum exportálása bináris csomagba és csomagolás IPA formátumba aláírással. A Gym automatikusan meghatározza a projekt típusát (single target vagy workspace) és kiválasztja a megfelelő építési módszert.

Az archiválási szakaszban a Gym elindítja az xcodebuild archive-ot a projektben megadott séma és konfiguráció paramétereivel. Az .xcarchive archívum sikeres létrehozása után a Gym elindítja az xcodebuild -exportArchive-ot a kiválasztott exportálási módszerrel. IPA-export az .xcarchive archívum konvertálásának folyamata .ipa telepítőfájllá az összes szükséges erőforrás és aláírás belefoglalásával.

Az építés export paraméterei

Az exportálási módszer meghatározza az IPA aláírásához használandó Provisioning Profile típusát. A Gym négy módszert támogat: development hibakereséshez fejlesztői eszközökön, app-store publikáláshoz az App Store-ban, ad-hoc béta teszteléshez korlátozott számú eszközön és enterprise vállalati terjesztéshez.

További paraméterek közé tartozik az export_options_plist megadása a pontos exportálás beállításához, a Swift overlay elnyomása az IPA méretének csökkentéséhez és a bitcode kezelése. A Gym támogatja a szimulátorhoz való építést is a --skip_package_ipa jelzőn keresztül, ami hasznos a kód gyors ellenőrzéséhez teljes exportálás nélkül.

# Alapvető IPA build a Gym segítségével
fastlane gym --workspace "MyApp.xcworkspace" --scheme "MyApp"

# Build az exportálási mód megadásával
fastlane gym --export_method app-store

# Csak archívum build IPA-export nélkül
fastlane gym --skip_package_ipa

A Gym beállítása Gymfile-on keresztül

Gymfile egy Fastlane konfigurációs fájl, amely az összes építési paramétert strukturált Ruby formátumban tárolja. Ellentétben a jelzők parancssoron keresztüli átadásával, a Gymfile lehetővé teszi a konfiguráció rögzítését a tárolóban és garantálja, hogy az összes fejlesztő és CI azonos építési beállításokat használ.

# Gymfile — build-konfiguráció
workspace("MyApp.xcworkspace")
scheme("MyApp")
export_method(:app-store)
configuration("Release")
output_directory("./build")
output_name("MyApp.ipa")
include_symbols(true)
include_bitcode(false)

A Gymfile-ban lévő export_method paraméter megfelel az Apple Developer Portal profiltípusainak. App Store kiadásokhoz :app-store használatos, teszteléshez — :development vagy :ad-hoc. A configuration paraméter határozza meg az építési konfigurációt: Release kiadásokhoz vagy Debug hibakereső verziókhoz.

Az include_bitcode paraméter szabályozza a bitcode IPA-ba való belefoglalását. Az Apple megkövetelte a bitcode-ot a watchOS és tvOS alkalmazásokhoz, de iOS esetén ez a paraméter kikapcsolható a bináris fájl méretének csökkentésére. Az include_symbols tartalmazza a .dSYM szimbolikus hibakereső fájlokat, amelyek szükségesek a crash naplók szimbolizálásához az App Store Connect-ből vagy harmadik féltől származó monitorozó szolgáltatásokból.

A Gymfile további paraméterei közé tartozik az export_options_plist egyedi export plist fájlhoz, a silent a felesleges naplókimenet elnyomásához és a build_path az ideiglenes építési könyvtár megadásához. Ezek a paraméterek hasznosak a Gym komplex CI/CD pipeline-okba való integrálásakor, amelyek speciális követelményekkel rendelkeznek az artefaktumokra vonatkozóan.

Gym parancsok alkalmazások építéséhez

Parancs felület A Gym alapvető paramétereket tartalmaz tipikus építési forgatókönyvekhez és kiterjesztett jelzőket a viselkedés pontos beállításához. A legtöbb paraméter átadható parancssoron és Gymfile-on keresztül is, a parancssori argumentumok elsőbbséget élveznek a konfigurációs fájllal szemben.

A fastlane gym parancs paraméterek nélkül a Gymfile beállításait használja, vagy automatikusan meghatározza a projektet az aktuális könyvtárban. Több célponttal rendelkező projekteknél meg kell adni a --scheme és --workspace paramétereket a cél építési konfiguráció helyes kiválasztásához.

Tipikus építési parancsok

Gyors hibakereső buildhez a fastlane gym --export_method development használatos — ez Development profillal épít IPA-t a fejlesztői eszközökre telepítéshez. IPA-építés az App Store-hoz a --export_method app-store jelzőt és a Distribution tanúsítvány használatát igényli, amelyet előre be kell állítani a Match-ben vagy a Keychain-ben.

# Build az App Store-hoz egyéni névvel
fastlane gym --export_method app-store --output_name "Release_1.0.ipa"

# Build archívum előtti tisztítással
fastlane gym --clean --configuration Debug

# Build szimulátorhoz IPA nélkül
fastlane gym --skip_package_ipa --destination "generic/platform=iOS Simulator"

A --clean jelző törli az előző építés ideiglenes fájljait az indítás előtt, ami megakadályozza az elavult gyorsítótár használatát és tiszta build-et garantál. A --destination jelző lehetővé teszi a célplatform megadását az építéshez: iOS Simulator, iOS Device vagy macOS Catalyst.

A Gym integrálása CI/CD pipeline-ba

A Gym integrálása CI/CD-vel szabványos gyakorlat a folyamatos szállításra törekvő iOS fejlesztőcsapatok számára. A Gym a GitHub Actions, GitLab CI, Bitrise vagy Jenkins pipeline-okban indul a tesztelési szakasz után és a TestFlight-ba vagy App Store-ba küldés előtt.

Egy tipikus iOS CI/CD pipeline tartalmazza: a tároló klónozását, a függőségek telepítését CocoaPods vagy SPM segítségével, a tanúsítványok beállítását Match-en keresztül, az IPA építését Gym-en keresztül és a feltöltést Pilot vagy Deliver segítségével. GitLab CI a GitLab folyamatos integrációs rendszere, amely lehetővé teszi build-ek indítását minden egyes tárolóba push-nál.

# Build-lépés példa a GitLab CI-ben
fastlane gym --scheme "MyApp" \
      --export_method app-store \
      --output_directory "$CI_PROJECT_DIR/build"
      
# IPA mentése build-összetevőként
cp "build/MyApp.ipa" "$CI_PROJECT_DIR/artifacts/"

A Gym CI-ben való helyes működéséhez be kell állítani a xcodebuild hozzáférését a Keychain-hez tanúsítványokkal. Ez a security unlock-keychain paranccsal történik a Gym elindítása előtt. Ha Match-et használ, a tanúsítványok automatikusan települnek és külön Keychain beállítás nem szükséges — a Match maga hoz létre ideiglenes kulcstartót az építéshez.

Sikeres építés után az IPA továbbítható a pipeline következő lépéseihez: feltöltés a TestFlight-ba Pilot-on keresztül vagy küldés az App Store Connect-be Deliver-en keresztül. Állítsa be a CI rendszer környezeti változóit az Apple Developer hitelesítő adatok tárolásához, beleértve a FASTLANE_APPLE_API_KEY és MATCH_PASSWORD értékeket, hogy a pipeline összes szakasza interaktív bevitel nélkül működjön.

Gyakori Gym építési hibák

A Gym használatakor a fejlesztők gyakran találkoznak hibákkal, amelyek az xcodebuild helytelen konfigurációjához, tanúsítványok hiányához vagy az Xcode verziók inkompatibilitásához kapcsolódnak. A hibák diagnosztizálása a Gym teljes építési naplójának elemzésével kezdődik, amely minden parancs befejezése után megjelenik a konzolban.

A «error: No matching provisioning profiles found» hiba a kiválasztott exportálási módszerhez tartozó megfelelő Provisioning Profile hiányát jelzi. Megoldás: győződjön meg arról, hogy a Match vagy Keychain tartalmazza a megfelelő profilt a megadott export_method számára. Provisioning Profile meg kell egyeznie az alkalmazás azonosítójával és a tanúsítvány típusával (Development vagy Distribution) az IPA sikeres aláírásához.

A «error: Signing for requires a development team» hiba akkor fordul elő, amikor a projektben nincs megadva fejlesztői csapat. Megoldás: adja hozzá a DEVELOPMENT_TEAM paramétert a projekt építési konfigurációjához, vagy adja meg a team_id-t a Gymfile-ban az export_team_id paraméteren keresztül. Ez különösen fontos olyan projekteknél, amelyek több Apple Developer fiókkal dolgoznak.

A «error: Multiple commands produce...» hibánál kimeneti fájlok közötti konfliktus lép fel a különböző célpontok között a workspace-ben. Megoldás: állítson be egyedi kimeneti útvonalakat minden célponthoz az Xcode projekt Build Settings beállításaiban, vagy használja az új build rendszert, amely alapértelmezetten engedélyezve van az Xcode 14 és újabb verziókban. A Gym mindkét változatot támogatja a --use_legacy_build_system jelzőn keresztül.