CocoaPods Trunk: bu nədir, kitabxanaların Trunk vasitəsilə dərci

CocoaPods Trunk nədir?

CocoaPods Trunk — 2015-ci ildə pod kitabxanalarının mərkəzləşdirilmiş dərci üçün işə salınmış server infrastrukturudur. Trunk yaranana qədər hər bir pod Git repozitoriyası vasitəsilə yayılırdı: tərtibatçı ictimai repozitoriya yaratmalı, podspec faylı əlavə etməli və mərkəzi CocoaPods/Specs repozitoriyasına Pull Request göndərməli idi. Bu yanaşma əl ilə moderasiya tələb edir və yeniləmələrin dərcində gecikmələr yaradırdı.

Trunk bu problemləri həll edərək podların dərci, yenilənməsi və silinməsi üçün vahid API təmin etdi. Xidmət dörd əsas komponenti əhatə edir:

• Autentifikasiya — email təsdiqi ilə qeydiyyat və sessiya tokenlərinin idarə edilməsi. Hər bir tərtibatçı öz hesabına və cihazlarına bağlanan unikal token alır.
• Validasiya — dərcdən əvvəl podspec-in avtomatik yoxlanışı, o cümlədən sintaktik analiz, asılılıqların lintinqi və platforma uyğunluğunun yoxlanılması.
• Hostinq — podların metadata və versiyalarının CocoaPods serverlərində saxlanması. Mənbə kodu hələ də tərtibatçının Git repozitoriyasında yerləşir, Trunk isə yalnız podspec fayllarını və linkləri saxlayır.
• Giriş idarəetməsi — pod sahiblərini əlavə etmək və silmək, dərc hüquqlarını ötürmək, podları köhnəlmiş kimi qeyd etmək imkanı.

Trunk-un arxitekturası PostgreSQL verilənlər bazası ilə Ruby on Rails stack-ı üzərində qurulmuşdur. Xidmət bütün əməliyyatlar üçün JSON formatı ilə HTTP API istifadə edir, pod trunk CLI klienti isə CocoaPods distribusiyasının bir hissəsidir və əsas cocoapods gem-i ilə birlikdə quraşdırılır.

Hal-hazırda Trunk vasitəsilə 100 000-dən çox pod dərc edilmişdir, ümumi yükləmə sayı 50 milyardı keçmişdir. Xidmət hər gün dünyanın hər yerindən tərtibatçıların minlərlə dərc və yeniləmə sorğusunu emal edir.

Qeydiyyat və autentifikasiya

Pod dərc etməzdən əvvəl Trunk-da qeydiyyatdan keçmək lazımdır. Proses bir addımdan ibarətdir — pod trunk register əmri:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, iOS tərtibatı'

Əmr icra edildikdən sonra göstərilən email-ə təsdiq linki olan məktub gəlir. Linkə keçid hesabı aktivləşdirir və sistem açar saxlayıcısında (macOS-də Keychain, Linux-da gnome-keyring və ya ekvivalent) saxlanılan sessiya tokeni yaradır. Token bütün sonrakı pod trunk əməliyyatlarında avtomatik istifadə olunur.

--description parametri isteğe bağlıdır, lakin tövsiyə olunur — aktiv sessiyalara pod trunk me vasitəsilə baxarkən sessiyanı identifikasiya etməyə kömək edir. Bir neçə maşında işləyirsinizsə (iş stansiyası, CI server), təsvir bir sessiyanı digərindən fərqləndirməyə imkan verir.

Autentifikasiya statusunu yoxlamaq üçün aşağıdakı əmr istifadə olunur:

pod trunk me

Nəticə email, ad, podlarınızın siyahısı (əgər artıq dərc etmisinizsə) və aktiv sessiyaları göstərir. Nümunə nəticə:

  - 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 inkişafı

CI serverlərində (GitHub Actions, GitLab CI, Jenkins) autentifikasiya COCOAPODS_TRUNK_TOKEN mühit dəyişəni vasitəsilə ötürülən tokenlə həyata keçirilir. Tokeni aşağıdakı əmrlə əldə etmək olar:

pod trunk me --token-only

Bu token CI parametrlərində gizli dəyişən kimi saxlanılır və dərc mərhələsində təkrar qeydiyyat olmadan istifadə olunur. GitHub Actions üçün nümunə:

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

Vacib: token hesaba bağlı podların idarə edilməsinə tam giriş verir. Onu heç vaxt ictimai repozitoriyalarda dərc etməyin və üçüncü şəxslərə ötürməyin. Token kompromitasiya olunarsa, onu pod trunk remove-session vasitəsilə ləğv edə və ya CocoaPods saytında idarəetmə paneli vasitəsilə bütün sessiyaları silə bilərsiniz.

