Scheme: ماهيته وإعداده وتشغيله في Xcode

ما هو Scheme في Xcode؟

Scheme في Xcode هو ملف XML (بامتداد .xcscheme) يصف تسلسل الإجراءات ومعاملاتها لبناء التطبيق وتحليله. يرتبط كل Scheme بهدف واحد أو أكثر ويحدد الإعداد (Debug أو Release أو AdHoc) الذي سيُنفَّذ به كل إجراء. Scheme هو ما يعادل Build Variant في Android، لكن بهيكل أكثر مرونة: يمكن للمخطط الواحد أن يتضمن أهدافًا مختلفة لإجراءات مختلفة.

ينشئ Xcode تلقائيًا مخططًا لكل هدف عند أول فتح للمشروع. اسم المخطط الافتراضي يطابق اسم الهدف. إذا كان المشروع يتضمن هدف اختبار، يضيفه Xcode تلقائيًا إلى إجراء Test في مخطط الهدف الرئيسي. بالنسبة للمشاريع ذات الأهداف المتعددة (التطبيق الرئيسي + watchOS + الإضافة)، ينشئ Xcode مخططًا منفصلًا لكل منها، ولكن يمكن أيضًا إنشاء مخطط واحد يبني جميع الأهداف دفعة واحدة.

تُخزَّن المخططات في دليل xcshareddata/xcschemes/ (للمشتركة) أو xcuserdata/<user>/xcschemes/ (للخاصة). المخططات المشتركة تصل إلى Git ويستخدمها الفريق بأكمله. المخططات الخاصة تُخزَّن محليًا ولا تتم مزامنتها. ملف .xcscheme بتنسيق XML مع عنصر جذر <Scheme>. يوجد في الداخل كتل لكل إجراء: BuildAction وTestAction وLaunchAction وProfileAction وAnalyzeAction وArchiveAction.

بنية ملف .xcscheme

.xcscheme هو ملف XML يمكن تحريره يدويًا أو عبر Xcode. العناصر الرئيسية: <BuildAction> (قائمة الأهداف المراد بناؤها)، <TestAction> (روابط لأهداف الاختبار)، <LaunchAction> (إعداد التشغيل)، <ProfileAction> و<AnalyzeAction> و<ArchiveAction>. تحتوي كل كتلة على سمة buildConfiguration التي تحدد الإعداد (Debug/Release) الذي سيُستخدم لهذا الإجراء.

إجراءات Scheme: Build وRun وTest وProfile وAnalyze وArchive

Scheme يتكون من ستة إجراءات، يمكن إعداد كل منها بشكل مستقل. يحدد إجراء Build الأهداف التي سيتم بناؤها وترتيبها. يحدد إجراء Run كيفية تشغيل التطبيق: بأي وسائط ومتغيرات بيئة وأي إعداد. يحدد إجراء Test الاختبارات التي سيتم تنفيذها وخيارات تغطية الكود المفعلة. ينفذ إجراء Profile التشغيل بأدوات Instruments للتنميط. ينفذ إجراء Analyze التحليل الساكن للكود باستخدام Clang Static Analyzer. يبني إجراء Archive للنشر في App Store أو التوزيع عبر AdHoc.

لكل إجراء يمكن تعيين إعداد بناء منفصل. عادةً يُستخدم Debug لـ Run وTest وRelease لـ Archive. يحدد إعداد البناء مجموعة أعلام المترجم والتحسينات ومعلومات التصحيح. يوفر Xcode إعدادين قياسيين: Debug (بدون تحسينات، مع رموز التصحيح) وRelease (مع التحسينات، بدون معلومات التصحيح). يمكن للمطور إضافة إعدادات مخصصة عبر project.xcconfig.

إجراء Archive مهم بشكل خاص: فهو ينشئ ملف .xcarchive يتم تصديره لاحقًا إلى .ipa لتطبيق App Store أو AdHoc. يستخدم إجراء Archive إعداد Release افتراضيًا، لكن يمكن التبديل إلى AdHoc أو Distribution. يتوفر في إجراء Archive أيضًا العلم revealArchiveInOrganizer: بعد اكتمال الأرشفة، يفتح Xcode Organizer لإجراء المزيد من العمليات على الأرشيف.

<!-- مثال على .xcscheme لتطبيق iOS -->
<Scheme
  LastUpgradeVersion = "1500"
  version = "1.7">

  <BuildAction
    parallelizeBuildables = "YES"
    buildImplicitDependencies = "YES">
    <BuildActionEntries>
      <BuildActionEntry
        buildForTesting = "YES"
        buildForRunning = "YES"
        buildForProfiling = "YES"
        buildForArchiving = "YES"
        buildForAnalyzing = "YES">
        <BuildableReference
          BuildableIdentifier = "primary"
          BlueprintIdentifier = "ABCD1234"
          BuildableName = "MyApp.app"
          BlueprintName = "MyApp"
          ReferencedContainer = "container:MyApp.xcodeproj">
        </BuildableReference>
      </BuildActionEntry>
    </BuildActionEntries>
  </BuildAction>

  <LaunchAction
    buildConfiguration = "Debug"
    selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
    enableAddressSanitizer = "YES">
  </LaunchAction>
