CocoaPods Trunk: τι είναι, δημοσίευση βιβλιοθηκών μέσω Trunk

Τι είναι το CocoaPods Trunk;

CocoaPods Trunk — είναι μια υποδομή διακομιστή που ξεκίνησε το 2015 για κεντρικοποιημένη δημοσίευση βιβλιοθηκών pod. Πριν από την εμφάνιση του Trunk, κάθε pod διανέμονταν μέσω αποθετηρίου Git: ο προγραμματιστής έπρεπε να δημιουργήσει ένα δημόσιο αποθετήριο, να προσθέσει ένα αρχείο podspec και να στείλει ένα Pull Request στο κεντρικό αποθετήριο CocoaPods/Specs. Αυτή η προσέγγιση απαιτούσε χειροκίνητη εποπτεία και δημιουργούσε καθυστερήσεις στη δημοσίευση ενημερώσεων.

Το Trunk έλυσε αυτά τα προβλήματα παρέχοντας ένα ενοποιημένο API για δημοσίευση, ενημέρωση και διαγραφή pod. Η υπηρεσία περιλαμβάνει τέσσερα βασικά στοιχεία:

• Αυθεντικοποίηση — εγγραφή με επιβεβαίωση email και διαχείριση tokens sessions. Κάθε προγραμματιστής λαμβάνει ένα μοναδικό token που συνδέεται με τον λογαριασμό και τις συσκευές του.
• Επικύρωση — αυτόματος έλεγχος του podspec πριν από τη δημοσίευση, συμπεριλαμβανομένης της συντακτικής ανάλυσης, του linting εξαρτήσεων και του ελέγχου συμβατότητας πλατφορμών.
• Φιλοξενία — αποθήκευση μεταδεδομένων και εκδόσεων pod στους διακομιστές CocoaPods. Ο πηγαίος κώδικας παραμένει στο αποθετήριο Git του προγραμματιστή, ενώ το Trunk αποθηκεύει μόνο αρχεία podspec και συνδέσμους.
• Διαχείριση πρόσβασης — δυνατότητα προσθήκης και αφαίρεσης ιδιοκτητών pod, μεταφοράς δικαιωμάτων δημοσίευσης, επισήμανσης pod ως παρωχημένων.

Η αρχιτεκτονική του Trunk βασίζεται στη στοίβα Ruby on Rails με βάση δεδομένων PostgreSQL. Η υπηρεσία χρησιμοποιεί HTTP API με μορφή JSON για όλες τις λειτουργίες, και ο πελάτης CLI pod trunk είναι μέρος της διανομής CocoaPods και εγκαθίσταται μαζί με το κύριο gem cocoapods.

Επί του παρόντος, πάνω από 100.000 pod έχουν δημοσιευτεί μέσω Trunk, με συνολικό αριθμό λήψεων που ξεπερνά τα 50 δισεκατομμύρια. Καθημερινά, η υπηρεσία επεξεργάζεται χιλιάδες αιτήματα δημοσίευσης και ενημέρωσης βιβλιοθηκών από προγραμματιστές σε όλο τον κόσμο.

Εγγραφή και αυθεντικοποίηση

Πριν από τη δημοσίευση ενός pod, πρέπει να εγγραφείτε στο Trunk. Η διαδικασία αποτελείται από ένα βήμα — την εντολή pod trunk register:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, ανάπτυξη iOS'

Μετά την εκτέλεση της εντολής, στην καθορισμένη διεύθυνση email αποστέλλεται ένα μήνυμα με σύνδεσμο επιβεβαίωσης. Κάνοντας κλικ στον σύνδεσμο ενεργοποιείται ο λογαριασμός και δημιουργείται ένα token session που αποθηκεύεται στην αλυσίδα κλειδιών συστήματος (Keychain σε macOS, gnome-keyring ή αντίστοιχο σε Linux). Το token χρησιμοποιείται αυτόματα σε όλες τις επόμενες λειτουργίες pod trunk.

Η παράμετρος --description είναι προαιρετική αλλά συνιστάται — βοηθά στην αναγνώριση του session κατά την προβολή ενεργών sessions μέσω pod trunk me. Εάν εργάζεστε σε πολλά μηχανήματα (σταθμός εργασίας, διακομιστής CI), η περιγραφή σας επιτρέπει να διακρίνετε το ένα session από το άλλο.

Για τον έλεγχο της κατάστασης αυθεντικοποίησης χρησιμοποιείται η ακόλουθη εντολή:

pod trunk me

Η έξοδος εμφανίζει email, όνομα, λίστα των pod σας (εάν έχετε ήδη δημοσιεύσει) και ενεργά sessions. Παράδειγμα αποτελέσματος:

  - 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) η αυθεντικοποίηση γίνεται μέσω token που μεταφέρεται μέσω της μεταβλητής περιβάλλοντος COCOAPODS_TRUNK_TOKEN. Το token μπορεί να ληφθεί με την εντολή:

pod trunk me --token-only

Αυτό το token αποθηκεύεται στις ρυθμίσεις CI ως μυστική μεταβλητή και στο στάδιο δημοσίευσης χρησιμοποιείται χωρίς εκ νέου εγγραφή. Παράδειγμα για GitHub Actions:

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

Σημαντικό: το token παρέχει πλήρη πρόσβαση στη διαχείριση pod που είναι συνδεδεμένα με τον λογαριασμό. Ποτέ μην το δημοσιεύετε σε δημόσια αποθετήρια και μην το μεταδίδετε σε τρίτους. Σε περίπτωση παραβίασης, το token μπορεί να ανακληθεί μέσω pod trunk remove-session ή να διαγραφούν όλα τα sessions μέσω του πίνακα ελέγχου στην ιστοσελίδα CocoaPods.

Προετοιμασία podspec

Το αρχείο podspec (.podspec ή .podspec.json) — είναι το manifest της βιβλιοθήκης που περιέχει μεταδεδομένα, εξαρτήσεις, πληροφορίες για πλατφόρμες και πηγαίο κώδικα. Το 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 και tag. Το Trunk δεν αποθηκεύει τον πηγαίο κώδικα, επομένως το αποθετήριο πρέπει να είναι προσβάσιμο για κλωνοποίηση.
• platform — πλατφόρμα-στόχος (iOS, macOS, tvOS, watchOS) και ελάχιστη έκδοση SDK.
• license — τύπος άδειας. Συνιστάται η αναφορά MIT, Apache-2.0, BSD ή άλλης ανοικτής άδειας.

Πριν από τη δημοσίευση, το podspec πρέπει να ελεγχθεί για ορθότητα με τη χρήση linter:

pod lib lint MyLibrary.podspec

Ο linter ελέγχει τη σύνταξη, την ύπαρξη υποχρεωτικών πεδίων, την ορθότητα διαδρομών αρχείων και την επιλυσιμότητα εξαρτήσεων. Εάν στη διαδικασία linting χρησιμοποιούνται ιδιωτικές πηγές (private specs), προστίθεται η σημαία --sources. Για παράλειψη λήψης δικτύου (μόνο τοπικός έλεγχος) χρησιμοποιείται η σημαία --local-only.

Δημοσίευση μέσω pod trunk push

Η κύρια εντολή για δημοσίευση pod — pod trunk push. Στέλνει το αρχείο podspec στον διακομιστή Trunk, όπου υποβάλλεται σε πλήρη επικύρωση και καταχωρείται στο δημόσιο μητρώο. Σύνταξη:

pod trunk push MyLibrary.podspec

Η σημαία --allow-warnings επιτρέπει τη δημοσίευση παρουσία προειδοποιήσεων. Από προεπιλογή, οποιεσδήποτε προειδοποιήσεις (warnings) μπλοκάρουν τη δημοσίευση. Εάν η βιβλιοθήκη έχει γνωστές προειδοποιήσεις που δεν επηρεάζουν τη λειτουργικότητα, μπορείτε να χρησιμοποιήσετε αυτή τη σημαία. Σημαντικό: τα σφάλματα (errors) μπλοκάρουν πάντα τη δημοσίευση, ανεξάρτητα από τις σημαίες.

Η σημαία --synchronous καθιστά το αίτημα σύγχρονο — το τερματικό περιμένει την ολοκλήρωση της επικύρωσης στον διακομιστή. Από προεπιλογή, η εντολή επιστρέφει τον έλεγχο αμέσως μετά την αποστολή και ο διακομιστής επεξεργάζεται τη δημοσίευση ασύγχρονα. Η σύγχρονη λειτουργία είναι χρήσιμη σε CI/CD, όταν το επόμενο βήμα του pipeline εξαρτάται από την επιτυχία της δημοσίευσης.

Η σημαία --skip-import-validation παραλείπει τον έλεγχο εισαγωγής της βιβλιοθήκης σε ένα δοκιμαστικό έργο. Αυτό επιταχύνει τη δημοσίευση, αλλά δεν εγγυάται ότι η βιβλιοθήκη πραγματικά μεταγλωττίζεται. Χρησιμοποιήστε αυτή τη σημαία μόνο εάν είστε σίγουροι για την ορθότητα του 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.
Αιτία: Το token session λείπει ή έχει λήξει. Τα tokens έχουν περιορισμένη διάρκεια ισχύος (από προεπιλογή 30 ημέρες χωρίς δραστηριότητα).
Λύση: Εκτελέστε ξανά pod trunk register your@email.com 'Your Name'. Εάν χρησιμοποιείτε CI, ελέγξτε την επικαιρότητα της μεταβλητής COCOAPODS_TRUNK_TOKEN και δημιουργήστε νέο 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 είναι κατειλημμένο, εξετάστε ένα εναλλακτικό όνομα.