CocoaPods Trunk: bu nima, kutubxonalarni Trunk orqali nashr qilish

CocoaPods Trunk nima?

CocoaPods Trunk — 2015-yilda pod kutubxonalarini markazlashtirilgan nashr qilish uchun ishga tushirilgan server infratuzilmasidir. Trunk paydo bo'lishidan oldin har bir pod Git repozitoriyasi orqali tarqatilardi: dasturchi umumiy repozitoriya yaratishi, podspec fayl qo'shishi va markaziy CocoaPods/Specs repozitoriyasiga Pull Request yuborishi kerak edi. Bunday yondashuv qo'lda moderatsiyani talab qilar va yangilanishlarni nashr qilishda kechikishlar yaratardi.

Trunk bu muammolarni podlarni nashr qilish, yangilash va o'chirish uchun yagona API taqdim etib hal qildi. Xizmat to'rtta asosiy komponentni o'z ichiga oladi:

• Autentifikatsiya — email tasdiqlash bilan ro'yxatdan o'tish va sessiya tokenlarini boshqarish. Har bir dasturchi o'z hisobi va qurilmalariga bog'langan noyob token oladi.
• Validatsiya — nashrdan oldin podspecni avtomatik tekshirish, jumladan sintaktik tahlil, bog'liqliklarni linting va platforma mosligini tekshirish.
• Xosting — podlarning metama'lumotlari va versiyalarini CocoaPods serverlarida saqlash. Manba kodi hali ham dasturchining Git repozitoriyasida joylashgan, Trunk esa faqat podspec fayllar va havolalarni saqlaydi.
• Kirishni boshqarish — pod egalarini qo'shish va o'chirish, nashr qilish huquqlarini uzatish, podlarni eskirgan deb belgilash imkoniyati.

Trunk arxitekturasi PostgreSQL ma'lumotlar bazasi bilan Ruby on Rails stacki asosida qurilgan. Xizmat barcha operatsiyalar uchun JSON formatli HTTP API dan foydalanadi, pod trunk CLI klienti esa CocoaPods distributsiyasining bir qismidir va asosiy cocoapods gemi bilan birga o'rnatiladi.

Hozirgi kunda Trunk orqali 100 000 dan ortiq pod nashr qilingan, umumiy yuklab olishlar soni 50 milliarddan oshgan. Xizmat har kuni dunyoning turli burchaklaridagi dasturchilardan minglab nashr va yangilash so'rovlarini qayta ishlaydi.

Ro'yxatdan o'tish va autentifikatsiya

Pod nashr qilishdan oldin Trunkda ro'yxatdan o'tish kerak. Jarayon bir qadamdan iborat — pod trunk register buyrug'i:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, iOS dasturlash'

Buyruq bajarilgandan so'ng ko'rsatilgan emailga tasdiqlash havolasi bilan xat keladi. Havolaga o'tish hisobni faollashtiradi va tizim kalitlar zanjirida (macOS da Keychain, Linux da gnome-keyring yoki ekvivalent) saqlanadigan sessiya tokenini yaratadi. Token barcha keyingi pod trunk operatsiyalarida avtomatik ishlatiladi.

--description parametri ixtiyoriy, ammo tavsiya etiladi — pod trunk me orqali faol sessiyalarni ko'rishda sessiyani aniqlashga yordam beradi. Agar bir nechta mashinada ishlasangiz (ish stansiyasi, CI server), tavsif bir sessiyani boshqasidan farqlash imkonini beradi.

Autentifikatsiya holatini tekshirish uchun quyidagi buyruq ishlatiladi:

pod trunk me

Natija email, ism, podlaringiz ro'yxati (agar allaqachon nashr qilgan bo'lsangiz) va faol sessiyalarni ko'rsatadi. Namuna natija:

  - 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 ishlab chiqish

CI serverlarida (GitHub Actions, GitLab CI, Jenkins) autentifikatsiya COCOAPODS_TRUNK_TOKEN muhit o'zgaruvchisi orqali uzatiladigan token orqali amalga oshiriladi. Tokenni quyidagi buyruq bilan olish mumkin:

pod trunk me --token-only

Bu token CI sozlamalarida maxfiy o'zgaruvchi sifatida saqlanadi va nashr bosqichida qayta ro'yxatdan o'tmasdan ishlatiladi. GitHub Actions uchun namuna:

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

Muhim: token hisobga bog'langan podlarni boshqarishga to'liq kirish imkonini beradi. Uni hech qachon jamoat repozitoriyalarida nashr qilmang va uchinchi shaxslarga bermang. Token buzilgan taqdirda, uni pod trunk remove-session orqali bekor qilish yoki CocoaPods veb-saytidagi boshqaruv paneli orqali barcha sessiyalarni o'chirish mumkin.

Podspecni tayyorlash

