pub: kluczowe pojęcia, menedżer pakietów Dart i pubspec.yaml

Czym jest pub?

pub (Package Universal Browser) — wbudowany menedżer pakietów, który jest dostarczany wraz z Dart SDK. Zarządza zewnętrznymi bibliotekami, rozwiązuje konflikty wersji, pobiera zależności przechodnie i przechowuje pakiety w lokalnym cache. W ekosystemie Flutter pub jest używany jako główne narzędzie do podłączania pluginów nawigacji, klientów HTTP, menedżerów stanu i innych komponentów.

Główne funkcje pub obejmują: instalację zależności z rejestru pub.dev, lokalnych ścieżek (path-zależności) i repozytoriów git; rozwiązywanie wersji według zasad semantycznego wersjonowania; buforowanie pobranych pakietów w katalogu systemowym; publikację własnych pakietów w otwartym rejestrze. Wszystkie te operacje są dostępne przez polecenie CLI dart pub lub równoważne flutter pub.

Architektura pub opiera się na domkniętym grafie zależności: menedżer buduje drzewo, w którym każdy pakiet występuje dokładnie raz. Jeśli dwie biblioteki wymagają różnych wersji tego samego pakietu, pub próbuje znaleźć zgodny zakres albo zgłasza błąd konfliktu. Różni się to od podejścia npm, gdzie dopuszczalne są wielokrotne wersje tego samego pakietu w różnych węzłach drzewa.

Struktura pubspec.yaml

Plik pubspec.yaml — centralny plik konfiguracyjny każdego projektu Dart lub Flutter. Jest napisany w formacie YAML i zawiera metadane, zależności, konfigurację kompilacji oraz ograniczenia SDK. Poniżej znajduje się typowy przykład dla aplikacji Flutter:

name: my_app
description: Przykład aplikacji 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/

Kluczowe pola pubspec.yaml: name — unikalna nazwa pakietu (tylko łacińskie litery, podkreślenie, cyfry); description — krótki opis (wymagany do publikacji); version — wersja semantyczna z opcjonalnym numerem kompilacji po plusie; environment — minimalne wersje Dart SDK i Flutter SDK; dependencies — główne zależności aplikacji; dev_dependencies — zależności tylko do rozwoju i testów; flutter — sekcja konfiguracji Flutter (assets, fonts, plugins).

Pole publish_to kontroluje dostępność publikacji: wartość none zabrania publikacji (typowe dla aplikacji), wartość domyślna — https://pub.dev. Pole dependency_overrides pozwala wymusić wersję pakietu w sytuacji konfliktu — używać ostrożnie, tylko tymczasowo.

Zależności i ich rodzaje

pub obsługuje cztery typy zależności, każdy z własną składnią w pubspec.yaml:

Rejestrowe (hosted)

Standardowy typ — pakiet pobierany z rejestru pub.dev lub innego zgodnego rejestru. Podaje się nazwę pakietu i wersję. Przykład: http: ^1.1.0 pobierze najnowszą zgodną wersję z zakresu >=1.1.0 i <2.0.0 według zasad caret-wersjonowania.

Zależności SDK

Używane do podłączenia Flutter SDK lub Dart SDK. Składnia: flutter: sdk: flutter. Pakiet pochodzi z lokalnej instalacji Flutter SDK, a nie z rejestru. Zależności SDK nie są wersjonowane — ich wersja jest określana przez aktualnie zainstalowaną wersję Flutter.

Ścieżkowe (path)

Wskazują lokalny katalog z pakietem. Przydatne przy opracowywaniu biblioteki i testowaniu bez publikacji. Składnia:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Zależności ścieżkowe nie są zapisywane w pubspec.lock — każda aktualizacja jest ponownie rozwiązywana ze wskazanej ścieżki.

Zależności Git

Pozwalają podłączyć pakiet bezpośrednio z repozytorium git. Obsługiwane są gałęzie, tagi i commity:

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

Zależności Git są wygodne dla forków, nieopublikowanych poprawek lub pracy nad Pull Request. Zaleca się wskazywanie konkretnego tagu lub commitu zamiast gałęzi, aby uniknąć nieoczekiwanych zmian przy kompilacji.

Wersjonowanie i zakresy

pub ściśle przestrzega Semantic Versioning 2.0: format MAJOR.MINOR.PATCH, gdzie MAJOR — niekompatybilne zmiany, MINOR — wstecznie kompatybilne dodatki, PATCH — wstecznie kompatybilne poprawki. Na podstawie tego schematu pub określa zgodność pakietów i rozwiązuje konflikty.

Do określania wersji używane są trzy główne operatory w pubspec.yaml:

• Caret (^) — ^1.2.3 odpowiada >=1.2.3 i <2.0.0. Najczęściej używany operator, ponieważ zakłada zgodność w obrębie głównej wersji. Dla pakietów z główną wersją 0 (zero) — ^0.1.2 oznacza >=0.1.2 i <0.2.0, co odpowiada zasadom SemVer dla niestabilnych wersji.
• Tylda (~) — ~1.2.3 odpowiada >=1.2.3 i <1.3.0. Ustala wersję pomocniczą, zezwalając tylko na poprawki (patch). Rzadziej używany, głównie gdy znana jest niekompatybilność na poziomie wersji pomocniczej.
• Dokładny zakres — >=1.2.0 <2.0.0 — jawny zapis dający pełną kontrolę. Przydatny dla złożonych ograniczeń, na przykład przy użyciu wielu wersji zależności przechodnich.