</Scheme>

إنشاء وإعداد Scheme

أدوات التعقيم التشخيصية

إنشاء مخطط جديد يتم من خلال قائمة Xcode: Product → Scheme → New Scheme أو بزر "+" في لوحة Scheme (بجوار زر Run). عند الإنشاء يتم اختيار الهدف الذي سيُنشأ له المخطط. ينسخ Xcode تلقائيًا الإعدادات من مخطط موجود إذا تم تحديده كـ "duplicate". تُحفظ المخططات الجديدة على أنها خاصة افتراضيًا — لنشرها للفريق تحتاج إلى تفعيل Shared في Manage Schemes.

نافذة Edit Scheme (Product → Scheme → Edit Scheme) تحتوي على ستة ألسنة بعدد الإجراءات. في كل لسان يمكن تغيير إعداد البناء ووسائط التشغيل ومتغيرات البيئة وأعلام التشخيص. في لسان Run تتوفر الخيارات: executable (أي ملف ثنائي سيتم تشغيله)، wait for executable to be launched (لتصحيح أخطاء العمليات المشغلة)، debugger (LLDB أو None)، launch arguments وenvironment variables وخيارات موسعة (Address Sanitizer وThread Sanitizer وMain Thread Checker وMemory Management).

للتشخيص، Address Sanitizer (ASan) يكتشف الوصول خارج الحدود وuse-after-free وأخطاء ذاكرة أخرى في كود C/C++/ObjC. Thread Sanitizer (TSan) يكتشف حالات السباق (data races) في الكود متعدد الخيوط. Undefined Behavior Sanitizer (UBSan) يكشف السلوك غير المحدد، مثل تجاوز int بالإشارة. هذه الخيارات متاحة في Edit Scheme → Run → Diagnostics وتعمل فقط مع بناءات Debug. تفعيل جميع أدوات التعقيم قد يبطئ التشغيل 2-3 مرات، لذا يُنصح بتفعيلها بشكل انتقائي.

استنساخ المخطط لبيئات مختلفة

الممارسة الشائعة هي إنشاء مخططات منفصلة لكل بيئة: Dev وStaging وProduction. يستخدم كل مخطط نفس إعداد البناء (Debug لـ Dev وRelease لـ Production)، لكن بوسائط تشغيل مختلفة: -FIRAnalyticsDebugEnabled و-com.apple.CoreData.SQLDebug 1 لـ Dev وغيابها لـ Production. تُمرَّر وسائط التشغيل إلى UserDefaults (ProcessInfo.processInfo.arguments) وتكون متاحة للقراءة عند بدء التطبيق. هذا يسمح بتبديل عنوان خادم URL ومستوى التسجيل والميزات دون تغيير الكود.

المخططات المشتركة والخاصة: الإدارة عبر Git

المخططات المشتركة تُخزَّن في <project>.xcworkspace/xcshareddata/xcschemes/ أو <project>.xcodeproj/xcshareddata/xcschemes/ وتصل إلى مستودع Git. يرى جميع مطوري الفريق هذه المخططات في Xcode. المخططات المشتركة هي الطريقة الوحيدة لتوزيع المخططات داخل الفريق. إذا أنشأ مطور مخططًا مهمًا (مثل "Staging Archive") لكنه لم يعلّمه كـ Shared، فلن يراه بقية الفريق، مما يؤدي إلى الالتباس: سيُنشئ كل شخص مخططه الخاص بإعداداته الخاصة.

المخططات الخاصة تُخزَّن في xcuserdata/<user>/xcschemes/ ولا تصل إلى Git. وهي مفيدة للإعدادات الشخصية: على سبيل المثال، مخطط مع تفعيل جميع أدوات التعقيم لمطور معين. لا ينبغي أن تحتوي المخططات الخاصة على إعدادات حرجة يعتمد عليها بناء المشروع — إذا غادر المطور المشروع، ستختفي مخططاته الخاصة. توصية: اجعل جميع المخططات المستخدمة في CI/CD والتي يستخدمها مطوران على الأقل Shared.

إدارة المخططات تتم عبر Manage Schemes (Product → Scheme → Manage Schemes). تعرض النافذة جميع مخططات المشروع وحالتها (Shared/Private) وأزرار +/− للإضافة/الحذف. علامة Shared تحوّل رؤية المخطط للفريق. عند تعارض Git (تغييرات في .xcscheme من مطورين)، يجب حل الدمج بحذر — قد تحتوي ملفات XML على معرفات أهداف مختلفة. يُنصح بإضافة .xcscheme إلى الملفات المقفلة أثناء الدمج (git lfs أو .gitattributes).

