CocoaPods Trunk: چیست، انتشار کتابخانه‌ها از طریق Trunk

CocoaPods Trunk چیست؟

CocoaPods Trunk — زیرساخت سروری است که در سال ۲۰۱۵ برای انتشار متمرکز کتابخانه‌های pod راه‌اندازی شد. قبل از ظهور Trunk، هر pod از طریق مخزن Git توزیع می‌شد: توسعه‌دهنده باید یک مخزن عمومی ایجاد می‌کرد، فایل podspec اضافه می‌نمود و Pull Request به مخزن مرکزی CocoaPods/Specs ارسال می‌کرد. این رویکرد نیاز به نظارت دستی داشت و تأخیرهایی در انتشار به‌روزرسانی‌ها ایجاد می‌کرد.

Trunk این مشکلات را با ارائه API یکپارچه برای انتشار، به‌روزرسانی و حذف podها حل کرد. این سرویس چهار مؤلفه کلیدی دارد:

• احراز هویت — ثبت‌نام با تأیید ایمیل و مدیریت توکن‌های نشست. هر توسعه‌دهنده یک توکن منحصر‌به‌فرد دریافت می‌کند که به حساب و دستگاه‌هایش متصل می‌شود.
• اعتبارسنجی — بررسی خودکار podspec قبل از انتشار، شامل تحلیل نحوی، لینتینگ وابستگی‌ها و بررسی سازگاری پلتفرم‌ها.
• میزبانی — ذخیره متاداده و نسخه‌های pod در سرورهای CocoaPods. کد منبع همچنان در مخزن Git توسعه‌دهنده قرار دارد و Trunk فقط فایل‌های podspec و پیوندها را ذخیره می‌کند.
• مدیریت دسترسی — امکان افزودن و حذف مالکان pod، انتقال حقوق انتشار، علامت‌گذاری podها به عنوان منسوخ.

معماری Trunk بر روی پشته Ruby on Rails با پایگاه داده PostgreSQL ساخته شده است. سرویس از HTTP API با فرمت JSON برای تمام عملیات استفاده می‌کند و کلاینت CLI pod trunk بخشی از توزیع CocoaPods است و همراه با gem اصلی cocoapods نصب می‌شود.

در حال حاضر بیش از ۱۰۰٬۰۰۰ pod از طریق Trunk منتشر شده است و مجموع دانلودها از ۵۰ میلیارد فراتر رفته است. روزانه این سرویس هزاران درخواست انتشار و به‌روزرسانی کتابخانه را از توسعه‌دهندگان سراسر جهان پردازش می‌کند.

ثبت‌نام و احراز هویت

قبل از انتشار pod باید در Trunk ثبت‌نام کنید. فرآیند شامل یک مرحله است — دستور pod trunk register:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro، توسعه iOS'

پس از اجرای دستور، ایمیلی با لینک تأیید به آدرس مشخص‌شده ارسال می‌شود. کلیک روی لینک حساب را فعال کرده و یک توکن نشست ایجاد می‌کند که در زنجیره کلید سیستم (Keychain در macOS، gnome-keyring یا معادل آن در لینوکس) ذخیره می‌شود. توکن به طور خودکار در تمام عملیات‌های بعدی pod trunk استفاده می‌شود.

پارامتر --description اختیاری است اما توصیه می‌شود — هنگام مشاهده نشست‌های فعال از طریق pod trunk me به شناسایی نشست کمک می‌کند. اگر روی چند ماشین کار می‌کنید (ایستگاه کاری، سرور CI)، توضیحات به شما امکان می‌دهد یک نشست را از دیگری تشخیص دهید.

برای بررسی وضعیت احراز هویت از دستور زیر استفاده می‌شود:

pod trunk me

خروجی ایمیل، نام، لیست podهای شما (اگر قبلاً منتشر کرده‌اید) و نشست‌های فعال را نشان می‌دهد. مثال خروجی:

  - Name: Your Name
  - Email: your@email.com
  - Since: 2024-03-15 10:30 UTC
  - Pods:
    - MyLibrary
    - AnotherPod
  - Sessions:
    - 2024-03-15 10:30 UTC - MacBook Pro، توسعه iOS

در سرورهای CI (GitHub Actions، GitLab CI، Jenkins) احراز هویت از طریق توکن ارسال‌شده از طریق متغیر محیطی COCOAPODS_TRUNK_TOKEN انجام می‌شود. توکن را می‌توان با دستور زیر دریافت کرد:

pod trunk me --token-only

این توکن در تنظیمات CI به عنوان متغیر مخفی ذخیره می‌شود و در مرحله انتشار بدون ثبت‌نام مجدد استفاده می‌شود. مثال برای GitHub Actions:

env:
  COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}

مهم: توکن دسترسی کامل به مدیریت podهای متصل به حساب می‌دهد. هرگز آن را در مخازن عمومی منتشر نکنید و به اشخاص ثالث ندهید. در صورت به خطر افتادن، توکن را می‌توان از طریق pod trunk remove-session باطل کرد یا تمام نشست‌ها را از طریق پنل مدیریت در وب‌سایت CocoaPods حذف نمود.

