Gym (Fastlane): какво е това, изграждане на IPA и автоматизация в разработката на приложения

Какво е Gym (Fastlane)?

Gym (Fastlane) е компонент на екосистемата Fastlane, който осигурява изграждане на iOS приложения във формат IPA чрез една терминална команда. Той абстрахира сложния процес на извикване на xcodebuild с десетки флагове и предоставя на разработчика прост интерфейс с разумни стойности по подразбиране.

В Xcode за изграждане на IPA е необходимо да отворите проекта, да изберете схема, да настроите Archive и Export, да посочите метод на разпространение и да изчакате завършване. Автоматизация на изграждането чрез Gym елиминира ръчните стъпки и гарантира, че всяко изграждане се изпълнява с еднакви параметри — това е критично за предвидимостта на CI/CD пайплайна.

Според SwiftLee (2024), екипите, които използват Gym за изграждане, отделят 40% по-малко време за настройка на процеса на издаване в сравнение с ръчния експорт чрез Xcode Organizer. Gym също така генерира подробни логове за изграждане с посочване на всяка стъпка на xcodebuild, което опростява отстраняването на грешки при неуспешни билдове и анализ на грешки при компилация.

Използвайте Gym във всеки iOS проект, който изисква редовно изграждане на IPA за тестване или публикуване — това е единственият начин да гарантирате идентична конфигурация за изграждане на всички машини в екипа.

Как Gym изгражда IPA: процес и параметри

Процес на изграждане на IPA чрез Gym

Изграждането на IPA чрез Gym се състои от три последователни етапа: архивиране на проекта чрез xcodebuild, експорт на архива в двоичен пакет и опаковане във формат IPA с подпис. Gym автоматично определя типа на проекта (single target или workspace) и избира правилния метод за изграждане.

На етапа на архивиране Gym изпълнява xcodebuild archive с параметрите на схемата и конфигурацията, посочени в проекта. След успешно създаване на архива .xcarchive, Gym изпълнява xcodebuild -exportArchive с избрания метод за експорт. Експорт на IPA е процесът на конвертиране на архива .xcarchive в инсталационен файл .ipa, включващ всички необходими ресурси и подписи.

Параметри за експорт на изграждане

Методът за експорт определя типа на Provisioning Profile, който ще се използва за подписване на IPA. Gym поддържа четири метода: development за отстраняване на грешки на устройства на разработчици, app-store за публикуване в App Store, ad-hoc за бета тестване на ограничен брой устройства и enterprise за корпоративно разпространение.

Допълнителните параметри включват посочване на export_options_plist за прецизна настройка на експорта, потискане на Swift overlay за намаляване на размера на IPA и управление на биткод. Gym също поддържа изграждане за симулатор чрез флага --skip_package_ipa, което е полезно за бърза проверка на код без пълен експорт.

# Базовая сборка IPA через Gym
fastlane gym --workspace "MyApp.xcworkspace" --scheme "MyApp"

# Сборка с указанием метода экспорта
fastlane gym --export_method app-store

# Сборка только архива без экспорта IPA
fastlane gym --skip_package_ipa

Настройка на Gym чрез Gymfile

Gymfile е конфигурационен файл на Fastlane, който съхранява всички параметри за изграждане в структуриран Ruby формат. За разлика от предаването на флагове чрез команден ред, Gymfile позволява фиксиране на конфигурацията в хранилището и гарантира, че всички разработчици и CI използват идентични настройки за изграждане.

# Gymfile — конфигурация сборки
workspace("MyApp.xcworkspace")
scheme("MyApp")
export_method(:app-store)
configuration("Release")
output_directory("./build")
output_name("MyApp.ipa")
include_symbols(true)
include_bitcode(false)

Параметърът export_method в Gymfile съответства на типовете профили от Apple Developer Portal. За App Store версии се използва :app-store, за тестване — :development или :ad-hoc. Параметърът configuration определя конфигурацията за изграждане: Release за версии или Debug за версии за отстраняване на грешки.

Параметърът include_bitcode управлява включването на биткод в IPA. Apple изискваше биткод за watchOS и tvOS приложения, но за iOS този параметър може да бъде изключен за намаляване на размера на двоичния файл. include_symbols включва файлове за символично отстраняване на грешки .dSYM, които са необходими за символизация на crash логове от App Store Connect или услуги за мониторинг на трети страни.

Допълнителните параметри на Gymfile включват export_options_plist за персонализиран plist файл за експорт, silent за потискане на излишния изход в логовете и build_path за посочване на временна директория за изграждане. Тези параметри са полезни при интегриране на Gym в сложни CI/CD пайплайни със специални изисквания за артефакти.

