CocoaPods Trunk: шта је то, објављивање библиотека путем Trunk-а

Шта је CocoaPods Trunk?

CocoaPods Trunk — је серверска инфраструктура покренута 2015. године за централизовано објављивање pod библиотека. Пре појаве Trunk-а, сваки pod се дистрибуирао путем Git репозиторијума: програмер је морао да креира јавни репозиторијум, дода podspec датотеку и пошаље Pull Request у централни репозиторијум CocoaPods/Specs. Такав приступ је захтевао ручно модерисање и стварао кашњења при објављивању ажурирања.

Trunk је решио ове проблеме пружајући јединствени API за објављивање, ажурирање и уклањање подова. Сервис укључује четири кључне компоненте:

• Аутентификација — регистрација са потврдом е-поште и управљање токенима сесије. Сваки програмер добија јединствени токен који је везан за његов налог и уређаје.
• Валидација — аутоматска провера podspec-а пре објављивања, укључујући синтаксну анализу, линтинг зависности и проверу компатибилности платформи.
• Хостинг — чување метаподатака и верзија подова на CocoaPods серверима. Изворни код и даље остаје у програмеровом Git репозиторијуму, а Trunk чува само podspec датотеке и линкове.
• Управљање приступом — могућност додавања и уклањања власника пода, преноса права на објављивање, означавања подова као застарелих.

Архитектура Trunk-а је изграђена на Ruby on Rails стек-у са PostgreSQL базом података. Сервис користи HTTP API са JSON форматом за све операције, а CLI клијент pod trunk је део CocoaPods дистрибуције и инсталира се заједно са главним gem-ом cocoapods.

Тренутно је кроз Trunk објављено преко 100 000 подова, а укупан број преузимања премашује 50 милијарди. Свакодневно сервис обрађује хиљаде захтева за објављивање и ажурирање библиотека од програмера широм света.

Регистрација и аутентификација

Пре објављивања пода потребно је извршити регистрацију у Trunk-у. Процес се састоји из једног корака — команде pod trunk register:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, развој iOS'

Након извршења команде, на наведену е-пошту стиже писмо са линком за потврду. Клик на линк активира налог и креира токен сесије који се чува у системском ланцу кључева (Keychain на macOS-у, gnome-keyring или еквивалент на Linux-у). Токен се аутоматски користи у свим наредним pod trunk операцијама.

Параметар --description није обавезан, али се препоручује — помаже у идентификацији сесије при прегледу активних сесија путем pod trunk me. Ако радите на више машина (радна станица, CI сервер), опис ће вам омогућити да разликујете једну сесију од друге.

За проверу статуса аутентификације користи се команда:

pod trunk me

Излаз приказује е-пошту, име, листу ваших подова (ако сте већ објављивали) и активне сесије. Пример резултата:

  - 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 trunk remove-session или избрисати све сесије кроз контролну таблу на CocoaPods веб-сајту.

Припрема podspec-а

Podspec датотека (.podspec или .podspec.json) — манифест библиотеке који садржи метаподатке, зависности, информације о платформама и изворном коду. Trunk користи ову датотеку за валидацију и регистрацију пода. Минимални 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 — име пода, мора бити јединствено у Trunk регистру. Имена се региструју по принципу «први заузети» — ако је име заузето, објављивање ће бити одбијено.
• version — семантичка верзија у формату MAJOR.MINOR.PATCH. Trunk не прихвата поновно објављивање исте верзије — потребно је повећати број.
• source — линк ка Git репозиторијуму и tag. 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 trunk push. Она преноси podspec датотеку на Trunk сервер, где пролази потпуну валидацију и региструје се у јавном регистру. Синтакса:

pod trunk push MyLibrary.podspec

Флаг --allow-warnings дозвољава објављивање у присуству упозорења. Подразумевано, сва упозорења (warnings) блокирају објављивање. Ако библиотека има позната упозорења која не утичу на функционалност, можете користити овај флаг. Важно: грешке (errors) увек блокирају објављивање, без обзира на флагове.

Флаг --synchronous чини захтев синхроним — терминал чека завршетак валидације на серверу. Подразумевано, команда враћа контролу одмах након слања, а сервер обрађује објављивање асинхроно. Синхрони режим је користан у CI/CD-у, када следећи корак pipeline-а зависи од успешности објављивања.

Флаг --skip-import-validation прескаче проверу импорта библиотеке у тест пројекат. Ово убрзава објављивање, али не гарантује да се библиотека заиста компајлира. Користите овај флаг само ако сте сигурни у исправност компилације.

Пример објављивања са типичним опцијама:

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 trunk delete, доступан само запосленима у CocoaPods-у и примењује се у крајњим случајевима (кршење лиценце, злонамерни код).

Управљање издањима и приступом

CocoaPods Trunk пружа неколико команди за администрирање објављених подова:

Додавање власника

За пренос права на објављивање пода другом програмеру користи се команда:

pod trunk add-owner MyLibrary developer@email.com

Након извршења, нови власник добија потпун приступ управљању подом: објављивање нових верзија, додавање и уклањање других власника, означавање пода као застарелог. Власник може бити било који регистровани корисник Trunk-а — претходна регистрација је обавезна.

Уклањање власника

Ако је програмер напустио пројекат или више не треба да има приступ поду:

pod trunk remove-owner MyLibrary developer@email.com

Власника може уклонити само тренутни власник. Не може се уклонити последњи власник пода — прво је потребно додати новог. Ово спречава ситуацију у којој под остаје без власника.

Означавање пода као застарелог

Ако библиотека више није подржана, може се означити као застарела (deprecated). Ово не уклања под из регистра, али додаје упозорење корисницима при инсталацији:

pod trunk deprecate MyLibrary

Опционо се може навести заменски под:

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

Приликом инсталације застарелог пода, CocoaPods приказује упозорење у терминалу и препоручује прелазак на наведену замену. Ово је исправан начин за окончање подршке библиотеке без нарушавања компилације постојећих пројеката.

Преглед информација о поду

Информације о поду доступне су путем команде pod trunk info:

pod trunk info MyLibrary

Команда приказује све верзије пода, датуме објављивања, листу власника и статус (активан/застарео). За преглед детаља одређене верзије користи се pod spec cat MyLibrary 0.1.0.

Грешке и њихово решавање

При раду са Trunk-ом, програмери се често сусрећу са типичним грешкама. Размотримо најчешће:

Грешка аутентификације

Симптом: [!] Authentication failed. You need to register a session first.
Узрок: Токен сесије недостаје или је истекао. Токени имају ограничен рок трајања (подразумевано 30 дана без активности).
Решење: Поново извршити 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-а.

Недостатак приступа поду

Симптом: [!] You do not have permission to push to MyLibrary.
Узрок: Нисте власник пода. Ово се дешава ако је неко већ регистровао под са тим именом.
Решење: Контактирати тренутног власника пода (можете сазнати путем pod trunk info MyLibrary) и затражити да вас дода путем pod trunk add-owner. Ако је име пода заузето, размотрите алтернативно име.