pub: klíčové pojmy, správce balíčků Dart a pubspec.yaml

Co je pub?

pub (Package Universal Browser) — vestavěný správce balíčků, který je dodáván s Dart SDK. Spravuje externí knihovny, řeší konflikty verzí, stahuje tranzitivní závislosti a ukládá balíčky do lokální mezipaměti. V ekosystému Flutter se pub používá jako hlavní nástroj pro připojení navigačních pluginů, HTTP klientů, správců stavu a dalších komponent.

Hlavní funkce pub zahrnují: instalaci závislostí z registru pub.dev, lokálních cest (path závislosti) a git úložišť; řešení verzí podle pravidel sémantického verzování; ukládání do mezipaměti stažených balíčků v systémovém adresáři; publikování vlastních balíčků do otevřeného registru. Všechny tyto operace jsou dostupné prostřednictvím CLI příkazu dart pub nebo ekvivalentního flutter pub.

Architektura pub je založena na uzavřeném grafu závislostí: správce vytváří strom, ve kterém se každý balíček vyskytuje právě jednou. Pokud dvě knihovny vyžadují různé verze stejného balíčku, pub se pokusí najít kompatibilní rozsah nebo nahlásí chybu konfliktu. To se liší od přístupu npm, kde jsou povoleny více verzí stejného balíčku v různých uzlech stromu.

Struktura pubspec.yaml

Soubor pubspec.yaml — centrální konfigurační soubor každého projektu Dart nebo Flutter. Je napsán ve formátu YAML a obsahuje metadata, závislosti, konfiguraci sestavení a omezení SDK. Níže je uveden typický příklad pro Flutter aplikaci:

name: my_app
description: Příklad Flutter aplikace
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/

Klíčová pole pubspec.yaml: name — jedinečný název balíčku (pouze latinka, podtržítko, číslice); description — stručný popis (povinný pro publikování); version — sémantická verze s volitelným build číslem za plusem; environment — minimální verze Dart SDK a Flutter SDK; dependencies — hlavní závislosti aplikace; dev_dependencies — závislosti pouze pro vývoj a testování; flutter — sekce konfigurace Flutter (assets, fonts, plugins).

Pole publish_to řídí dostupnost publikování: hodnota none zakazuje publikování (typické pro aplikace), výchozí hodnota — https://pub.dev. Pole dependency_overrides umožňuje vynutit přepsání verze balíčku v konfliktní situaci — používat opatrně, pouze jako dočasné řešení.

Závislosti a jejich typy

pub podporuje čtyři typy závislostí, každý s vlastní syntaxí v pubspec.yaml:

Registrové (hosted)

Standardní typ — balíček se stahuje z registru pub.dev nebo jiného kompatibilního registru. Uvádí se název balíčku a verze. Příklad: http: ^1.1.0 stáhne nejnovější kompatibilní verzi z rozsahu >=1.1.0 a <2.0.0 podle pravidel caret verzování.

Závislosti SDK

Používají se pro připojení Flutter SDK nebo Dart SDK. Syntaxe: flutter: sdk: flutter. Balíček se bere z lokální instalace Flutter SDK, nikoli z registru. Závislosti SDK nejsou verzovány — jejich verze je určena aktuálně nainstalovanou verzí Flutter.

Cestové (path)

Odkazují na lokální adresář s balíčkem. Užitečné při vývoji knihovny a testování bez publikování. Syntaxe:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Cestové závislosti nejsou fixovány v pubspec.lock — každá aktualizace je znovu vyřešena z uvedené cesty.

Git závislosti

Umožňují připojit balíček přímo z git úložiště. Jsou podporovány větve, tagy a commity:

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

Git závislosti jsou vhodné forky, nepublikované opravy nebo práci na Pull Request. Doporučuje se uvádět konkrétní tag nebo commit místo větve, aby se předešlo neočekávaným změnám při sestavení.

Verzování a rozsahy

pub důsledně dodržuje Semantic Versioning 2.0: formát MAJOR.MINOR.PATCH, kde MAJOR — nekompatibilní změny, MINOR — zpětně kompatibilní doplňky, PATCH — zpětně kompatibilní opravy. Na základě tohoto schématu pub určuje kompatibilitu balíčků a řeší konflikty.

Pro zadávání verzí se používají tři hlavní operátory v pubspec.yaml:

• Caret (^) — ^1.2.3 je ekvivalent >=1.2.3 a <2.0.0. Nejrozšířenější operátor, protože předpokládá kompatibilitu v rámci hlavní verze. Pro balíčky s hlavní verzí 0 (nula) — ^0.1.2 znamená >=0.1.2 a <0.2.0, což odpovídá pravidlům SemVer pro nestabilní verze.
• Tilda (~) — ~1.2.3 je ekvivalent >=1.2.3 a <1.3.0. Fixuje vedlejší verzi, povoluje pouze patch aktualizace. Používá se méně často, hlavně když je známa nekompatibilita na úrovni vedlejší verze.
• Přesný rozsah — >=1.2.0 <2.0.0 — explicitní zápis poskytující plnou kontrolu. Užitečný pro složitá omezení, například při použití více verzí tranzitivních závislostí.