Команди на Gym за изграждане на приложения

Интерфейс за команди Gym включва основни параметри за типични сценарии за изграждане и разширени флагове за прецизна настройка на поведението. Повечето параметри могат да се предават както чрез команден ред, така и чрез Gymfile, като аргументите на командния ред имат приоритет пред конфигурационния файл.

Командата fastlane gym без параметри използва настройките от Gymfile или автоматично определя проекта в текущата директория. За проекти с множество цели трябва да се посочат --scheme и --workspace за правилен избор на целева конфигурация за изграждане.

Типични команди за изграждане

За бързо изграждане за отстраняване на грешки се използва fastlane gym --export_method development — тя изгражда IPA с Development профил за инсталиране на устройства на разработчици. Изграждане на IPA за App Store изисква флага --export_method app-store и използване на Distribution сертификат, който трябва да бъде предварително настроен в Match или Keychain.

# Сборка для App Store с кастомным именем
fastlane gym --export_method app-store --output_name "Release_1.0.ipa"

# Сборка с очисткой перед архивацией
fastlane gym --clean --configuration Debug

# Сборка для симулятора без IPA
fastlane gym --skip_package_ipa --destination "generic/platform=iOS Simulator"

Флагът --clean изтрива временните файлове от предишното изграждане преди стартиране, което предотвратява използването на остарял кеш и гарантира чисто изграждане. Флагът --destination позволява посочване на целева платформа за изграждане: iOS Simulator, iOS Device или macOS Catalyst.

Интеграция на Gym в CI/CD пайплайн

Интеграция на Gym с CI/CD е стандартна практика за екипи за iOS разработка, стремящи се към непрекъсната доставка. Gym се стартира в пайплайнове на GitHub Actions, GitLab CI, Bitrise или Jenkins след фазата на тестване и преди изпращане до TestFlight или App Store.

Типичният iOS CI/CD пайплайн включва: клониране на хранилището, инсталиране на зависимости чрез CocoaPods или SPM, настройка на сертификати чрез Match, изграждане на IPA чрез Gym и качване чрез Pilot или Deliver. GitLab CI е система за непрекъсната интеграция от GitLab, която позволява стартиране на изграждания при всяко публикуване в хранилището.

# Пример шага сборки в GitLab CI
fastlane gym --scheme "MyApp" \
      --export_method app-store \
      --output_directory "$CI_PROJECT_DIR/build"
      
# Сохранение IPA как артефакта сборки
cp "build/MyApp.ipa" "$CI_PROJECT_DIR/artifacts/"

За правилна работа на Gym в CI е необходимо да се настрои достъп на xcodebuild до Keychain със сертификати. Това се прави чрез командата security unlock-keychain преди стартиране на Gym. Ако се използва Match, сертификатите се инсталират автоматично и отделна настройка на Keychain не е необходима — Match сам създава временна ключодържателница за изграждане.

След успешно изграждане IPA може да бъде предаден на следващите стъпки от пайплайна: качване в TestFlight чрез Pilot или изпращане до App Store Connect чрез Deliver. Настройте променливите на средата на CI системата за съхранение на идентификационни данни за Apple Developer, включително FASTLANE_APPLE_API_KEY и MATCH_PASSWORD, така че всички етапи от пайплайна да работят без интерактивно въвеждане.

Типични грешки при изграждане с Gym

При използване на Gym разработчиците често се сблъскват с грешки, свързани с неправилна конфигурация на xcodebuild, липсващи сертификати или несъвместимост на версиите на Xcode. Диагностика на грешки на Gym започва с анализ на пълния лог за изграждане, който се показва в конзолата след завършване на всяка команда.

Грешката «error: No matching provisioning profiles found» показва липса на подходящ Provisioning Profile за избрания метод за експорт. Решение: уверете се, че Match или Keychain съдържа правилен профил за посочения export_method. Provisioning Profile трябва да съответства на идентификатора на приложението и типа на сертификата (Development или Distribution) за успешно подписване на IPA.

Грешката «error: Signing for requires a development team» възниква, когато в проекта не е посочен екип за разработка. Решение: добавете DEVELOPMENT_TEAM в конфигурацията за изграждане на проекта или посочете team_id в Gymfile чрез параметъра export_team_id. Това е особено важно за проекти, работещи с множество акаунти в Apple Developer.

При грешката «error: Multiple commands produce...» възниква конфликт на изходни файлове между различни цели в workspace. Решение: настройте уникални пътища за изход за всяка цел в Build Settings на проекта в Xcode или използвайте новата build система, която е включена по подразбиране в Xcode 14 и по-нови версии. Gym поддържа и двата варианта чрез флага --use_legacy_build_system.