Podspec fayli (.podspec yoki .podspec.json) — metama'lumotlar, bog'liqliklar, platformalar va manba kodi haqidagi ma'lumotlarni o'z ichiga olgan kutubxona manifestidir. Trunk bu faylni podning validatsiyasi va ro'yxatdan o'tkazilishi uchun ishlatadi. Nashr qilish uchun minimal podspec quyidagicha ko'rinadi:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Kutubxonaning qisqa tavsifi'
  s.description  = 'Imkoniyatlarni tushuntirish bilan batafsil tavsif'
  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

Podspecning asosiy maydonlari:

• name — pod nomi, Trunk reyestrida noyob bo'lishi kerak. Nomlar «birinchi kelgan» prinsipi bo'yicha ro'yxatga olinadi — nom band bo'lsa, nashr rad etiladi.
• version — MAJOR.MINOR.PATCH formatidagi semantik versiya. Trunk bir xil versiyani qayta nashr qilishni qabul qilmaydi — raqamni oshirish kerak.
• source — Git repozitoriyasiga havola va teg. Trunk manba kodini saqlamaydi, shuning uchun repozitoriya klonlash uchun mavjud bo'lishi kerak.
• platform — maqsadli platforma (iOS, macOS, tvOS, watchOS) va minimal SDK versiyasi.
• license — litsenziya turi. MIT, Apache-2.0, BSD yoki boshqa ochiq litsenziyani ko'rsatish tavsiya etiladi.

Nashr qilishdan oldin podspecni linter yordamida tekshirish kerak:

pod lib lint MyLibrary.podspec

Linter sintaksis, majburiy maydonlarning mavjudligi, fayl yo'llarining to'g'riligi va bog'liqliklarning hal qilinishini tekshiradi. Agar linting jarayonida xususiy manbalardan (private specs) foydalanilsa, --sources flagi qo'shiladi. Tarmoq yuklamasini o'tkazib yuborish (faqat mahalliy tekshirish) uchun --local-only flagi ishlatiladi.

Pod trunk push orqali nashr qilish

Podni nashr qilish uchun asosiy buyruq — pod trunk push. U podspec faylini Trunk serveriga uzatadi, u erda to'liq validatsiyadan o'tadi va umumiy reyestrda ro'yxatga olinadi. Sintaksis:

pod trunk push MyLibrary.podspec

--allow-warnings flagi ogohlantirishlar mavjud bo'lganda nashr qilishga ruxsat beradi. Odatiy bo'lib, har qanday ogohlantirish (warning) nashrni bloklaydi. Kutubxonada funksionallikka ta'sir qilmaydigan ma'lum ogohlantirishlar bo'lsa, bu flagdan foydalanish mumkin. Muhim: xatolar (errors) flaglardan qat'iy nazar har doim nashrni bloklaydi.

--synchronous flagi so'rovni sinxron qiladi — terminal serverda validatsiya tugashini kutadi. Odatiy bo'lib, buyruq yuborilgandan so'ng darhol boshqaruvni qaytaradi, server esa nashrni asinxron qayta ishlaydi. Sinxron rejim CI/CD da, keyingi pipeline bosqichi nashrning muvaffaqiyatiga bog'liq bo'lganda foydalidir.

--skip-import-validation flagi kutubxonaning test loyihasiga importini tekshirishni o'tkazib yuboradi. Bu nashrni tezlashtiradi, ammo kutubxonaning haqiqatan ham kompilyatsiya qilinishini kafolatlamaydi. Bu flagdan faqat qurilishning to'g'riligiga ishonchingiz komil bo'lsa foydalaning.

Odatiy variantlar bilan nashr namunasi:

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

Muvaffaqiyatli nashrdan so'ng Trunk tafsilotlar bilan JSON qaytaradi:

  Congrats

  MyLibrary (0.1.0) successfully published

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

Kutubxona har qanday iOS yoki macOS loyihasining Podfile orqali o'rnatish uchun mavjud bo'ladi. Odatda CocoaPods qidiruv indeksidagi ma'lumotlar bir necha daqiqa ichida yangilanadi, ammo kamdan-kam hollarda indeksatsiya bir soatgacha davom etishi mumkin.

Muhim cheklov: bir marta nashr qilingan pod versiyasini o'chirib bo'lmaydi. Bu allaqachon ushbu versiyadan foydalanayotgan loyihalarda buzilishlarning oldini olish uchun qilingan. Agar nashr xato bilan yakunlangan bo'lsa, keyingi versiyani tuzatish bilan nashr qilish mumkin, ammo qaytarish mumkin emas. Istisno — faqat CocoaPods xodimlari uchun mavjud bo'lgan pod trunk delete va haddan tashqari holatlarda qo'llaniladi (litsenziya buzilishi, zararli kod).

Relizlar va kirishni boshqarish

CocoaPods Trunk nashr qilingan podlarni boshqarish uchun bir nechta buyruqlarni taqdim etadi:

Egalarni qo'shish