Podspec-in hazırlanması

Podspec faylı (.podspec və ya .podspec.json) — metadata, asılılıqlar, platformalar və mənbə kodu haqqında məlumatları ehtiva edən kitabxana manifestidir. Trunk bu faylı podun validasiyası və qeydiyyatı üçün istifadə edir. Dərc üçün minimal podspec belə görünür:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Kitabxananın qısa təsviri'
  s.description  = 'İmkanların izahı ilə geniş təsvir'
  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-in əsas sahələri:

• name — podun adı, Trunk reyestrində unikal olmalıdır. Adlar «ilk kim gəldi» prinsipi ilə qeydiyyata alınır — ad məşğuldursa, dərc rədd ediləcək.
• version — MAJOR.MINOR.PATCH formatında semantik versiya. Trunk eyni versiyanın təkrar dərcini qəbul etmir — nömrəni artırmaq lazımdır.
• source — Git repozitoriyasına keçid və teq. Trunk mənbə kodunu saxlamır, ona görə də repozitoriya klonlaşdırma üçün əlçatan olmalıdır.
• platform — hədəf platforma (iOS, macOS, tvOS, watchOS) və minimal SDK versiyası.
• license — lisenziya növü. MIT, Apache-2.0, BSD və ya digər açıq lisenziyanı göstərmək tövsiyə olunur.

Dərcdən əvvəl podspec-i linter vasitəsilə yoxlamaq lazımdır:

pod lib lint MyLibrary.podspec

Linter sintaksisi, məcburi sahələrin mövcudluğunu, fayl yollarının düzgünlüyünü və asılılıqların həll oluna bilməsini yoxlayır. Lintinq prosesində özəl mənbələr (private specs) istifadə olunarsa, --sources flag-ı əlavə edilir. Şəbəkə yükləməsini keçmək (yalnız lokal yoxlama) üçün --local-only flag-ı istifadə olunur.

Pod trunk push vasitəsilə dərc

Podun dərci üçün əsas əmr — pod trunk push. O, podspec faylını Trunk serverinə ötürür, burada tam validasiyadan keçir və ictimai reyestrdə qeydiyyata alınır. Sintaksis:

pod trunk push MyLibrary.podspec

--allow-warnings flag-ı xəbərdarlıqlar olduqda dərcə icazə verir. Susmaya görə hər hansı xəbərdarlıq (warning) dərci bloklayır. Kitabxanada funksionallığa təsir etməyən məlum xəbərdarlıqlar varsa, bu flag-dan istifadə etmək olar. Vacib: səhvlər (errors) flag-lardan asılı olmayaraq həmişə dərci bloklayır.

--synchronous flag-ı sorğunu sinxron edir — terminal serverdə validasiyanın bitməsini gözləyir. Susmaya görə əmr göndərişdən dərhal sonra idarəni qaytarır, server isə dərci asinxron emal edir. Sinxron rejim CI/CD-də, növbəti pipeline addımı dərcin uğurundan asılı olduqda faydalıdır.

--skip-import-validation flag-ı kitabxananın test layihəsinə idxalının yoxlanışını keçir. Bu dərci sürətləndirir, lakin kitabxananın həqiqətən kompilyasiya olunduğunu zəmanət vermir. Bu flag-dan yalnız qurulmanın düzgünlüyünə əminsinizsə istifadə edin.

Tipik seçimlərlə dərc nümunəsi:

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

Uğurlu dərcdən sonra Trunk təfərrüatlarla JSON qaytarır:

  Congrats

  MyLibrary (0.1.0) successfully published

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

Kitabxana istənilən iOS və ya macOS layihəsinin Podfile vasitəsilə quraşdırılması üçün əlçatan olur. Adətən CocoaPods axtarış indeksindəki məlumatlar bir neçə dəqiqə ərzində yenilənir, lakin nadir hallarda indeksasiya bir saata qədər çəkə bilər.

Vacib məhdudiyyət: bir dəfə dərc edilmiş pod versiyasını siləmək olmaz. Bu, artıq həmin versiyadan istifadə edən layihələrdə xətaların qarşısını almaq üçün edilir. Dərc səhvlə başa çatıbsa, növbəti versiyanı düzəlişlə dərc etmək olar, lakin geri qaytarmaq mümkün deyil. İstisna — yalnız CocoaPods əməkdaşları üçün əlçatan olan pod trunk delete və həddindən artıq hallarda tətbiq edilir (lisenziya pozuntusu, zərərli kod).

Relizlərin və girişin idarə edilməsi

CocoaPods Trunk dərc edilmiş podların idarə edilməsi üçün bir neçə əmr təqdim edir:

Sahib əlavə etmək

Podun dərc hüququnu başqa tərtibatçıya ötürmək üçün aşağıdakı əmr istifadə olunur:

pod trunk add-owner MyLibrary developer@email.com

İcradan sonra yeni sahib podun idarə edilməsinə tam giriş əldə edir: yeni versiyaların dərci, digər sahiblərin əlavə edilməsi və silinməsi, podun köhnəlmiş kimi qeyd edilməsi. Sahib Trunk-ın istənilən qeydiyyatdan keçmiş istifadəçisi ola bilər — əvvəlcədən qeydiyyat məcburidir.

Sahibi silmək

Əgər tərtibatçı layihəni tərk edibsə və ya artıq poda girişi olmamalıdırsa:

pod trunk remove-owner MyLibrary developer@email.com

Sahibi yalnız cari sahib silə bilər. Podun son sahibini silmək olmaz — əvvəlcə yenisini əlavə etmək lazımdır. Bu, podun sahibsiz qalmasının qarşısını alır.

Podun köhnəlmiş kimi qeyd edilməsi

Kitabxana artıq dəstəklənmirsə, onu köhnəlmiş (deprecated) kimi qeyd etmək olar. Bu podu reyestrdən silmir, lakin quraşdırma zamanı istifadəçilərə xəbərdarlıq əlavə edir:

pod trunk deprecate MyLibrary

İsteğe bağlı olaraq əvəzedici pod göstərilə bilər:

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

Köhnəlmiş pod quraşdırarkən CocoaPods terminalda xəbərdarlıq göstərir və göstərilən əvəzediciyə keçməyi tövsiyə edir. Bu, mövcud layihələrin qurulmasını pozmadan kitabxana dəstəyini bitirməyin düzgün yoludur.

Pod haqqında məlumata baxmaq

Pod haqqında məlumat pod trunk info əmri vasitəsilə əlçatandır:

pod trunk info MyLibrary

Əmr podun bütün versiyalarını, dərc tarixlərini, sahiblərin siyahısını və statusu (aktiv/köhnəlmiş) göstərir. Müəyyən versiyanın təfərrüatlarına baxmaq üçün pod spec cat MyLibrary 0.1.0 istifadə olunur.

Xətalar və onların həlli

Trunk ilə işləyərkən tərtibatçılar tez-tez tipik səhvlərlə qarşılaşırlar. Ən geniş yayılmışları nəzərdən keçirək:

Autentifikasiya xətası

Simptom: [!] Authentication failed. You need to register a session first.
Səbəb: Sessiya tokeni yoxdur və ya müddəti bitmişdir. Tokenlərin məhdud istifadə müddəti var (susmaya görə aktivlik olmadan 30 gün).
Həll: pod trunk register your@email.com 'Your Name' əmrini təkrar yerinə yetirin. CI istifadə edirsinizsə, COCOAPODS_TRUNK_TOKEN dəyişəninin aktuallığını yoxlayın və zəruri hallarda yeni token yaradın.

Versiya konflikti

Simptom: [!] You have already pushed version 0.1.0 for MyLibrary.
Səbəb: Mövcud versiyanın təkrar dərc edilməsi cəhdi. Trunk versiyaların üzərinə yazmağa icazə vermir.
Həll: Podspec-də semantik versiyalama uyğun olaraq versiyanı artırın. Podspec-də səhv etmisinizsə, növbəti versiyanı düzəlişlə dərc edin.

Podspec validasiya xətası

Simptom: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Səbəb: source_files sahəsində mənbə fayllarına gedən yol düzgün göstərilməyib.
Həll: Podspec-də yolları yoxlayın, bütün səhvlər aradan qaldırılana qədər lokal olaraq pod lib lint icra edin, sonra dərci təkrarlayın. Glob nümunələrindən istifadə edin: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Bağlantı vaxt aşımı

Simptom: [!] Connection to trunk.cocoapods.org failed. Timeout.
Səbəb: Şəbəkə problemləri və ya Trunk serverinin müvəqqəti əlçatmazlığı.
Həll: Serverin əlçatanlığını yoxlayın: curl -I https://trunk.cocoapods.org. Server cavab verirsə, bir neçə dəqiqədən sonra əmri təkrarlayın. IP-niz bloklanmış ola bilər — başqa bağlantıdan və ya VPN vasitəsilə cəhd edin.

Poda girişin olmaması

Simptom: [!] You do not have permission to push to MyLibrary.
Səbəb: Siz podun sahibi deyilsiniz. Bu, kimsə artıq bu adla pod qeydiyyatdan keçiribsə baş verir.
Həll: Cari pod sahibi ilə əlaqə saxlayın (onu pod trunk info MyLibrary vasitəsilə tapmaq olar) və sizi pod trunk add-owner vasitəsilə əlavə etməsini xahiş edin. Pod adı məşğuldursa, alternativ ad seçin.