Gym (Fastlane): چیست، ساخت IPA و اتوماسیون در توسعه برنامه‌های کاربردی

Gym (Fastlane) چیست؟

Gym (Fastlane) جزئی از اکوسیستم Fastlane است که ساخت برنامه‌های iOS را به صورت IPA از طریق یک دستور ترمینال انجام می‌دهد. آن فرآیند پیچیده فراخوانی xcodebuild با ده‌ها فلگ را چکیده کرده و یک رابط ساده با مقادیر پیش‌فرض مناسب در اختیار توسعه‌دهنده قرار می‌دهد.

در Xcode برای ساخت IPA باید پروژه را باز کرد، شما را انتخاب کرد، Archive و Export را تنظیم کرد، روش توزیع را مشخص کرد و منتظر تکمیل شد. اتوماسیون ساخت از طریق Gym مراحل دستی را حذف کرده و تضمین می‌کند که هر ساخت با پارامترهای یکسان انجام شود — این برای قابل پیش‌بینی بودن خط لوله CI/CD حیاتی است.

به استناد به SwiftLee (2024)، تیم‌هایی که از Gym برای ساخت استفاده می‌کنند، ۴۰٪ زمان کمتری برای تنظیم فرآیند انتشار در مقایسه با استخراج دستی از طریق Xcode Organizer صرف می‌کنند. Gym همچنین ثبت‌های مفصل ساخت را با کل مرحله xcodebuild تولید می‌کند که اشکال‌زدایی بیلدهای ناموفق و تجزیه و تحلیل خطاهای کامپایلر را آسان می‌کند.

از Gym در هر پروژه iOS که نیازمند ساخت منظم IPA برای آزمایش یا انتشار است استفاده کنید — این تنها راه تضمین تنظیمات ساخت یکسان در تمام ماشین‌های تیم است.

Gym چگونه IPA می‌سازد: فرآیند و پارامترها

فرآیند ساخت IPA از طریق Gym

ساخت IPA از طریق Gym شامل سه مرحله پیاپی است: بایگانی شدن پروژه از طریق xcodebuild، استخراج بایگانی به بسته دودویی و بسته‌بندی در قالب IPA با امضا. Gym به طور خودکار نوع پروژه (تک تارگت یا 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 و مدیریت bitcode است. Gym همچنین از ساخت برای شبیه‌ساز از طریق فلگ --skip_package_ipa پشتیبانی می‌کند که برای بررسی سریع کد بدون استخراج کامل مفید است.

# ساخت پایه IPA با Gym
fastlane gym --workspace "MyApp.xcworkspace" --scheme "MyApp"

# ساخت با تعیین روش export
fastlane gym --export_method app-store

# ساخت فقط آرشیو بدون export 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 ورود bitcode به IPA را کنترل می‌کند. Apple برای برنامه‌های watchOS و tvOS bitcode را نیاز داشت، اما برای 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 به‌عنوان artifact ساخت
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 تنظیم کنید یا از سیستم ساخت جدید استفاده کنید که در Xcode 14 و بالاتر به صورت پیش‌فرض فعال است. Gym از هر دو گزینه از طریق فلگ --use_legacy_build_system پشتیبانی می‌کند.