آماده‌سازی podspec

فایل podspec (.podspec یا .podspec.json) — مانیفست کتابخانه‌ای است که شامل متاداده، وابستگی‌ها، اطلاعات پلتفرم‌ها و کد منبع می‌باشد. Trunk از این فایل برای اعتبارسنجی و ثبت pod استفاده می‌کند. حداقل podspec برای انتشار به این شکل است:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'توضیح مختصر کتابخانه'
  s.description  = 'توضیح کامل با شرح قابلیت‌ها'
  s.homepage     = 'https://github.com/username/MyLibrary'
  s.license      = { :type => 'MIT', :file => 'LICENSE' }
  s.author       = { 'Your Name' => 'your@email.com' }
  s.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => s.version.to_s }
  s.source_files = 'Sources/**/*.{swift,h,m}'
  s.platform     = :ios, '12.0'
  s.swift_version = '5.7'
end

فیلدهای کلیدی podspec:

• name — نام pod، باید در رجیستری Trunk منحصربه‌فرد باشد. نام‌ها بر اساس اصل «اولین نفر مالک است» ثبت می‌شوند — اگر نام گرفته شده باشد، انتشار رد می‌شود.
• version — نسخه معنایی در قالب MAJOR.MINOR.PATCH. Trunk انتشار مجدد همان نسخه را نمی‌پذیرد — باید شماره را افزایش دهید.
• source — لینک به مخزن Git و تگ. Trunk کد منبع را ذخیره نمی‌کند، بنابراین مخزن باید برای کلون کردن در دسترس باشد.
• platform — پلتفرم هدف (iOS، macOS، tvOS، watchOS) و حداقل نسخه SDK.
• license — نوع مجوز. توصیه می‌شود MIT، Apache-2.0، BSD یا سایر مجوزهای متن‌باز را مشخص کنید.

قبل از انتشار باید podspec را با استفاده از لینتر بررسی کنید:

pod lib lint MyLibrary.podspec

لینتر نحو، وجود فیلدهای اجباری، صحت مسیرهای فایل و قابلیت حل وابستگی‌ها را بررسی می‌کند. اگر در فرآیند لینتینگ از منابع خصوصی (private specs) استفاده می‌شود، پرچم --sources اضافه می‌شود. برای رد کردن بارگذاری شبکه (فقط بررسی محلی) از پرچم --local-only استفاده می‌شود.

انتشار از طریق pod trunk push

دستور اصلی برای انتشار pod — pod trunk push. این دستور فایل podspec را به سرور Trunk ارسال می‌کند، جایی که اعتبارسنجی کامل انجام می‌شود و در رجیستری عمومی ثبت می‌گردد. نحو:

pod trunk push MyLibrary.podspec

پرچم --allow-warnings انتشار در صورت وجود هشدارها را مجاز می‌کند. به طور پیش‌فرض، هرگونه هشدار (warning) انتشار را مسدود می‌کند. اگر کتابخانه هشدارهای شناخته‌شده‌ای دارد که بر عملکرد تأثیر نمی‌گذارند، می‌توانید از این پرچم استفاده کنید. مهم: خطاها (errors) بدون توجه به پرچم‌ها همیشه انتشار را مسدود می‌کنند.

پرچم --synchronous درخواست را همزمان می‌کند — ترمینال منتظر پایان اعتبارسنجی در سرور می‌ماند. به طور پیش‌فرض، دستور بلافاصله پس از ارسال کنترل را برمی‌گرداند و سرور انتشار را به صورت ناهمزمان پردازش می‌کند. حالت همزمان در CI/CD مفید است، زمانی که گام بعدی pipeline به موفقیت انتشار وابسته است.

پرچم --skip-import-validation بررسی import کتابخانه در پروژه آزمایشی را رد می‌کند. این کار انتشار را سریع‌تر می‌کند اما تضمین نمی‌کند که کتابخانه واقعاً کامپایل می‌شود. فقط در صورتی از این پرچم استفاده کنید که از صحت build مطمئن هستید.

مثال انتشار با گزینه‌های معمول:

pod trunk push MyLibrary.podspec \
  --allow-warnings \
  --synchronous \
  --skip-import-validation

پس از انتشار موفق، Trunk یک JSON با جزئیات برمی‌گرداند:

  Congrats

  MyLibrary (0.1.0) successfully published

  Pod URL: https://cocoapods.org/pods/MyLibrary

کتابخانه برای نصب از طریق Podfile هر پروژه iOS یا macOS در دسترس قرار می‌گیرد. معمولاً داده‌های موجود در ایندکس جستجوی CocoaPods ظرف چند دقیقه به‌روز می‌شوند، اما در موارد نادر ایندکس‌گذاری ممکن است تا یک ساعت طول بکشد.

محدودیت مهم: نسخه منتشر شده pod قابل حذف نیست. این کار برای جلوگیری از خرابی در پروژه‌هایی که از این نسخه استفاده می‌کنند انجام شده است. اگر انتشار با خطا انجام شد، می‌توانید نسخه بعدی را با اصلاحیه منتشر کنید، اما بازگشت غیرممکن است. استثنا — pod trunk delete که فقط برای کارکنان CocoaPods در دسترس است و در موارد نادر (نقض مجوز، کد مخرب) اعمال می‌شود.

