مهاجرت از Xcode به Bazel

در این صفحه نحوه ساخت یا آزمایش یک پروژه Xcode با Bazel توضیح داده شده است. تفاوت های Xcode و Bazel را شرح می دهد و مراحل تبدیل پروژه Xcode به پروژه Bazel را ارائه می دهد. همچنین راه حل های عیب یابی برای رفع خطاهای رایج ارائه می دهد.

تفاوت بین Xcode و Bazel

• Bazel از شما می‌خواهد که هر هدف ساخت و وابستگی‌های آن را به‌علاوه تنظیمات ساخت مربوطه را از طریق قوانین ساخت مشخص کنید.

• Bazel نیاز دارد که تمام فایل‌هایی که پروژه به آن‌ها وابسته است، در دایرکتوری فضای کاری وجود داشته باشند یا به‌عنوان واردات در فایل WORKSPACE مشخص شده باشند.

• هنگام ساختن پروژه های Xcode با Bazel، فایل(های) BUILD منبع حقیقت می شود. اگر روی پروژه در Xcode کار می‌کنید، باید هر زمان که فایل‌های BUILD را به‌روزرسانی می‌کنید، نسخه جدیدی از پروژه Xcode را که با فایل‌های BUILD مطابقت دارد، با استفاده از Tulsi ایجاد کنید. اگر از Xcode استفاده نمی‌کنید، فرمان‌های bazel build bazel و bazel test قابلیت‌های ساخت و آزمایش را با محدودیت‌های خاصی که در ادامه در این راهنما توضیح داده شده است، ارائه می‌کنند.

• به دلیل تفاوت در طرح‌واره‌های پیکربندی ساخت، مانند طرح‌بندی دایرکتوری یا پرچم‌های ساخت، Xcode ممکن است کاملاً از "تصویر بزرگ" ساخت آگاه نباشد و بنابراین برخی از ویژگی‌های Xcode ممکن است کار نکنند. برای مثال:

  • بسته به اهدافی که برای تبدیل در Tulsi انتخاب می کنید، Xcode ممکن است نتواند منبع پروژه را به درستی ایندکس کند. این روی تکمیل کد و پیمایش در Xcode تأثیر می‌گذارد، زیرا Xcode نمی‌تواند همه کد منبع پروژه را ببیند.

  • تجزیه و تحلیل استاتیک، ضد عفونی کننده آدرس، و ضدعفونی کننده نخ ممکن است کار نکنند، زیرا Bazel خروجی هایی را که Xcode برای آن ویژگی ها انتظار دارد تولید نمی کند.

  • اگر یک پروژه Xcode با Tulsi ایجاد کنید و از آن پروژه برای اجرای آزمایش‌ها از داخل Xcode استفاده کنید، Xcode آزمایش‌ها را به جای Bazel اجرا می‌کند. برای اجرای تست ها با Bazel، دستور bazel test را به صورت دستی اجرا کنید.

قبل از اینکه شروع کنی

قبل از شروع، موارد زیر را انجام دهید:

1. اگر قبلاً این کار را نکرده اید، Bazel را نصب کنید .

2. اگر با Bazel و مفاهیم آن آشنایی ندارید، آموزش اپلیکیشن iOS را کامل کنید. شما باید فضای کاری Bazel، از جمله فایل های WORKSPACE و BUILD ، و همچنین مفاهیم اهداف، قوانین ساخت و بسته های Bazel را درک کنید.

3. تجزیه و تحلیل و درک وابستگی های پروژه.

تجزیه و تحلیل وابستگی های پروژه

برخلاف Xcode، Bazel از شما می‌خواهد که تمام وابستگی‌ها را برای هر هدف در فایل BUILD به صراحت اعلام کنید.

برای اطلاعات بیشتر در مورد وابستگی های خارجی، به کار با وابستگی های خارجی مراجعه کنید.

با Bazel یک پروژه Xcode بسازید یا آزمایش کنید

برای ساخت یا آزمایش یک پروژه Xcode با Bazel، موارد زیر را انجام دهید:

1. فایل WORKSPACE را ایجاد کنید

2. (تجربی) وابستگی های CocoaPods را ادغام کنید

3. یک فایل BUILD ایجاد کنید:

   آ. هدف برنامه را اضافه کنید

   ب (اختیاری) هدف(های) آزمایشی را اضافه کنید

   ج افزودن هدف(های) کتابخانه

4. (اختیاری) ساختار را دانه بندی کنید

5. ساخت را اجرا کنید

6. پروژه Xcode را با Tulsi ایجاد کنید

مرحله 1: فایل WORKSPACE را ایجاد کنید

یک فایل WORKSPACE در یک فهرست جدید ایجاد کنید. این فهرست به ریشه فضای کاری Bazel تبدیل می شود. اگر پروژه از هیچ وابستگی خارجی استفاده نمی کند، این فایل می تواند خالی باشد. اگر پروژه به فایل ها یا بسته هایی بستگی دارد که در یکی از دایرکتوری های پروژه نیستند، این وابستگی های خارجی را در فایل WORKSPACE مشخص کنید.

مرحله 2: (تجربی) وابستگی های CocoaPods را ادغام کنید

برای ادغام وابستگی های CocoaPods در فضای کاری Bazel، باید آنها را به بسته های Bazel تبدیل کنید همانطور که در تبدیل وابستگی های CocoaPods توضیح داده شده است.

مرحله 3: یک فایل BUILD ایجاد کنید