وسائط التشغيل ومتغيرات البيئة

الوسائط في Scheme هي سلاسل تُمرَّر إلى التطبيق عند التشغيل (ProcessInfo.processInfo.arguments) ومتغيرات البيئة (ProcessInfo.processInfo.environment). تُستخدم الوسائط للأعلام: -AppleLanguages (ru) و-AppleLocale ru_RU لمحاكاة اللغة الروسية، أو -FIRDebugEnabled لتفعيل تصحيح Firebase. تُستخدم متغيرات البيئة للإعداد: API_BASE_URL=http://localhost:3000 وLOG_LEVEL=debug.

لإدارة الميزات (feature flags) في بيئات مختلفة يُستخدم مزيج من الوسائط + إعداد البناء. في مخطط Dev يُحدَّد الوسيط -FeatureFlagNewOnboarding YES، وفي Production — -FeatureFlagNewOnboarding NO (أو الوسيط غير موجود). في الكود يكون الفحص: UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding"). يسمح هذا الأسلوب بتفعيل الميزات تدريجيًا على staging دون تغيير الكود ودون إرسال قيم الإنتاج إلى Git.

مهم: وسائط ومتغيرات بيئة Scheme تتجاوز القيم من Info.plist. إذا كان API_URL محددًا في Info.plist، وفي Scheme — API_URL=http://localhost لإجراء Run، فسيُستخدم عند التشغيل من Xcode القيمة من Scheme. عند التشغيل على جهاز (ليس من Xcode) — القيمة من Info.plist. هذا مريح للتطوير المحلي، لكن يجب تذكر أن متغيرات Scheme لا تدخل في البناء — فهي تعمل فقط عند التشغيل عبر Xcode.

import Foundation

struct AppEnvironment {
    var apiBaseURL: String {
        ProcessInfo.processInfo.environment["API_BASE_URL"]
            ?? Bundle.main.object(forInfoDictionaryKey: "API_BASE_URL") as? String
            ?? "https://api.production.com"
    }

    var isDebugMode: Bool {
        ProcessInfo.processInfo.arguments.contains("-DebugModeEnabled")
    }

    var isNewOnboardingEnabled: Bool {
        UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding")
    }
}

// الاستخدام عند بدء التشغيل
let env = AppEnvironment()
NetworkConfig.shared.configure(baseURL: env.apiBaseURL)

Scheme في CI/CD: الأتمتة عبر xcodebuild

في CI/CD (GitHub Actions وJenkins وGitLab CI) يُستخدم Scheme كوسيط رئيسي لأمر xcodebuild. مثال: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphoneos archive. يحدد العلم -scheme المخطط الذي سيُستخدم. يقرأ xcodebuild جميع الإعدادات من ملف .xcscheme، بما في ذلك إعداد البناء والأهداف وترتيب البناء. هذا يضمن أن CI/CD يبني التطبيق بنفس المعاملات التي تستخدمها بيئة التطوير المحلية.

بالنسبة لـ CI/CD، تعتبر المخططات المشتركة حرجة. إذا لم يكن المخطط Shared، فلن يجده xcodebuild في المستودع، وسيفشل البناء مع خطأ "Scheme not found". القاعدة: قبل إعداد CI/CD، تأكد من أن جميع المخططات المستخدمة محددة كـ Shared. القاعدة الثانية: في CI/CD لا تستخدم المخطط الافتراضي (يختار Xcode تلقائيًا المخطط الأول) — مرر اسم المخطط صراحة دائمًا عبر العلم -scheme.

للبناء المتوازي لعدة مخططات (على سبيل المثال، التطبيق وإضافة watchOS)، يمكن تشغيل xcodebuild بالتسلسل أو بالتوازي. تسمح أنظمة CI الحديثة بتوزيع بناء مخططات مختلفة عبر مصفوفة: وظيفة تبني تطبيق iOS والأخرى تبني إضافة watchOS. هذا يقلل إجمالي وقت البناء من 15 إلى 8 دقائق مع عاملين متوازيين. في النهاية تُدمج المنتجات في ملف .xcarchive واحد باستخدام xcodebuild -exportArchive.

#!/bin/bash — بناء CI/CD مع xcodebuild
# 1. التنظيف والبناء
xcodebuild clean archive \
  -workspace "MyApp.xcworkspace" \
  -scheme "MyApp Production" \
  -configuration Release \
  -sdk iphoneos \
  -archivePath "build/MyApp.xcarchive" \
  CODE_SIGN_STYLE="Manual" \
  PROVISIONING_PROFILE_SPECIFIER="match AppStore"

# 2. التصدير إلى IPA
xcodebuild -exportArchive \
  -archivePath "build/MyApp.xcarchive" \
  -exportPath "build/ipa" \
  -exportOptionsPlist "ExportOptions.plist"