pubspec.yaml — τι είναι, δομή και διαμόρφωση εξαρτήσεων στο Flutter

Τι είναι το pubspec.yaml

pubspec.yaml — είναι ένα αρχείο manifest σε μορφή YAML που χρησιμοποιεί ο διαχειριστής πακέτων pub για τη διαχείριση έργων Dart και Flutter. Βρίσκεται στη ρίζα του έργου και επεξεργάζεται σε κάθε εντολή flutter pub get. Σε αντίθεση με άλλες πλατφόρμες όπου η διαμόρφωση είναι κατανεμημένη σε πολλά αρχεία, το Flutter χρησιμοποιεί ένα κεντρικοποιημένο manifest για όλες τις ανάγκες.

Το αρχείο περιέχει μεταδεδομένα: όνομα έργου, περιγραφή, έκδοση, συγγραφέα. Αυτά τα δεδομένα χρησιμοποιούνται κατά τη δημοσίευση του πακέτου στο pub.dev και κατά την κατασκευή της εφαρμογής για το App Store και το Google Play. Το πεδίο description εμφανίζεται στα αποτελέσματα αναζήτησης πακέτων, επομένως πρέπει να είναι πληροφοριακό και να περιέχει λέξεις-κλειδιά με τις οποίες άλλοι προγραμματιστές μπορούν να βρουν τη βιβλιοθήκη.

Χωρίς σωστό pubspec.yaml, ένα έργο Flutter δεν μπορεί να κατασκευαστεί. Συντακτικά σφάλματα ή λανθασμένες εσοχές οδηγούν σε άμεση αποτυχία μεταγλώττισης με μήνυμα Error on line X. Το YAML είναι ευαίσθητο στα κενά: ένα επιπλέον κενό αλλάζει τη δομή δεδομένων και το tab προκαλεί συντακτικό σφάλμα. Γι' αυτό, κατά τη μη αυτόματη επεξεργασία του pubspec.yaml είναι σημαντικό να χρησιμοποιείτε ένα πρόγραμμα επεξεργασίας με επισήμανση σύνταξης YAML, όπως το VS Code με την επίσημη επέκταση για Flutter.

Κύριες ενότητες του pubspec.yaml

Το pubspec.yaml αποτελείται από υποχρεωτικές και προαιρετικές ενότητες. Κάθε ενότητα είναι υπεύθυνη για μια συγκεκριμένη πτυχή της διαμόρφωσης του έργου. Η σειρά των ενοτήτων δεν είναι σημαντική, αλλά σύμφωνα με τη σύμβαση της κοινότητας τηρείται μια ιεραρχία: μεταδεδομένα, περιβάλλον, εξαρτήσεις, πόροι, πλατφόρμες.

name και description

Το πεδίο name ορίζει το μοναδικό αναγνωριστικό του πακέτου σε μορφή snake_case, αποτελούμενο μόνο από πεζά λατινικά γράμματα, αριθμούς και κάτω παύλες. Το πεδίο description — μια σύντομη περιγραφή του έργου έως 180 χαρακτήρες, υποχρεωτική για δημοσίευση στο pub.dev. Η περιγραφή πρέπει να εξηγεί τον σκοπό του πακέτου, χωρίς να επαναλαμβάνει το όνομα, και να περιέχει λέξεις-κλειδιά για βελτιστοποίηση αναζήτησης του αποθετηρίου.

name: my_flutter_app
description: Εφαρμογή διαχείρισης εργασιών με Flutter
publish_to: 'none'

version και environment

Το πεδίο version χρησιμοποιεί σημασιολογική έκδοση major.minor.patch με προαιρετικό αριθμό κατασκευής μετά το σύμβολο συν (1.0.0+1). Η ενότητα environment ορίζει τις ελάχιστες και μέγιστες εκδόσεις του Dart και Flutter SDK για εγγύηση συμβατότητας. Εάν μια νέα έκδοση του SDK περιέχει κρίσιμες αλλαγές μη συμβατές με τον κώδικα του έργου, η μεταγλώττιση θα διακοπεί με ένα κατανοητό μήνυμα σφάλματος.

version: 1.0.0+1
environment:
  sdk: '>=3.2.0 <4.0.0'
  flutter: '>=3.16.0'

dependencies και dev_dependencies

Η ενότητα dependencies απαριθμεί τα πακέτα που είναι απαραίτητα για τη λειτουργία της εφαρμογής κατά τον χρόνο εκτέλεσης. Η ενότητα dev_dependencies περιέχει πακέτα για δοκιμές, δημιουργία κώδικα και ανάπτυξη — αυτά δεν περιλαμβάνονται στην τελική έκδοση. Ο διαχωρισμός των εξαρτήσεων είναι κρίσιμος για την απόδοση: κάθε πακέτο στο dependencies αυξάνει το μέγεθος του τελικού APK ή IPA, καθώς και τον χρόνο εκκίνησης της εφαρμογής λόγω αρχικοποίησης πρόσθετων βιβλιοθηκών.

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0
  provider: ^6.1.0
  shared_preferences: ^2.2.0
  cached_network_image: ^3.3.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  mockito: ^5.4.0
  build_runner: ^2.4.0

