Gym (Fastlane): co to je, sestavení IPA a automatizace ve vývoji aplikací

Co je Gym (Fastlane)?

Gym (Fastlane) je součást ekosystému Fastlane, která zajišťuje sestavování iOS aplikací do formátu IPA přes jeden terminálový příkaz. Abstrahuje složitý proces volání xcodebuild s desítkami příznaků a poskytuje vývojáři jednoduché rozhraní s rozumnými výchozími hodnotami.

V Xcode je pro sestavení IPA třeba otevřít projekt, vybrat schéma, nastavit Archive a Export, určit metodu distribuce a počkat na dokončení. Automatizace sestavení přes Gym odstraňuje ruční kroky a zaručuje, že každé sestavení probíhá se stejnými parametry — to je kritické pro předvídatelnost CI/CD pipeline.

Podle SwiftLee (2024) tráví týmy používající Gym pro sestavení o 40% méně času nastavováním release procesu ve srovnání s ručním exportem přes Xcode Organizer. Gym také generuje podrobné logy sestavení s uvedením každého kroku xcodebuild, což zjednodušuje ladění neúspěšných buildů a analýzu chyb kompilace.

Používejte Gym v jakémkoli iOS projektu, který vyžaduje pravidelné sestavení IPA pro testování nebo publikaci — je to jediný způsob, jak zaručit identickou konfiguraci sestavení na všech počítačích v týmu.

Jak Gym sestavuje IPA: proces a parametry

Proces sestavení IPA přes Gym

Sestavení IPA přes Gym se skládá ze tří po sobě jdoucích fází: archivace projektu přes xcodebuild, export archivu do binárního balíčku a zabalení do formátu IPA s podpisem. Gym automaticky určuje typ projektu (single target nebo workspace) a vybírá správnou metodu sestavení.

Ve fázi archivace Gym spouští xcodebuild archive s parametry schématu a konfigurace uvedenými v projektu. Po úspěšném vytvoření archivu .xcarchive Gym spouští xcodebuild -exportArchive s vybranou metodou exportu. Export IPA je proces převodu archivu .xcarchive na instalační soubor .ipa se zahrnutím všech potřebných zdrojů a podpisů.

Parametry exportu sestavení

Metoda exportu určuje typ Provisioning Profile, který bude použit pro podepsání IPA. Gym podporuje čtyři metody: development pro ladění na zařízeních vývojářů, app-store pro publikaci v App Store, ad-hoc pro beta testování na omezeném počtu zařízení a enterprise pro firemní distribuci.

Další parametry zahrnují určení export_options_plist pro přesné nastavení exportu, potlačení Swift overlay pro zmenšení velikosti IPA a správu bitcode. Gym také podporuje sestavení pro simulátor přes příznak --skip_package_ipa, což je užitečné pro rychlou kontrolu kódu bez plného exportu.

# Základní sestavení IPA přes Gym
fastlane gym --workspace "MyApp.xcworkspace" --scheme "MyApp"

# Sestavení s uvedením metody exportu
fastlane gym --export_method app-store

# Sestavení pouze archivu bez exportu IPA
fastlane gym --skip_package_ipa

Nastavení Gym přes Gymfile

Gymfile je konfigurační soubor Fastlane, který ukládá všechny parametry sestavení ve strukturovaném formátu Ruby. Na rozdíl od předávání příznaků přes příkazový řádek umožňuje Gymfile zafixovat konfiguraci v repozitáři a zaručit, že všichni vývojáři a CI používají identická nastavení sestavení.

# Gymfile — konfigurace sestavení
workspace("MyApp.xcworkspace")
scheme("MyApp")
export_method(:app-store)
configuration("Release")
output_directory("./build")
output_name("MyApp.ipa")
include_symbols(true)
include_bitcode(false)

Parametr export_method v Gymfile odpovídá typům profilů z Apple Developer Portal. Pro App Store releasy se používá :app-store, pro testování — :development nebo :ad-hoc. Parametr configuration určuje konfiguraci sestavení: Release pro releasy nebo Debug pro ladící verze.

Parametr include_bitcode řídí zahrnutí bitcode do IPA. Apple vyžadoval bitcode pro watchOS a tvOS aplikace, ale pro iOS lze tento parametr vypnout pro zmenšení velikosti binárního souboru. include_symbols zahrnuje soubory symbolického ladění .dSYM, které jsou nezbytné pro symbolizaci crash logů z App Store Connect nebo sledovacích služeb třetích stran.

Další parametry Gymfile zahrnují export_options_plist pro vlastní plist soubor exportu, silent pro potlačení nadbytečného výstupu v logách a build_path pro určení dočasného adresáře sestavení. Tyto parametry jsou užitečné při integraci Gym do složitých CI/CD pipeline se speciálními požadavky na artefakty.

Příkazy Gym pro sestavování aplikací