Po provedení dart pub get pub vygeneruje soubor pubspec.lock, který fixuje přesné verze všech vyřešených balíčků (přímých i tranzitivních). Tento soubor musí být zahrnut do systému správy verzí pro zajištění reprodukovatelných sestavení na všech strojích. Při provedení dart pub upgrade je lock soubor aktualizován na nejnovější kompatibilní verze v rámci stanovených omezení.

Chyba dependency conflict nastane, když dva balíčky vyžadují nepřekrývající se rozsahy stejné závislosti. pub hlásí, které balíčky se dostaly do konfliktu a z jakého důvodu. Řešení: aktualizovat jeden z konfliktních balíčků na kompatibilní verzi, použít dependency_overrides (dočasné opatření) nebo nahradit balíček alternativou.

Základní příkazy pub

Všechny operace pub se provádějí prostřednictvím jednotného CLI rozhraní. V Dart SDK se používá příkaz dart pub, ve Flutter SDK — ekvivalentní flutter pub (navíc zohledňuje závislosti Flutter SDK a pluginy). Níže jsou uvedeny klíčové příkazy:

• dart pub get — stahuje všechny závislosti uvedené v pubspec.yaml, řeší verze a vytváří/aktualizuje pubspec.lock. Provádí se při prvním klonování projektu nebo po změně závislostí.
• dart pub upgrade — aktualizuje všechny závislosti na nejnovější verze v rámci omezení pubspec.yaml a přepíše pubspec.lock. Lze aktualizovat jednotlivý balíček: dart pub upgrade http.
• dart pub add <package> — přidá novou závislost do pubspec.yaml a okamžitě provede pub get. Příklad: dart pub add dio přidá nejnovější verzi balíčku dio.
• dart pub remove <package> — odstraní závislost z pubspec.yaml a restartuje řešení grafu.
• dart pub cache repair — znovu načte všechny balíčky v mezipaměti. Pomáhá při poškození lokální mezipaměti nebo chybách kontrolních součtů.
• dart pub deps — zobrazí strom závislostí v čitelném textovém formátu. Užitečné pro analýzu tranzitivních závislostí a hledání duplicit.
• dart pub publish — publikuje aktuální balíček na pub.dev. Před publikováním zkontroluje správnost pubspec.yaml, licenci a popis.
• dart pub outdated — zobrazí seznam zastaralých závislostí s aktuální, požadovanou a nejnovější dostupnou verzí. Obdoba npm outdated.

Všechny příkazy jsou k dispozici také ve zkrácené podobě: dart pub get jako dart pub g (ne všechny zkratky). Ve Flutter projektech se před příkazy pub přidává prefix flutter: flutter pub get, flutter pub add a tak dále. Flutter verze navíc kontroluje kompatibilitu pluginů s cílovou platformou.

Publikování na pub.dev

pub.dev — centrální registr balíčků ekosystému Dart a Flutter. K lednu 2025 zde bylo publikováno více než 50 000 balíčků, celkem stažených přes 10 miliardkrát. Každý balíček má stránku s popisem, dokumentací, hodnocením popularity (Popularity), body Pub Points a verzemi.

Pub Points — automatický systém hodnocení kvality balíčku od 0 do 130 bodů. Zohledňuje se: existence licence, popis, příklady, kompatibilita s nejnovější stabilní verzí Dart, absence zranitelností, pokrytí testy, správnost formátování. Vysoké skóre zvyšuje viditelnost balíčku ve vyhledávání a důvěru uživatelů.

Proces publikování zahrnuje několik kroků:

1. Zkontrolujte pubspec.yaml: existenci name, description, version, license (doporučuje se uvést SPDX identifikátor, např. MIT).
2. Spusťte dart pub publish --dry-run — simulace publikování bez odeslání na server, zobrazí všechny soubory, které budou zahrnuty do balíčku, a možné chyby.
3. Autorizujte se přes Google účet při prvním publikování: dart pub publish otevře prohlížeč pro OAuth autentizaci.
4. Potvrďte publikování v terminálu. Po úspěšném odeslání se balíček objeví na pub.dev během několika minut.

Důležitá pravidla: lze publikovat pouze balíčky s jedinečným názvem; jednou publikovanou verzi nelze odstranit (lze pouze skrýt — dart pub unpublish — do 7 dnů); pro velké aktualizace je třeba dodržovat pravidla Semantic Versioning, nelámat veřejné API bez změny hlavní verze.