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 تلقائياً نوع المشروع (هدف واحد أو 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"

# بناء مع تحديد طريقة التصدير
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 في تضمين bitcode في IPA. كانت Apple تتطلب bitcode لتطبيقات watchOS وtvOS، ولكن لنظام iOS يمكن تعطيل هذا المعامل لتقليل حجم الملف الثنائي. include_symbols يضم ملفات تصحيح الرموز .dSYM، اللازمة لترميز سجلات الأعطال من 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 يتيح تشغيل البنيات مع كل 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..."، يحدث تعارض في ملفات الإخراج بين الأهداف المختلفة في workspace. الحل: قم بتعيين مسارات إخراج فريدة لكل هدف في Build Settings لمشروع Xcode أو استخدم نظام البناء الجديد، والذي يتم تمكينه افتراضياً في Xcode 14 والإصدارات الأحدث. يدعم Gym كلا الخيارين عبر العلم --use_legacy_build_system.