Rozhraní příkazů Gym zahrnuje základní parametry pro typické scénáře sestavení a rozšířené příznaky pro přesné nastavení chování. Většinu parametrů lze předat jak přes příkazový řádek, tak přes Gymfile, přičemž argumenty příkazového řádku mají prioritu před konfiguračním souborem.

Příkaz fastlane gym bez parametrů používá nastavení z Gymfile nebo automaticky určí projekt v aktuálním adresáři. U projektů s více cíli je třeba určit --scheme a --workspace pro správný výběr cílové konfigurace sestavení.

Typické příkazy sestavení

Pro rychlé ladící sestavení se používá fastlane gym --export_method development — sestaví IPA s Development profilem pro instalaci na zařízení vývojářů. Sestavení IPA pro App Store vyžaduje příznak --export_method app-store a použití Distribution certifikátu, který musí být předem nastaven v Match nebo Keychain.

# Sestavení pro App Store s vlastním názvem
fastlane gym --export_method app-store --output_name "Release_1.0.ipa"

# Sestavení s vyčištěním před archivací
fastlane gym --clean --configuration Debug

# Sestavení pro simulátor bez IPA
fastlane gym --skip_package_ipa --destination "generic/platform=iOS Simulator"

Příznak --clean odstraňuje dočasné soubory předchozího sestavení před spuštěním, což zabraňuje použití zastaralé cache a zaručuje čistý build. Příznak --destination umožňuje určit cílovou platformu pro sestavení: iOS Simulator, iOS Device nebo macOS Catalyst.

Integrace Gym do CI/CD pipeline

Integrace Gym s CI/CD je standardní praxí pro týmy iOS vývojářů usilujících o kontinuální doručování. Gym se spouští v pipeline GitHub Actions, GitLab CI, Bitrise nebo Jenkins po fázi testování a před odesláním do TestFlight nebo App Store.

Typická iOS CI/CD pipeline zahrnuje: klonování repozitáře, instalaci závislostí přes CocoaPods nebo SPM, nastavení certifikátů přes Match, sestavení IPA přes Gym a nahrání přes Pilot nebo Deliver. GitLab CI je systém kontinuální integrace od GitLab, který umožňuje spouštět sestavení při každém pushi do repozitáře.

# Příklad kroku sestavení v GitLab CI
fastlane gym --scheme "MyApp" \
      --export_method app-store \
      --output_directory "$CI_PROJECT_DIR/build"
      
# Uložení IPA jako artefaktu sestavení
cp "build/MyApp.ipa" "$CI_PROJECT_DIR/artifacts/"

Pro správnou funkci Gym v CI je třeba nastavit xcodebuild přístup do Keychain s certifikáty. To se provádí pomocí příkazu security unlock-keychain před spuštěním Gym. Pokud se používá Match, certifikáty se instalují automaticky a samostatné nastavení Keychain není třeba — Match sám vytváří dočasnou sadu klíčů pro sestavení.

Po úspěšném sestavení může být IPA předán do dalších kroků pipeline: nahrání do TestFlight přes Pilot nebo odeslání do App Store Connect přes Deliver. Nastavte proměnné prostředí CI systému pro ukládání přihlašovacích údajů Apple Developer, včetně FASTLANE_APPLE_API_KEY a MATCH_PASSWORD, aby všechny fáze pipeline fungovaly bez interaktivního vstupu.

Typické chyby sestavení Gym

Při používání Gym se vývojáři často setkávají s chybami souvisejícími s nesprávnou konfigurací xcodebuild, chybějícími certifikáty nebo nekompatibilitou verzí Xcode. Diagnostika chyb Gym začíná analýzou úplného logu sestavení, který se zobrazí v konzoli po dokončení každého příkazu.

Chyba «error: No matching provisioning profiles found» indikuje chybějící vhodný Provisioning Profile pro vybranou metodu exportu. Řešení: ujistěte se, že Match nebo Keychain obsahuje správný profil pro uvedený export_method. Provisioning Profile musí odpovídat identifikátoru aplikace a typu certifikátu (Development nebo Distribution) pro úspěšné podepsání IPA.

Chyba «error: Signing for requires a development team» nastává, když v projektu není uveden vývojářský tým. Řešení: přidejte DEVELOPMENT_TEAM do konfigurace sestavení projektu nebo uveďte team_id v Gymfile přes parametr export_team_id. To je zvláště důležité pro projekty pracující s více Apple Developer účty.

Při chybě «error: Multiple commands produce...» dochází ke konfliktu výstupních souborů mezi různými cíli v workspace. Řešení: nastavte jedinečné cesty výstupu pro každý cíl v Build Settings projektu Xcode nebo použijte nový build system, který je ve výchozím nastavení zapnutý v Xcode 14 a novějších. Gym podporuje obě varianty přes příznak --use_legacy_build_system.