pub: alapfogalmak, Dart csomagkezelő és pubspec.yaml

Mi az a pub?

pub (Package Universal Browser) — a Dart SDK-val együtt szállított beépített csomagkezelő. Kezeli a külső könyvtárakat, feloldja a verzióütközéseket, letölti a tranzitív függőségeket és helyileg gyorsítótárazza a csomagokat. A Flutter ökoszisztémában a pub a navigációs bővítmények, HTTP kliensek, állapotkezelők és más összetevők csatlakoztatásának fő eszköze.

A pub fő funkciói: függőségek telepítése a pub.dev nyilvántartásból, helyi elérési utak (path függőségek) és git tárolókból; verziók feloldása a szemantikus verziókezelés szabályai szerint; gyorsítótárazás a letöltött csomagok rendszermappában; közzététel saját csomagok nyilvános nyilvántartásba. Minden művelet elérhető a dart pub CLI parancson vagy azzal egyenértékű flutter pub paranccsal.

A pub architektúrája egy zárt függőségi gráfon alapul: a kezelő egy fát épít, amelyben minden csomag pontosan egyszer jelenik meg. Ha két könyvtár ugyanazon csomag különböző verzióit igényli, a pub megpróbál kompatibilis tartományt találni, vagy ütközési hibát jelez. Ez eltér az npm megközelítésétől, ahol ugyanazon csomag több verziója is megengedett a fa különböző csomópontjaiban.

A pubspec.yaml szerkezete

A pubspec.yaml fájl — bármely Dart vagy Flutter projekt központi konfigurációs fájlja. YAML formátumban íródik, és metaadatokat, függőségeket, fordítási konfigurációt és SDK korlátozásokat tartalmaz. Az alábbiakban egy tipikus példa látható Flutter alkalmazáshoz:

name: my_app
description: Példa Flutter-alkalmazásra
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/

A pubspec.yaml kulcsmezői: name — a csomag egyedi neve (csak latin betűk, aláhúzás, számok); description — rövid leírás (közzétételhez kötelező); version — szemantikus verzió opcionális build számmal a pluszjel után; environment — a Dart SDK és Flutter SDK minimális verziói; dependencies — az alkalmazás fő függőségei; dev_dependencies — csak fejlesztéshez és teszteléshez használt függőségek; flutter — a Flutter konfigurációs szakasza (assets, fonts, plugins).

A publish_to mező szabályozza a közzététel elérhetőségét: a none érték tiltja a közzétételt (jellemző alkalmazásokra), az alapértelmezett érték — https://pub.dev. A dependency_overrides mező lehetővé teszi egy csomag verziójának kényszerített felülírását ütközés esetén — óvatosan használandó, csak ideiglenes megoldásként.

Függőségek és típusaik

A pub négy típusú függőséget támogat, mindegyiket saját szintaxissal a pubspec.yaml-ban:

Nyilvántartásbeli (hosted)

Szabványos típus — a csomag a pub.dev nyilvántartásból vagy más kompatibilis nyilvántartásból töltődik le. Meg kell adni a csomag nevét és verzióját. Példa: http: ^1.1.0 letölti a legújabb kompatibilis verziót a >=1.1.0 és <2.0.0 tartományból a caret verziókezelés szabályai szerint.

SDK függőségek

A Flutter SDK vagy Dart SDK csatlakoztatására szolgál. Szintaxis: flutter: sdk: flutter. A csomag a Flutter SDK helyi telepítéséből származik, nem a nyilvántartásból. Az SDK függőségek nem verziószámozottak — verziójukat az aktuálisan telepített Flutter verzió határozza meg.

Útvonal (path)

Helyi mappára mutat a csomaggal. Hasznos könyvtár fejlesztésekor és közzététel nélküli teszteléskor. Szintaxis:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Az útvonal függőségek nem rögzítődnek a pubspec.lock-ban — minden frissítés újra feloldásra kerül a megadott útvonalról.

Git függőségek

Lehetővé teszik csomag közvetlen csatlakoztatását git tárolóból. Ágak, címkék és commitok támogatottak:

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

A Git függőségek kényelmesek forkokhoz, nem közzétett javításokhoz vagy Pull Request-eken való munkához. Javasolt konkrét címkét vagy commitot megadni ág helyett a váratlan változások elkerülése érdekében a fordítás során.

Verziókezelés és tartományok

A pub szigorúan betartja a Semantic Versioning 2.0-t: formátum MAJOR.MINOR.PATCH, ahol MAJOR — inkompatibilis változtatások, MINOR — visszafelé kompatibilis kiegészítések, PATCH — visszafelé kompatibilis javítások. E séma alapján a pub meghatározza a csomagok kompatibilitását és feloldja az ütközéseket.

A verziók megadásához három fő operátor használható a pubspec.yaml-ban:

• Caret (^) — ^1.2.3 egyenlő: >=1.2.3 és <2.0.0. A leggyakoribb operátor, mivel kompatibilitást feltételez a főverzión belül. 0 (nulla) főverziójú csomagoknál — ^0.1.2 jelentése >=0.1.2 és <0.2.0, ami megfelel a SemVer instabil verziókra vonatkozó szabályainak.
• Tilde (~) — ~1.2.3 egyenlő: >=1.2.3 és <1.3.0. Rögzíti a mellékverziót, csak patch frissítéseket engedélyez. Ritkábban használják, főleg ha ismert inkompatibilitás a mellékverzió szintjén.
• Pontos tartomány — >=1.2.0 <2.0.0 — explicit megadás, teljes ellenőrzést biztosít. Hasznos összetett korlátozásokhoz, például tranzitív függőségek több verziójának használatakor.

