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 хранилището и таг. 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. Ако името на пода е заето, обмислете алтернативно име.