النقل من Xcode إلى Bazel

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

أوجه الاختلاف بين Xcode وBazeel

• يتطلّب Bazel أن تحدّد صراحةً كل هدف لإصداره وحسب تبعيته، بالإضافة إلى إعدادات الإصدار المقابلة له من خلال قواعد الإصدار.

• يتطلّب Bazel توفّر جميع الملفات التي يعتمد عليها المشروع داخل دليل مساحة العمل أو المحدّدة كعمليات استيراد في ملف WORKSPACE.

• عند إنشاء مشاريع Xcode باستخدام Bazel، تصبح ملفات BUILD مصدرًا للحقيقة. إذا كنت تعمل على المشروع في Xcode، يجب إنشاء إصدار جديد من مشروع Xcode يتطابق مع ملفات BUILD باستخدام Tulsi عند تحديث BUILD. إذا كنت لا تستخدم Xcode، فإن الأمرَين bazel build وbazel test يوفران إمكانات إنشاء واختبار مع قيود معينة موضحة لاحقًا في هذا الدليل.

• ونظرًا للاختلافات في مخططات تهيئة الإصدار، مثل تنسيقات الدليل أو علامات الإصدار، قد لا يدرك Xcode تمامًا "الصورة الكبيرة" الخاصة بالإصدار وبالتالي قد لا تعمل بعض ميزات Xcode. وهي:

  • استنادًا إلى الأهداف التي تختارها للإحالة الناجحة في Tulsi، قد لا يتمكّن Xcode من فهرسة مصدر المشروع بشكلٍ صحيح. يؤثر هذا في اكتمال الرمز والتنقل في Xcode، نظرًا لأن Xcode لن يتمكن من مشاهدة جميع رموز المصدر الخاصة بالمشروع.

  • قد لا يعمل التحليل الثابت ومعقّمات العناوين ومعقمات سلاسل المحادثات لأن Bazel لا ينتج المخرجات التي يتوقّعها Xcode لهذه الميزات.

  • إذا أنشأت مشروع Xcode باستخدام Tulsi واستخدمت هذا المشروع لإجراء اختبارات من داخل Xcode، ستشغّل Xcode الاختبارات بدلاً من Bazel. لإجراء الاختبارات باستخدام Bazel، شغِّل الأمر bazel test يدويًا.

قبل البدء

قبل البدء، عليك إجراء ما يلي:

1. ثبِّت Bazel إذا لم يسبق لك تثبيتها.

2. إذا لم تكن على دراية ببازل ومفاهيمها، أكمِل البرنامج التعليمي لتطبيقات iOS. عليك التعرّف على مساحة عمل Bazel، بما في ذلك ملفات WORKSPACE وBUILD، بالإضافة إلى مفاهيم الأهداف وإنشاء القواعد وحزم Bazel.

3. يمكنك تحليل وتحليل تبعيات المشروع.

تحليل تبعيات المشروع

على عكس Xcode، يتطلب منك Bazel الإعلان بوضوح عن جميع التبعيات لكل هدف في ملف BUILD.

لمزيد من المعلومات حول التبعيات الخارجية، يُرجى الاطّلاع على العمل مع التبعيات الخارجية.

إنشاء مشروع Xcode أو اختباره مع Bazel

لإنشاء مشروع Xcode من خلال Bazel أو اختباره، يمكنك إجراء ما يلي:

1. إنشاء ملف WORKSPACE

2. (تجريبي) دمج تبعيات CocoaPods

3. إنشاء ملف BUILD:

   أ- إضافة هدف التطبيق

   ب- (اختياري) إضافة أهداف الاختبار

   ج- إضافة أهداف المكتبة

4. (اختياري) تحطيم الدقة

5. تشغيل الإصدار

6. إنشاء مشروع Xcode باستخدام Tulsi

الخطوة 1: إنشاء الملف WORKSPACE

يمكنك إنشاء ملف WORKSPACE في دليل جديد. يصبح هذا الدليل جذر بازيل العمل. إذا كان المشروع لا يعتمد على الارتباطات التابعة، يمكن أن يكون هذا الملف فارغًا. إذا كان المشروع يعتمد على ملفات أو حِزم ليست في أحد أدلة المشروع، يمكنك تحديد العناصر التابعة الخارجية في ملف WORKSPACE.