Ρύθμιση assets και γραμματοσειρών

Η ενότητα flutter περιέχει υποενότητες για τη ρύθμιση πόρων, γραμματοσειρών και παραμέτρων πλατφόρμας. Οι πόροι συνδέονται μέσω ενός πίνακα paths με καθορισμό συγκεκριμένων αρχείων ή ολόκληρων καταλόγων. Όλες οι διαδρομές καθορίζονται σχετικά με τη ρίζα του έργου, όχι σχετικά με το pubspec.yaml. Αυτή είναι μια σημαντική λεπτομέρεια που συχνά προκαλεί σύγχυση σε αρχάριους προγραμματιστές Flutter.

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/icons/
    - assets/config.json
    - assets/data/translations/
  fonts:
    - family: RobotoMono
      fonts:
        - asset: fonts/RobotoMono-Regular.ttf
        - asset: fonts/RobotoMono-Bold.ttf
          weight: 700
        - asset: fonts/RobotoMono-Italic.ttf
          style: italic

Η σύνδεση assets μέσω pubspec.yaml καθιστά τα αρχεία προσβάσιμα μέσω του AssetBundle κατά τον χρόνο εκτέλεσης. Αυτό λειτουργεί για εικόνες, JSON, αρχεία κειμένου και οποιουσδήποτε άλλους πόρους. Το Flutter υποστηρίζει αυτόματα διαφορετικές αναλύσεις οθόνης: εάν τοποθετήσετε images/2x/ και images/3x/, το Flutter θα επιλέξει την κατάλληλη έκδοση της εικόνας με βάση το device pixel ratio της συσκευής. Γι' αυτό, αρκεί να καθορίσετε στο assets μόνο τον ριζικό φάκελο images/.

Προσαρμοσμένες γραμματοσειρές προστίθενται μέσω της ενότητας fonts με καθορισμό family και λίστας τυπογραφικών στοιχείων. Μετά την αλλαγή του pubspec.yaml, πρέπει να εκτελέσετε το flutter pub get για εφαρμογή των ρυθμίσεων. Οι γραμματοσειρές μπορούν να χρησιμοποιηθούν τόσο καθολικά στο θέμα MaterialApp όσο και τοπικά σε συγκεκριμένα widget. Για κάθε τυπογραφικό στοιχείο μπορείτε να καθορίσετε weight (100-900) και style (normal, italic), επιτρέποντας στο Flutter να επιλέξει σωστά το αρχείο γραμματοσειράς κατά τη χρήση FontWeight και FontStyle στον κώδικα.

Διαχείριση εξαρτήσεων και εκδόσεων

Το pub υποστηρίζει διάφορους τρόπους καθορισμού πηγών εξαρτήσεων: pub.dev, αποθετήρια Git, τοπικές διαδρομές και ιδιωτικά αποθετήρια. Η επιλογή πηγής εξαρτάται από το στάδιο ανάπτυξης: για σταθερές εκδόσεις χρησιμοποιείται το pub.dev, για forks και προσαρμοσμένες τροποποιήσεις — Git, για παράλληλα αναπτυσσόμενες βιβλιοθήκες — τοπική διαδρομή.

Ο τελεστής ^version σημαίνει συμβατή έκδοση: το ^1.2.0 επιτρέπει εκδόσεις >=1.2.0 και <2.0.0. Αυτό είναι ανάλογο με τον τελεστή ~> στο CocoaPods και τον τελεστή Caret στο npm. Το pub επιλύει αυτόματα το Dependency Hell μέσω αλγορίθμου SAT-solver που βρίσκει έναν συνδυασμό εκδόσεων που ικανοποιεί όλους τους περιορισμούς. Εάν δεν υπάρχει τέτοιος συνδυασμός, το pub εμφανίζει λεπτομερές μήνυμα με ένδειξη των αντικρουόμενων πακέτων.

Το αρχείο pubspec.lock καθορίζει τις ακριβείς εκδόσεις εξαρτήσεων. Πρέπει να φυλάσσεται στο σύστημα ελέγχου εκδόσεων για εφαρμογές, ώστε να διασφαλίζονται αναπαραγώγιμες κατασκευές σε όλες τις μηχανές της ομάδας. Για βιβλιοθήκες, το pubspec.lock δεν περιλαμβάνεται στο αποθετήριο, επειδή οι χρήστες της βιβλιοθήκης πρέπει να μπορούν να τη χρησιμοποιούν με διαφορετικές εκδόσεις εξαρτήσεων. Η εντολή flutter pub upgrade ενημερώνει όλες τις εξαρτήσεις σύμφωνα με τους περιορισμούς του pubspec.yaml, και η flutter pub outdated δείχνει ποια πακέτα μπορούν να ενημερωθούν.