A dart pub get végrehajtása után a pub létrehozza a pubspec.lock fájlt, amely rögzíti az összes feloldott csomag (közvetlen és tranzitív) pontos verzióját. Ezt a fájlt be kell vonni a verziókezelő rendszerbe a reprodukálható fordítások biztosításához minden gépen. A dart pub upgrade végrehajtásakor a lock fájl frissül a legújabb kompatibilis verziókra a meghatározott korlátozásokon belül.

A dependency conflict hiba akkor lép fel, ha két csomag ugyanazon függőség nem átfedő tartományait igényli. A pub jelenti, mely csomagok ütköztek és miért. Megoldás: frissíteni az egyik ütköző csomagot kompatibilis verzióra, használni a dependency_overrides-t (ideiglenes intézkedés) vagy kicserélni a csomagot alternatívára.

A pub alapvető parancsai

A pub minden művelete egységes CLI felületen keresztül történik. A Dart SDK-ban a dart pub parancs, a Flutter SDK-ban az azzal egyenértékű flutter pub használatos (kiegészítve a Flutter SDK függőségek és bővítmények figyelembevételével). Az alábbiakban a kulcsparancsok találhatók:

• dart pub get — letölti a pubspec.yaml-ban megadott összes függőséget, feloldja a verziókat és létrehozza/frissíti a pubspec.lock-ot. A projekt első klónozásakor vagy a függőségek módosítása után hajtódik végre.
• dart pub upgrade — frissíti az összes függőséget a legújabb verziókra a pubspec.yaml korlátain belül és felülírja a pubspec.lock-ot. Egyedi csomag is frissíthető: dart pub upgrade http.
• dart pub add <package> — új függőséget ad a pubspec.yaml-hoz és azonnal végrehajtja a pub get-et. Példa: dart pub add dio hozzáadja a dio csomag legújabb verzióját.
• dart pub remove <package> — eltávolítja a függőséget a pubspec.yaml-ból és újraindítja a gráf feloldását.
• dart pub cache repair — újratölti az összes gyorsítótárazott csomagot. Segít a helyi gyorsítótár sérülése vagy ellenőrzőösszeg hibák esetén.
• dart pub deps — megjeleníti a függőségi fát olvasható szöveges formátumban. Hasznos a tranzitív függőségek elemzéséhez és ismétlődések kereséséhez.
• dart pub publish — közzéteszi az aktuális csomagot a pub.dev-en. Közzététel előtt ellenőrzi a pubspec.yaml helyességét, a licencet és a leírást.
• dart pub outdated — megjeleníti az elavult függőségek listáját az aktuális, kívánt és legújabb elérhető verzióval. Analóg az npm outdated-del.

Minden parancs rövidített formában is elérhető: dart pub get mint dart pub g (nem minden rövidítés). Flutter projektekben a flutter előtag kerül a pub parancsok elé: flutter pub get, flutter pub add és így tovább. A Flutter verzió emellett ellenőrzi a bővítmények kompatibilitását a célplatformmal.

Közzététel a pub.dev-en

pub.dev — a Dart és Flutter ökoszisztéma központi csomagnyilvántartása. 2025 januárjában több mint 50 000 csomagot tettek közzé itt, összesen több mint 10 milliárd letöltéssel. Minden csomagnak van oldala leírással, dokumentációval, népszerűségi értékelésekkel (Popularity), Pub Points pontszámokkal és verziókkal.

Pub Points — automatikus csomagminőség-értékelő rendszer 0-tól 130 pontig. Figyelembe veszi: licenc meglétét, leírást, példákat, kompatibilitást a legújabb stabil Dart verzióval, sérülékenységek hiányát, tesztlefedettséget, formázás helyességét. A magas pontszám növeli a csomag láthatóságát a keresésben és a felhasználók bizalmát.

A közzétételi folyamat több lépésből áll:

1. Ellenőrizze a pubspec.yaml-t: name, description, version, license megléte (ajánlott SPDX azonosító megadása, pl. MIT).
2. Futtassa a dart pub publish --dry-run-t — a közzététel szimulációja szerverre küldés nélkül, megjeleníti a csomagba kerülő összes fájlt és a lehetséges hibákat.
3. Hitelesítse magát Google fiókkal az első közzétételkor: a dart pub publish megnyitja a böngészőt OAuth hitelesítéshez.
4. Erősítse meg a közzétételt a terminálban. Sikeres küldés után a csomag néhány percen belül megjelenik a pub.dev-en.

Fontos szabályok: csak egyedi nevű csomagok tehetők közzé; egyszer közzétett verzió nem törölhető (csak elrejthető — dart pub unpublish — 7 napon belül); nagy frissítéseknél követni kell a Semantic Versioning szabályait, a nyilvános API-t nem szabad megtörni a főverzió megváltoztatása nélkül.