الخطوة 2: (التجريبية) دمج تبعيات CocoaPods

لدمج تبعيات CocoaPods في مساحة عمل Bazel، عليك تحويلها إلى حِزم Bazel على النحو الموضّح في تحويل تبعيات CocoaPods.

الخطوة 3: إنشاء ملف BUILD

بعد تحديد مساحة العمل والتبعيات الخارجية، عليك إنشاء ملف BUILD يخبر "بازيل" بكيفية تنظيم المشروع. أنشِئ الملف BUILD في جذر مساحة عمل Bazel واضبطه لإنشاء إصدار أولي من المشروع على النحو التالي:

• الخطوة 3 (أ): إضافة هدف التطبيق
• الخطوة 3 (ب): (اختياري) إضافة أهداف الاختبار
• الخطوة 3(ج): إضافة أهداف المكتبة

ملاحظة: لمعرفة المزيد عن الحزم ومفاهيم Bazel الأخرى، يُرجى الاطّلاع على مساحات العمل والطرود والاستهدافات.

الخطوة 3 (أ): إضافة هدف التطبيق

أضِف استهداف قاعدة macos_application أو ios_application. يعمل هذا الهدف على إنشاء حِزمة تطبيق macOS أو iOS، على التوالي. في الهدف، حدّد ما يلي على الأقل:

• bundle_id - معرّف الحزمة (مسار نظام أسماء النطاقات العكسي متبوعًا باسم التطبيق) من البرنامج الثنائي.

• provisioning_profile - إدارة الملف الشخصي من حسابك على مطوّر برامج Apple (في حال إنشاء حساب على جهاز يعمل بنظام التشغيل iOS)

• families (iOS فقط) - سواء كنت تريد إنشاء التطبيق لأجهزة iPhone أو iPad أو كلتيهما.

• infoplists - قائمة بملفات .plist للدمج في ملف Info.plist النهائي.

• minimum_os_version: الحد الأدنى من إصدار نظام التشغيل macOS أو iOS الذي يتوافق معه التطبيق ويضمن هذا الإجراء إنشاء Bazel للتطبيق باستخدام مستويات واجهات برمجة التطبيقات الصحيحة.

الخطوة 3-ب: (اختياري) إضافة أهداف الاختبار

يتوافق تطبيق Bazel مع قواعد Apple لإجراء اختبارات الوحدات المستندة إلى المكتبة على نظامَي التشغيل iOS وmacOS، بالإضافة إلى اختبارات التطبيقات على نظام التشغيل macOS. في ما يتعلق بالاختبارات المستندة إلى التطبيقات على اختبارات iOS أو واجهة المستخدم على أي من المنصتَين، سينشئ Bazel مخرجات الاختبار، ولكن يجب إجراء الاختبارات في Xcode من خلال مشروع تم إنشاؤه باستخدام Tulsi. أضِف أهداف الاختبار على النحو التالي:

• macos_unit_test لتشغيل اختبارات الوحدات المستندة إلى المكتبة والتطبيقات على نظام التشغيل macOS.

• ios_unit_test لتنفيذ اختبارات الوحدات المستندة إلى المكتبة على نظام التشغيل iOS. بالنسبة إلى الاختبارات التي تتطلب محاكي iOS، سينشئ Bazel نتائج الاختبار ولكنه لا يشغّل الاختبارات. عليك إنشاء مشروع Xcode مع Tulsi وإجراء الاختبارات من خلال Xcode.

• ios_ui_test لإنشاء النتائج المطلوبة لإجراء اختبارات واجهة المستخدم في محاكي iOS باستخدام Xcode. عليك إنشاء مشروع Xcode مع Tulsi وإجراء الاختبارات من خلال Xcode. يتعذّر على Bazel إجراء اختبارات واجهة المستخدم في الأصل.

حدِّد قيمة للسمة minimum_os_version على الأقلّ. على الرغم من أن سمات الحزمة الأخرى، مثل bundle_identifier وinfoplists، مضبوطة بشكل تلقائي على القيم الأكثر استخدامًا، تأكّد من توافقها مع المشروع وضبطها عند الضرورة. بالنسبة إلى الاختبارات التي تتطلب محاكي iOS، حدِّد أيضًا اسم ios_application المستهدف كقيمة للسمة test_host.