هنگامی که فضای کاری و وابستگی های خارجی را تعریف کردید، باید یک فایل BUILD ایجاد کنید که به Bazel بگوید ساختار پروژه چگونه است. فایل BUILD را در ریشه فضای کاری Bazel ایجاد کنید و آن را برای انجام ساخت اولیه پروژه به صورت زیر پیکربندی کنید:

• مرحله 3a: هدف برنامه را اضافه کنید
• مرحله 3b: (اختیاری) هدف(های) آزمایشی را اضافه کنید
• مرحله 3c: هدف(های) کتابخانه را اضافه کنید

نکته: برای کسب اطلاعات بیشتر در مورد بسته ها و سایر مفاهیم Bazel، به فضاهای کاری، بسته ها و اهداف مراجعه کنید.

مرحله 3a: هدف برنامه را اضافه کنید

یک macos_application یا یک هدف قانون ios_application اضافه کنید. این هدف به ترتیب یک بسته نرم افزاری macOS یا iOS ایجاد می کند. در هدف، حداقل موارد زیر را مشخص کنید:

• bundle_id - شناسه بسته (مسیر DNS معکوس به دنبال نام برنامه) باینری.

• provisioning_profile - تهیه نمایه از حساب توسعه دهنده Apple شما (اگر برای یک دستگاه دستگاه iOS ساخته می شود).

• families (فقط iOS) - آیا برای ساخت برنامه برای iPhone، iPad یا هر دو.

• infoplists - لیستی از فایل های .plist برای ادغام در فایل Info.plist نهایی.

• minimum_os_version - حداقل نسخه macOS یا iOS که برنامه از آن پشتیبانی می کند. این تضمین می کند که Bazel برنامه را با سطوح API صحیح می سازد.

مرحله 3b: (اختیاری) هدف(های) آزمایشی را اضافه کنید

قوانین ساخت اپل Bazel از اجرای آزمایش‌های واحد مبتنی بر کتابخانه در 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 نمی تواند به صورت بومی تست های UI را اجرا کند.

در حداقل، مقداری را برای ویژگی minimum_os_version مشخص کنید. در حالی که سایر ویژگی‌های بسته‌بندی، مانند bundle_identifier و infoplists ، به‌طور پیش‌فرض روی مقادیر متداول استفاده می‌شوند، اطمینان حاصل کنید که این پیش‌فرض‌ها با پروژه سازگار هستند و در صورت لزوم آنها را تنظیم کنید. برای تست هایی که به شبیه ساز iOS نیاز دارند، نام هدف ios_application را نیز به عنوان مقدار مشخصه test_host مشخص کنید.

مرحله 3c: هدف(های) کتابخانه را اضافه کنید

یک هدف objc_library برای هر کتابخانه Objective C و یک هدف swift_library برای هر کتابخانه Swift که برنامه و/یا آزمایش‌ها به آن بستگی دارد، اضافه کنید.

اهداف کتابخانه را به صورت زیر اضافه کنید:

• اهداف کتابخانه برنامه را به عنوان وابستگی به اهداف برنامه اضافه کنید.

• اهداف کتابخانه آزمایشی را به عنوان وابستگی به اهداف آزمایشی اضافه کنید.

• منابع پیاده سازی را در ویژگی srcs کنید.

• هدرها را در ویژگی hdrs فهرست کنید.

برای اطلاعات بیشتر در مورد قوانین ساخت، به قوانین اپل برای Bazel مراجعه کنید.

در این مرحله، ایده خوبی است که ساخت را آزمایش کنید:

bazel build //:<application_target>

مرحله 4: (اختیاری) ساخت را دانه بندی کنید

اگر پروژه بزرگ است، یا در حین رشد، آن را به چند بسته Bazel تقسیم کنید. این افزایش دانه بندی فراهم می کند:

• افزایش فزاینده سازه ها،

• افزایش موازی سازی وظایف ساخت،

• قابلیت نگهداری بهتر برای کاربران آینده،

• کنترل بهتر روی قابلیت مشاهده کد منبع در بین اهداف و بسته ها. این از نشت مسائلی مانند کتابخانه های حاوی جزئیات پیاده سازی به API های عمومی جلوگیری می کند.

نکاتی برای دانه بندی پروژه:

• هر کتابخانه را در بسته Bazel خودش قرار دهید. با کسانی که به کمترین وابستگی نیاز دارند شروع کنید و به سمت درخت وابستگی بروید.

• همانطور که فایل‌های BUILD را اضافه می‌کنید و اهداف را مشخص می‌کنید، این اهداف جدید را به ویژگی‌های deps اهدافی که به آنها بستگی دارد اضافه کنید.

• تابع glob() از مرزهای بسته عبور نمی کند، بنابراین با افزایش تعداد بسته ها، فایل های مطابق با glob() کوچک می شوند.

• هنگام افزودن یک فایل BUILD به دایرکتوری main ، یک فایل BUILD را نیز به دایرکتوری test مربوطه اضافه کنید.

• محدودیت های دید سالم را در سراسر بسته ها اعمال کنید.

• پروژه را بعد از هر تغییر عمده در فایل های BUILD بسازید و در صورت مواجه شدن با آنها خطاهای ساخت را برطرف کنید.

مرحله 5: ساخت را اجرا کنید

بیلد کاملاً منتقل شده را اجرا کنید تا مطمئن شوید که بدون خطا یا اخطار کامل می شود. هر برنامه کاربردی و هدف آزمایشی را به صورت جداگانه اجرا کنید تا منابع خطاهای رخ داده را راحت تر پیدا کنید.

مثلا:

bazel build //:my-target

مرحله 6: پروژه Xcode را با Tulsi ایجاد کنید

هنگام ساخت با Bazel، فایل های 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 را نیز اجرا کنید.