Ρύθμιση κατασκευής και δημοσίευσης

Για τη δημοσίευση της εφαρμογής στο pub.dev, οι ρυθμίσεις καθορίζονται στην ενότητα publish_to. Η τιμή 'none' απαγορεύει την τυχαία δημοσίευση του πακέτου, κάτι που είναι σημαντικό για εσωτερικά ή μη δημόσια έργα. Εάν το publish_to λείπει, το pub προσπαθεί να δημοσιεύσει το πακέτο στο προεπιλεγμένο pub.dev, το οποίο μπορεί να οδηγήσει σε ανεπιθύμητη διαρροή κώδικα.

Η ενότητα flutter περιέχει παραμέτρους πλατφόρμας: generate για αυτόματη δημιουργία αρχείων πλατφόρμας και deferred-components για αρθρωτή φόρτωση λειτουργικότητας. Η παράμετρος generate: true κάνει το Flutter να δημιουργεί και να ενημερώνει αυτόματα έργα πλατφόρμας (iOS, Android, Web) κατά την προσθήκη νέων πλατφορμών μέσω του flutter create --platforms. Χωρίς αυτήν την παράμετρο, η δομή των φακέλων πλατφόρμας μπορεί να χάσει τον συγχρονισμό με το pubspec.yaml.

flutter:
  generate: true
  deferred-components:
    - name: photoEditor
      libraries:
        - package:photo_editor/library.dart

Η ενότητα platforms ορίζει τις πλατφόρμες-στόχους για το πακέτο. Για εφαρμογές, καθορίζεται αυτόματα κατά την προσθήκη υποστήριξης για μια συγκεκριμένη πλατφόρμα μέσω flutter create. Οι πλατφόρμες μπορούν να προστεθούν και να αφαιρεθούν χειροκίνητα μέσω επεξεργασίας του pubspec.yaml. Τα Deferred Components επιτρέπουν τη φόρτωση τμημάτων της εφαρμογής κατόπιν ζήτησης, μειώνοντας το μέγεθος εγκατάστασης — αυτό είναι ιδιαίτερα σημαντικό για παιχνίδια και εφαρμογές με μεγάλο όγκο σπάνια χρησιμοποιούμενου περιεχομένου.

Κατά τη δημοσίευση ενός πακέτου, το pub ελέγχει όλα τα πεδία του pubspec.yaml για συμμόρφωση με τις απαιτήσεις του αποθετηρίου. Η απουσία υποχρεωτικών πεδίων name, version και description οδηγεί σε απόρριψη της δημοσίευσης. Επιπλέον, ελέγχεται η εγκυρότητα της άδειας χρήσης, η ύπαρξη README.md και CHANGELOG.md. Πακέτα με σφάλματα του αναλυτή κώδικα (dart analyze) επίσης δεν περνούν την επικύρωση. Μετά την επιτυχή δημοσίευση, το πακέτο γίνεται διαθέσιμο στο pub.dev εντός λίγων λεπτών.

Η ενότητα dependency_overrides επιτρέπει την εξαναγκασμένη έκδοση ενός πακέτου, αγνοώντας περιορισμούς από μεταβατικές εξαρτήσεις. Αυτός είναι ένας ισχυρός αλλά επικίνδυνος μηχανισμός: σε περίπτωση λανθασμένης χρήσης μπορεί να οδηγήσει σε ασυμβατότητα βιβλιοθηκών. Χρησιμοποιήστε το dependency_overrides μόνο προσωρινά για επίλυση συγκρούσεων ή δοκιμή νέων εκδόσεων. Αφού διορθώσετε τις κύριες εξαρτήσεις, το override πρέπει να αφαιρεθεί για να μην διαταράξει τον γράφο εξαρτήσεων του έργου μακροπρόθεσμα.

Η ενότητα executables στο pubspec.yaml επιτρέπει τον καθορισμό εκτελέσιμων σεναρίων που το pub εγκαθιστά στο PATH κατά την ενεργοποίηση του πακέτου. Αυτό είναι χρήσιμο για εργαλεία CLI γραμμένα σε Dart, όπως το build_runner ή το dart_code_metrics. Η εντολή dart pub global activate εγκαθιστά το πακέτο καθολικά, καθιστώντας τα σενάρια που καθορίζονται στο executables διαθέσιμα από το τερματικό. Για εφαρμογές, τα executables συνήθως δεν χρησιμοποιούνται, καθώς το σημείο εισόδου καθορίζεται μέσω του main στο lib/main.dart.