الخطوة 3(ج): إضافة أهداف المكتبة

أضِف استهداف objc_library لكل مكتبة "هدف ج" وهدف swift_library لكل مكتبة Swift التي التطبيق و/أو تعتمد على الفحوصات.

أضِف أهداف المكتبة على النحو التالي:

• أضِف أهداف مكتبة التطبيقات كمعتمدة على استهدافات التطبيق.

• أضِف أهداف مكتبة الاختبار اعتمادًا على أهداف الاختبار.

• أدرِج مصادر التنفيذ في السمة srcs.

• أدرِج العناوين في السمة hdrs.

وللحصول على مزيد من المعلومات حول قواعد الإصدار، يمكنك الاطّلاع على قواعد Apple لتطبيق Bazel.

في هذه المرحلة، من المفيد اختبار الإصدار:

bazel build //:<application_target>

الخطوة 4: (اختياري) تجزئة المحتوى

إذا كان المشروع كبيرًا أو ينمو، يمكنك تقسيمه إلى حِزم متعددة في Bazel. وتوفّر هذه الدقة العالية ما يلي:

• زيادة في الإصدارات،

• زيادة موازاة مهام الإصدار

• صيانة أفضل للمستخدمين في المستقبل،

• تحكّم أفضل في مستوى رؤية رمز المصدر على مستوى الأهداف والحزم. ويمنع ذلك مشاكل مثل المكتبات التي تحتوي على تفاصيل التنفيذ التي تُسرَب إلى واجهات برمجة التطبيقات العامة.

ملاحظات لتحسين المشروع:

• ضع كل مكتبة في حزمة بازيل الخاصة بها. ابدأ بتلك التي تتطلب تبعيات أقلها وتمتاز طريقك في الاعتمادية.

• أثناء إضافة BUILD ملف وتحديد أهداف، أضف هذه الاستهدافات الجديدة إلى سمات deps للأهداف التي تعتمد عليها.

• لا تتجاوز الدالة glob() حدود الحِزم، لذلك سيتم تصغير عدد الحِزم التي تمت مطابقتها مع glob().

• عند إضافة ملف BUILD إلى دليل main، يمكنك أيضًا إضافة ملف BUILD إلى الدليل test المقابل.

• فرض حدود سليمة لمستوى الرؤية في الحزم

• أنشِئ المشروع بعد كل تغيير رئيسي في ملفات BUILD وأصلح الأخطاء البرمجية أثناء مصادفتها.

الخطوة 5: تشغيل الإصدار

شغِّل الإصدار الذي تم نقله بالكامل لضمان اكتماله بدون أخطاء أو تحذيرات. شغِّل كل تطبيق واختبر هدفًا بشكل فردي للعثور بسهولة على مصادر أي أخطاء تحدث.

مثال:

bazel build //:my-target

الخطوة 6: إنشاء مشروع Xcode باستخدام Tulsi

عند إنشاء الملفات باستخدام بازيل، يصبح الملفان WORKSPACE وBUILD مصدرًا للحقيقة حول الإصدار. ولتوعية Xcode بذلك، يجب إنشاء مشروع Xcode متوافق مع Bazel باستخدام تطبيق Tulsi.

تحديد المشاكل وحلّها

يمكن أن تظهر أخطاء Bazel عند انتهاء المزامنة مع إصدار Xcode المحدد، مثل عند تطبيق تحديث. إليك بعض الأمور التي يمكنك تجربتها إذا كنت تواجه أخطاء في Xcode، على سبيل المثال "يجب تحديد إصدار Xcode لاستخدام Apple CROSSTool".

• شغِّل Xcode يدويًا واقبل أي بنود وشروط.

• استخدِم الرمز Xcode للإشارة إلى الإصدار الصحيح وقبول الترخيص ومحو حالة Bazel.

  sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
  sudo xcodebuild -license
  bazel sync --configure

• إذا لم تنجح هذه الطريقة، يمكنك أيضًا محاولة تشغيل bazel clean --expunge.