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-а или аутоматски одређује пројекат у тренутном директоријуму. За пројекте са више target-ова потребно је навести --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-а који омогућава покретање израде при сваком push-у у репозиторијум.

# Пример шага сборки в 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...» долази до конфликта излазних датотека између различитих target-ова у workspace-у. Решење: подесите јединствене путање излаза за сваки target у Build Settings пројекта Xcode-а или користите нови build system, који је подразумевано укључен у Xcode 14 и новијим верзијама. Gym подржава обе варијанте преко флага --use_legacy_build_system.