Podni nashr qilish huquqini boshqa dasturchiga o'tkazish uchun quyidagi buyruq ishlatiladi:

pod trunk add-owner MyLibrary developer@email.com

Bajarilgandan so'ng yangi egasi podni boshqarishga to'liq kirish oladi: yangi versiyalarni nashr qilish, boshqa egalarni qo'shish va o'chirish, podni eskirgan deb belgilash. Egun Trunkning istalgan ro'yxatdan o'tgan foydalanuvchisi bo'lishi mumkin — oldindan ro'yxatdan o'tish majburiydir.

Egalarni o'chirish

Agar dasturchi loyihani tark etgan bo'lsa yoki endi podga kirish huquqiga ega bo'lmasligi kerak bo'lsa:

pod trunk remove-owner MyLibrary developer@email.com

Egani faqat joriy egasi o'chira oladi. Podning oxirgi egasini o'chirib bo'lmaydi — avval yangisini qo'shish kerak. Bu podning egasiz qolishining oldini oladi.

Podni eskirgan deb belgilash

Agar kutubxona endi qo'llab-quvvatlanmasa, uni eskirgan (deprecated) deb belgilash mumkin. Bu podni reyestrdan o'chirmaydi, lekin o'rnatish vaqtida foydalanuvchilarga ogohlantirish qo'shadi:

pod trunk deprecate MyLibrary

Ixtiyoriy ravishda almashtiruvchi podni ko'rsatish mumkin:

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

Eskirgan podni o'rnatishda CocoaPods terminalda ogohlantirish ko'rsatadi va ko'rsatilgan almashtiruvchiga o'tishni tavsiya qiladi. Bu mavjud loyihalarning qurilishini buzmasdan kutubxona qo'llab-quvvatlashni tugatishning to'g'ri usulidir.

Pod haqida ma'lumotni ko'rish

Pod haqida ma'lumot pod trunk info buyrug'i orqali mavjud:

pod trunk info MyLibrary

Buyruq podning barcha versiyalari, nashr sanalari, egalar ro'yxati va holatini (faol/eskirgan) ko'rsatadi. Muayyan versiyaning tafsilotlarini ko'rish uchun pod spec cat MyLibrary 0.1.0 ishlatiladi.

Xatolar va ularni hal qilish

Trunk bilan ishlashda dasturchilar tez-tez odatiy xatolarga duch kelishadi. Eng keng tarqalganlarini ko'rib chiqamiz:

Autentifikatsiya xatosi

Alomat: [!] Authentication failed. You need to register a session first.
Sabab: Sessiya tokeni yo'q yoki muddati tugagan. Tokenlarning cheklangan amal qilish muddati bor (odatiy bo'lib faoliyatsiz 30 kun).
Yechim: pod trunk register your@email.com 'Your Name' ni qayta bajaring. CI dan foydalanayotgan bo'lsangiz, COCOAPODS_TRUNK_TOKEN o'zgaruvchisining dolzarbligini tekshiring va kerak bo'lsa yangi token yarating.

Versiya ziddiyati

Alomat: [!] You have already pushed version 0.1.0 for MyLibrary.
Sabab: Mavjud versiyani qayta nashr qilish urinishi. Trunk versiyalarni ustiga yozishga ruxsat bermaydi.
Yechim: Podspecda semantik versiyalashga muvofiq versiyani oshiring. Podspecda xato qilgan bo'lsangiz, keyingi versiyani tuzatish bilan nashr qiling.

Podspec validatsiya xatosi

Alomat: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Sabab: source_files maydonida manba fayllariga yo'l noto'g'ri ko'rsatilgan.
Yechim: Podspecdagi yo'llarni tekshiring, barcha xatolar bartaraf etilgunga qadar pod lib lint ni mahalliy bajaring, so'ng nashrni takrorlang. Glob na'munlaridan foydalaning: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Ulanish vaqti tugashi

Alomat: [!] Connection to trunk.cocoapods.org failed. Timeout.
Sabab: Tarmoq muammolari yoki Trunk serverining vaqtinchalik mavjud emasligi.
Yechim: Serverning mavjudligini tekshiring: curl -I https://trunk.cocoapods.org. Agar server javob bersa, buyruqni bir necha daqiqadan so'ng takrorlang. IP manzilingiz bloklangan bo'lishi mumkin — boshqa ulanishdan yoki VPN orqali urinib ko'ring.

Podga kirishning yo'qligi

Alomat: [!] You do not have permission to push to MyLibrary.
Sabab: Siz podning egasi emassiz. Bu kimdir allaqachon shu nom bilan podni ro'yxatdan o'tkazgan bo'lsa sodir bo'ladi.
Yechim: Joriy pod egasi bilan bog'laning (uni pod trunk info MyLibrary orqali topish mumkin) va sizni pod trunk add-owner orqali qo'shishni so'rang. Pod nomi band bo'lsa, muqobil nomni ko'rib chiqing.