pub: concepte cheie, managerul de pachete Dart și pubspec.yaml

Ce este pub?

pub (Package Universal Browser) — managerul de pachete încorporat care vine împreună cu Dart SDK. Acesta gestionează bibliotecile externe, rezolvă conflictele de versiuni, descarcă dependințe tranzitive și stochează pachetele în cache local. În ecosistemul Flutter, pub este utilizat ca instrument principal pentru conectarea pluginurilor de navigare, clienților HTTP, managerilor de stare și altor componente.

Funcțiile principale ale pub includ: instalarea dependințelor din registrul pub.dev, căi locale (dependințe path) și repository git; rezolvarea versiunilor conform regulilor de versionare semantică; stocarea în cache a pachetelor descărcate în directorul de sistem; publicarea propriilor pachete în registrul deschis. Toate aceste operațiuni sunt disponibile prin comanda CLI dart pub sau echivalenta flutter pub.

Arhitectura pub se bazează pe un graf închis de dependințe: managerul construiește un arbore în care fiecare pachet apare exact o dată. Dacă două biblioteci necesită versiuni diferite ale aceluiași pachet, pub încearcă să găsească un interval compatibil sau raportează o eroare de conflict. Aceasta diferă de abordarea npm, unde sunt permise versiuni multiple ale aceluiași pachet în diferite noduri ale arborelui.

Structura pubspec.yaml

Fișierul pubspec.yaml — fișierul central de configurare al oricărui proiect Dart sau Flutter. Este scris în format YAML și conține metadate, dependințe, configurarea construcției și restricții SDK. Mai jos este un exemplu tipic pentru o aplicație Flutter:

name: my_app
description: Exemplu de aplicație Flutter
version: 1.0.0+1
publish_to: none

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter
  http: ^1.1.0
  provider: ^6.0.5
  shared_preferences: ^2.2.0
  path_provider: ^2.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0
  mockito: ^5.4.3

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/fonts/

Câmpurile cheie ale pubspec.yaml: name — numele unic al pachetului (doar litere latine, underscore, cifre); description — descriere scurtă (obligatorie pentru publicare); version — versiune semantică cu număr opțional de build după semnul plus; environment — versiunile minime ale Dart SDK și Flutter SDK; dependencies — dependințele principale ale aplicației; dev_dependencies — dependințe doar pentru dezvoltare și testare; flutter — secțiunea de configurare Flutter (assets, fonts, plugins).

Câmpul publish_to controlează disponibilitatea publicării: valoarea none interzice publicarea (tipic pentru aplicații), valoarea implicită — https://pub.dev. Câmpul dependency_overrides permite suprascrierea forțată a versiunii unui pachet în situații de conflict — de utilizat cu prudență, doar ca soluție temporară.

Dependințe și tipurile lor

pub suportă patru tipuri de dependințe, fiecare specificat cu propria sintaxă în pubspec.yaml:

Registru (hosted)

Tip standard — pachetul este descărcat din registrul pub.dev sau alt registru compatibil. Se specifică numele pachetului și versiunea. Exemplu: http: ^1.1.0 va descărca ultima versiune compatibilă din intervalul >=1.1.0 și <2.0.0 conform regulilor de versionare caret.

Dependințe SDK

Utilizate pentru conectarea Flutter SDK sau Dart SDK. Sintaxa: flutter: sdk: flutter. Pachetul este preluat din instalarea locală a Flutter SDK, nu din registru. Dependințele SDK nu sunt versionate — versiunea lor este determinată de versiunea curentă instalată a Flutter.

Path (cale)

Indică un director local cu pachetul. Util la dezvoltarea bibliotecilor și testarea fără publicare. Sintaxa:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Dependințele path nu sunt fixate în pubspec.lock — fiecare actualizare este rezolvată din nou din calea specificată.

Dependințe Git

Permit conectarea unui pachet direct dintr-un repository git. Sunt suportate ramuri, taguri și commituri:

dependencies:
  my_git_lib:
    git:
      url: https://github.com/user/my_git_lib.git
      ref: main

Dependințele Git sunt convenabile pentru forkuri, remedieri nepublicate sau lucru la Pull Request. Se recomandă specificarea unui tag sau commit concret în locul unei ramuri, pentru a evita schimbările neașteptate la construcție.

Versionare și intervale

pub respectă strict Semantic Versioning 2.0: formatul MAJOR.MINOR.PATCH, unde MAJOR — schimbări incompatibile, MINOR — adăugiri compatibile cu versiunile anterioare, PATCH — remedieri compatibile cu versiunile anterioare. Pe baza acestei scheme, pub determină compatibilitatea pachetelor și rezolvă conflictele.

Pentru specificarea versiunilor se folosesc trei operatori principali în pubspec.yaml:

• Caret (^) — ^1.2.3 este echivalent cu >=1.2.3 și <2.0.0. Cel mai răspândit operator, deoarece presupune compatibilitate în cadrul versiunii majore. Pentru pachetele cu versiunea majoră 0 (zero) — ^0.1.2 înseamnă >=0.1.2 și <0.2.0, ceea ce corespunde regulilor SemVer pentru versiuni instabile.
• Tildă (~) — ~1.2.3 este echivalent cu >=1.2.3 și <1.3.0. Fixează versiunea minoră, permițând doar actualizări de patch. Se folosește mai rar, în principal când se cunoaște incompatibilitatea la nivelul versiunii minore.
• Interval exact — >=1.2.0 <2.0.0 — scriere explicită care oferă control complet. Utilă pentru restricții complexe, de exemplu când se folosesc mai multe versiuni de dependințe tranzitive.

După executarea dart pub get, pub generează fișierul pubspec.lock, care fixează versiunile exacte ale tuturor pachetelor rezolvate (directe și tranzitive). Acest fișier trebuie inclus în sistemul de control al versiunilor pentru a asigura construcții reproductibile pe toate mașinile. La executarea dart pub upgrade, fișierul lock este actualizat la cele mai recente versiuni compatibile în cadrul restricțiilor specificate.

Eroarea dependency conflict apare când două pachete necesită intervale care nu se suprapun pentru aceeași dependință. pub raportează care pachete au intrat în conflict și din ce motiv. Soluție: actualizați unul dintre pachetele în conflict la o versiune compatibilă, utilizați dependency_overrides (măsură temporară) sau înlocuiți pachetul cu o alternativă.

Comenzile de bază pub

Toate operațiunile pub se execută printr-o interfață CLI unică. În Dart SDK se folosește comanda dart pub, în Flutter SDK — echivalenta flutter pub (suplimentar ia în considerare dependințele Flutter SDK și pluginurile). Mai jos sunt comenzile cheie:

• dart pub get — descarcă toate dependințele specificate în pubspec.yaml, rezolvă versiunile și creează/actualizează pubspec.lock. Se execută la prima clonare a proiectului sau după modificarea dependințelor.
• dart pub upgrade — actualizează toate dependințele la cele mai recente versiuni în cadrul restricțiilor pubspec.yaml și suprascrie pubspec.lock. Se poate actualiza un singur pachet: dart pub upgrade http.
• dart pub add <package> — adaugă o nouă dependință în pubspec.yaml și execută imediat pub get. Exemplu: dart pub add dio va adăuga ultima versiune a pachetului dio.
• dart pub remove <package> — elimină dependința din pubspec.yaml și repornește rezolvarea grafului.
• dart pub cache repair — reîncarcă toate pachetele stocate în cache. Ajută la deteriorarea cache-ului local sau erori de sume de control.
• dart pub deps — afișează arborele de dependințe într-un format text convenabil. Util pentru analiza dependințelor tranzitive și găsirea duplicărilor.
• dart pub publish — publică pachetul curent pe pub.dev. Înainte de publicare, verifică corectitudinea pubspec.yaml, licența și descrierea.
• dart pub outdated — arată lista dependințelor învechite cu versiunea curentă, dorită și ultima versiune disponibilă. Analog cu npm outdated.

Toate comenzile sunt disponibile și în formă scurtă: dart pub get ca dart pub g (nu toate scurtările). În proiectele Flutter, în fața comenzilor pub se adaugă prefixul flutter: flutter pub get, flutter pub add și așa mai departe. Versiunea Flutter verifică suplimentar compatibilitatea pluginurilor cu platforma țintă.

Publicare pe pub.dev

pub.dev — registrul central de pachete al ecosistemului Dart și Flutter. În ianuarie 2025, acolo erau publicate peste 50 000 de pachete, descărcate în total de peste 10 miliarde de ori. Fiecare pachet are o pagină cu descriere, documentație, evaluări de popularitate (Popularity), puncte Pub Points și versiuni.

Pub Points — sistem automat de evaluare a calității pachetului de la 0 la 130 de puncte. Se iau în considerare: existența licenței, descrierea, exemplele, compatibilitatea cu ultima versiune stabilă Dart, absența vulnerabilităților, acoperirea cu teste, corectitudinea formatării. Un scor ridicat crește vizibilitatea pachetului în căutare și încrederea utilizatorilor.

Procesul de publicare include mai mulți pași:

1. Verificați pubspec.yaml: existența name, description, version, license (se recomandă specificarea identificatorului SPDX, de exemplu MIT).
2. Rulați dart pub publish --dry-run — simulare a publicării fără trimitere pe server, afișează toate fișierele care vor fi incluse în pachet și posibilele erori.
3. Autorizați-vă prin cont Google la prima publicare: dart pub publish va deschide browserul pentru autentificare OAuth.
4. Confirmați publicarea în terminal. După trimiterea cu succes, pachetul apare pe pub.dev în câteva minute.

Reguli importante: se pot publica doar pachete cu nume unic; o versiune odată publicată nu poate fi ștearsă (poate fi doar ascunsă — dart pub unpublish — în termen de 7 zile); pentru actualizări majore, trebuie urmate regulile Semantic Versioning, fără a rupe API-ul public fără schimbarea versiunii majore.