Po wykonaniu dart pub get pub generuje plik pubspec.lock, który ustala dokładne wersje wszystkich rozwiązanych pakietów (bezpośrednich i przechodnich). Ten plik należy dołączyć do systemu kontroli wersji, aby zapewnić powtarzalne kompilacje na wszystkich maszynach. Po wykonaniu dart pub upgrade plik lock jest aktualizowany do najnowszych zgodnych wersji w ramach określonych ograniczeń.

Błąd dependency conflict występuje, gdy dwa pakiety wymagają nienakładających się zakresów tej samej zależności. pub informuje, które pakiety weszły w konflikt i z jakiego powodu. Rozwiązanie: zaktualizować jeden z konfliktujących pakietów do zgodnej wersji, użyć dependency_overrides (środek tymczasowy) lub zmienić pakiet na alternatywny.

Podstawowe polecenia pub

Wszystkie operacje pub są wykonywane przez jednolity interfejs CLI. W Dart SDK używane jest polecenie dart pub, w Flutter SDK — równoważne flutter pub (dodatkowo uwzględnia zależności Flutter SDK i wtyczki). Poniżej znajdują się kluczowe polecenia:

• dart pub get — pobiera wszystkie zależności określone w pubspec.yaml, rozwiązuje wersje i tworzy/aktualizuje pubspec.lock. Wykonywane przy pierwszym klonowaniu projektu lub po zmianie zależności.
• dart pub upgrade — aktualizuje wszystkie zależności do najnowszych wersji w ramach ograniczeń pubspec.yaml i nadpisuje pubspec.lock. Można zaktualizować pojedynczy pakiet: dart pub upgrade http.
• dart pub add <package> — dodaje nową zależność w pubspec.yaml i natychmiast wykonuje pub get. Przykład: dart pub add dio doda najnowszą wersję pakietu dio.
• dart pub remove <package> — usuwa zależność z pubspec.yaml i ponownie rozwiązuje graf zależności.
• dart pub cache repair — ponownie ładuje wszystkie buforowane pakiety. Pomaga przy uszkodzeniu lokalnego cache lub błędach sum kontrolnych.
• dart pub deps — wyświetla drzewo zależności w czytelnym formacie tekstowym. Przydatne do analizy zależności przechodnich i znajdowania duplikacji.
• dart pub publish — publikuje bieżący pakiet na pub.dev. Przed publikacją sprawdza poprawność pubspec.yaml, licencję i opis.
• dart pub outdated — pokazuje listę przestarzałych zależności z bieżącą, pożądaną i najnowszą dostępną wersją. Odpowiednik npm outdated.

Wszystkie polecenia są dostępne również w skróconej formie dart pub get jako dart pub g (nie wszystkie skróty). W projektach Flutter przed poleceniami pub dodawany jest prefiks flutter: flutter pub get, flutter pub add i tak dalej. Wersja Flutter dodatkowo sprawdza zgodność wtyczek z platformą docelową.

Publikacja na pub.dev

pub.dev — centralny rejestr pakietów ekosystemu Dart i Flutter. Na styczeń 2025 roku opublikowano tam ponad 50 000 pakietów, łącznie pobranych ponad 10 miliardów razy. Każdy pakiet ma stronę z opisem, dokumentacją, ocenami popularności (Popularity), punktami Pub Points i wersjami.

Pub Points — automatyczny system oceny jakości pakietu od 0 do 130 punktów. Uwzględnia: obecność licencji, opis, przykłady, zgodność z najnowszą stabilną wersją Dart, brak podatności, pokrycie testami, poprawność formatowania. Wysoki wynik zwiększa widoczność pakietu w wyszukiwaniu i zaufanie użytkowników.

Proces publikacji obejmuje kilka kroków:

1. Sprawdzić pubspec.yaml: obecność name, description, version, license (zaleca się podanie identyfikatora SPDX, np. MIT).
2. Uruchomić dart pub publish --dry-run — symulacja publikacji bez wysyłania na serwer, wyświetla wszystkie pliki, które zostaną dołączone do pakietu, oraz możliwe błędy.
3. Zautoryzować się przez konto Google przy pierwszej publikacji: dart pub publish otworzy przeglądarkę do uwierzytelniania OAuth.
4. Potwierdzić publikację w terminalu. Po pomyślnym wysłaniu pakiet pojawia się na pub.dev w ciągu kilku minut.

Ważne zasady: publikować można tylko pakiety z unikalną nazwą; raz opublikowanej wersji nie można usunąć (można tylko ukryć — dart pub unpublish — w ciągu 7 dni); w przypadku dużych aktualizacji należy przestrzegać zasad Semantic Versioning, nie łamać publicznego API bez zmiany głównej wersji.