مدیریت انتشارها و دسترسی

CocoaPods Trunk چندین دستور برای مدیریت podهای منتشر شده ارائه می‌دهد:

افزودن مالکان

برای انتقال حقوق انتشار pod به توسعه‌دهنده دیگر از دستور زیر استفاده می‌شود:

pod trunk add-owner MyLibrary developer@email.com

پس از اجرا، مالک جدید دسترسی کامل به مدیریت pod دریافت می‌کند: انتشار نسخه‌های جدید، افزودن و حذف سایر مالکان، علامت‌گذاری pod به عنوان منسوخ. مالک می‌تواند هر کاربر ثبت‌نام‌شده Trunk باشد — ثبت‌نام قبلی الزامی است.

حذف مالکان

اگر توسعه‌دهنده پروژه را ترک کرده یا دیگر نباید به pod دسترسی داشته باشد:

pod trunk remove-owner MyLibrary developer@email.com

فقط مالک فعلی می‌تواند یک مالک را حذف کند. نمی‌توان آخرین مالک pod را حذف کرد — ابتدا باید یک مالک جدید اضافه کنید. این کار از بی‌صاحب ماندن pod جلوگیری می‌کند.

علامت‌گذاری pod به عنوان منسوخ

اگر کتابخانه دیگر پشتیبانی نمی‌شود، می‌توان آن را به عنوان منسوخ (deprecated) علامت‌گذاری کرد. این کار pod را از رجیستری حذف نمی‌کند، اما هنگام نصب به کاربران هشدار می‌دهد:

pod trunk deprecate MyLibrary

به صورت اختیاری می‌توان pod جایگزین را مشخص کرد:

pod trunk deprecate MyLibrary --in-favor-of=NewLibrary

هنگام نصب pod منسوخ، CocoaPods یک هشدار در ترمینال نمایش می‌دهد و توصیه می‌کند به جایگزین مشخص‌شده مهاجرت کنید. این روش صحیحی برای پایان دادن به پشتیبانی کتابخانه بدون خراب کردن build پروژه‌های موجود است.

مشاهده اطلاعات pod

اطلاعات pod از طریق دستور pod trunk info در دسترس است:

pod trunk info MyLibrary

دستور تمام نسخه‌های pod، تاریخ انتشار، لیست مالکان و وضعیت (فعال/منسوخ) را نشان می‌دهد. برای مشاهده جزئیات یک نسخه خاص از pod spec cat MyLibrary 0.1.0 استفاده می‌شود.

خطاها و رفع آنها

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

خطای احراز هویت

علامت: [!] Authentication failed. You need to register a session first.
علت: توکن نشست وجود ندارد یا منقضی شده است. توکن‌ها مدت اعتبار محدودی دارند (پیش‌فرض ۳۰ روز بدون فعالیت).
رفع: دوباره pod trunk register your@email.com 'Your Name' را اجرا کنید. اگر از CI استفاده می‌کنید، صحت متغیر COCOAPODS_TRUNK_TOKEN را بررسی کنید و در صورت نیاز توکن جدیدی تولید کنید.

تضاد نسخه

علامت: [!] You have already pushed version 0.1.0 for MyLibrary.
علت: تلاش برای انتشار مجدد نسخه موجود. Trunk اجازه بازنویسی نسخه‌ها را نمی‌دهد.
رفع: نسخه را در podspec مطابق با نسخه‌بندی معنایی افزایش دهید. اگر در podspec اشتباه کرده‌اید، نسخه بعدی را با اصلاحیه منتشر کنید.

خطای اعتبارسنجی podspec

علامت: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
علت: مسیر فایل‌های منبع در فیلد source_files به اشتباه مشخص شده است.
رفع: مسیرها را در podspec بررسی کنید، pod lib lint را تا رفع تمام خطاها به صورت محلی اجرا کنید، سپس انتشار را تکرار کنید. از الگوهای glob استفاده کنید: Classes/**/*.{h,m}، Sources/MyLibrary/**/*.swift.

وقفه اتصال

علامت: [!] Connection to trunk.cocoapods.org failed. Timeout.
علت: مشکلات شبکه یا عدم دسترسی موقت سرور Trunk.
رفع: دسترسی سرور را بررسی کنید: curl -I https://trunk.cocoapods.org. اگر سرور پاسخ می‌دهد، دستور را چند دقیقه بعد تکرار کنید. ممکن است IP شما مسدود شده باشد — از اتصال دیگر یا از طریق VPN تلاش کنید.

عدم دسترسی به pod

علامت: [!] You do not have permission to push to MyLibrary.
علت: شما مالک pod نیستید. این اتفاق می‌افتد اگر کسی قبلاً pod را با این نام ثبت کرده باشد.
رفع: با مالک فعلی pod تماس بگیرید (می‌توانید از طریق pod trunk info MyLibrary پیدا کنید) و بخواهید شما را از طریق pod trunk add-owner اضافه کند. اگر نام pod گرفته شده است، یک نام جایگزین در نظر بگیرید.