pubspec.yaml — mi ez, szerkezete és függőségek konfigurálása Flutterben

Mi az a pubspec.yaml

pubspec.yaml — egy YAML formátumú manifest fájl, amelyet a pub csomagkezelő használ Dart és Flutter projektek kezelésére. A projekt gyökerében található, és minden flutter pub get parancsnál feldolgozásra kerül. Ellentétben más platformokkal, ahol a konfiguráció több fájlra van szétszórva, a Flutter egy központosított manifestet használ minden igényhez.

A fájl metaadatokat tartalmaz: projektnév, leírás, verzió, szerző. Ezek az adatok a csomag pub.dev-en történő publikálásakor és az App Store és Google Play számára történő alkalmazásépítéskor használatosak. A description mező megjelenik a csomagkeresési eredményekben, ezért informatívnak kell lennie, és tartalmaznia kell kulcsszavakat, amelyek alapján más fejlesztők megtalálhatják a könyvtárat.

Helyes pubspec.yaml nélkül a Flutter projekt nem építhető fel. Szintaxis hibák vagy helytelen behúzások azonnali fordítási hibához vezetnek Error on line X üzenettel. A YAML érzékeny a szóközökre: egy extra szóköz megváltoztatja az adatstruktúrát, a tabulátor pedig szintaxis hibát okoz. Ezért a pubspec.yaml kézi szerkesztésekor fontos YAML szintaxis kiemelést támogató szerkesztőt használni, például a VS Code-ot a hivatalos Flutter bővítménnyel.

A pubspec.yaml fő szekciói

A pubspec.yaml kötelező és opcionális szekciókból áll. Minden szekció a projekt konfigurációjának egy adott aspektusáért felelős. A szekciók sorrendje nem fontos, de a közösségi konvenció szerint a hierarchia betartandó: metaadatok, környezet, függőségek, erőforrások, platformok.

name és description

A name mező a csomag egyedi azonosítóját állítja be snake_case formátumban, csak kis latin betűkből, számokból és aláhúzásokból állva. A description mező — a projekt rövid leírása legfeljebb 180 karakterig, kötelező a pub.dev-en történő publikáláshoz. A leírásnak magyaráznia kell a csomag célját, anélkül hogy megismételné a nevet, és kulcsszavakat kell tartalmaznia a repository keresési optimalizálásához.

name: my_flutter_app
description: Feladatkezelő alkalmazás Flutterrel
publish_to: 'none'

version és environment

A version mező szemantikus verziókezelést használ: major.minor.patch, opcionális építési számmal a pluszjel után (1.0.0+1). Az environment szekció beállítja a Dart és Flutter SDK minimális és maximális verzióját a kompatibilitás garantálása érdekében. Ha az SDK új verziója olyan kritikus változásokat tartalmaz, amelyek nem kompatibilisek a projekt kódjával, a fordítás megszakad egy érthető hibaüzenettel.

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

dependencies és dev_dependencies

A dependencies szekció felsorolja az alkalmazás futásához szükséges csomagokat. A dev_dependencies szekció teszteléshez, kódgeneráláshoz és fejlesztéshez tartalmaz csomagokat — ezek nem kerülnek be a kiadási buildbe. A függőségek szétválasztása kritikus a teljesítmény szempontjából: minden csomag a dependencies-ben növeli a végső APK vagy IPA méretét, valamint az alkalmazás indítási idejét a további könyvtárak inicializálása miatt.

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

Assetek és betűtípusok konfigurálása

A flutter szekció alszekciókat tartalmaz az erőforrások, betűtípusok és platformparaméterek konfigurálásához. Az erőforrások egy paths tömbön keresztül csatlakoznak, konkrét fájlok vagy teljes könyvtárak megadásával. Minden elérési út a projekt gyökeréhez viszonyítva van megadva, nem a pubspec.yaml-hoz viszonyítva. Ez egy fontos részlet, amely gyakran zavart okoz a kezdő Flutter fejlesztőknél.

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

Az assetek pubspec.yaml-en keresztüli csatlakoztatása a fájlokat az AssetBundle-on keresztül teszi elérhetővé futásidőben. Ez működik képekhez, JSON-hoz, szöveges fájlokhoz és bármilyen más erőforráshoz. A Flutter automatikusan támogatja a különböző képernyőfelbontásokat: ha elhelyezi az images/2x/ és images/3x/ mappákat, a Flutter kiválasztja a kép megfelelő verzióját az eszköz device pixel ratio-ja alapján. Ehhez elég az assets-ben csak a images/ gyökérmappát megadni.

Egyedi betűtípusok a fonts szekción keresztül adhatók hozzá a family és a betűtípusok listájának megadásával. A pubspec.yaml módosítása után a flutter pub get futtatása szükséges a beállítások alkalmazásához. A betűtípusok használhatók globálisan a MaterialApp témában, valamint lokálisan konkrét widgetekben. Minden betűtípushoz megadható a weight (100-900) és a style (normal, italic), ami lehetővé teszi a Flutter számára, hogy megfelelően válassza ki a betűtípusfájlt a FontWeight és FontStyle kódban történő használatakor.

Függőségek és verziók kezelése

A pub több módszert támogat a függőségek forrásainak megadására: pub.dev, Git repositoryk, helyi elérési utak és privát repositoryk. A forrás kiválasztása a fejlesztési szakasztól függ: stabil verziókhoz a pub.dev, forkokhoz és egyéni módosításokhoz a Git, párhuzamosan fejlesztett könyvtárakhoz a helyi elérési út használatos.

A ^version operátor kompatibilis verziót jelent: a ^1.2.0 engedélyezi a >=1.2.0 és <2.0.0 verziókat. Ez analóg a ~> operátorral a CocoaPods-ban és a Caret operátorral az npm-ben. A pub automatikusan oldja meg a Dependency Hell-t egy SAT-megoldó algoritmus segítségével, amely megtalálja a verziók azon kombinációját, amely minden korlátozást kielégít. Ha ilyen kombináció nem létezik, a pub részletes üzenetet jelenít meg az ütköző csomagok megjelölésével.

A pubspec.lock fájl rögzíti a függőségek pontos verzióit. Alkalmazások esetén a verziókezelő rendszerben kell tartani a reprodukálható buildek biztosításához a csapat összes gépén. Könyvtárak esetén a pubspec.lock nem kerül be a repositoryba, hogy a könyvtár felhasználói különböző függőségi verziókkal használhassák azt. A flutter pub upgrade parancs frissíti az összes függőséget a pubspec.yaml korlátozásainak megfelelően, a flutter pub outdated pedig megmutatja, mely csomagok frissíthetők.

Építés és publikálás konfigurálása

Az alkalmazás pub.dev-en történő publikálásához a beállításokat a publish_to szekcióban kell megadni. A 'none' érték megtiltja a csomag véletlen publikálását, ami fontos a belső vagy nem nyilvános projekteknél. Ha a publish_to hiányzik, a pub megpróbálja publikálni a csomagot az alapértelmezett pub.dev-en, ami nem kívánt kódszivárgáshoz vezethet.

A flutter szekció platformparamétereket tartalmaz: generate a platformfájlok automatikus generálásához és deferred-components a funkcionalitás moduláris betöltéséhez. A generate: true paraméter hatására a Flutter automatikusan létrehozza és frissíti a platformprojekteket (iOS, Android, Web) új platformok flutter create --platforms segítségével történő hozzáadásakor. E paraméter nélkül a platformmappák szerkezete elveszítheti a szinkronizációt a pubspec.yaml-lal.

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

A platforms szekció beállítja a csomag célplatformjait. Alkalmazások esetén automatikusan meghatározásra kerül egy adott platform flutter create segítségével történő támogatásának hozzáadásakor. A platformok manuálisan is hozzáadhatók és eltávolíthatók a pubspec.yaml szerkesztésével. A Deferred Components lehetővé teszi az alkalmazás részeinek igény szerinti betöltését, csökkentve a telepítés méretét — ez különösen releváns a játékok és a ritkán használt tartalommal rendelkező alkalmazások esetében.

A csomag publikálásakor a pub ellenőrzi a pubspec.yaml összes mezőjének megfelelőségét a repository követelményeinek. A kötelező name, version és description mezők hiánya a publikálás elutasításához vezet. Ezenkívül ellenőrzésre kerül a licenc érvényessége, a README.md és CHANGELOG.md megléte. A kódanalizátor (dart analyze) hibáit tartalmazó csomagok szintén nem mennek át az érvényesítésen. Sikeres publikálás után a csomag néhány percen belül elérhetővé válik a pub.dev-en.

A dependency_overrides szekció lehetővé teszi egy csomag verziójának kényszerítését, figyelmen kívül hagyva a tranzitív függőségekből származó korlátozásokat. Ez egy erőteljes, de veszélyes mechanizmus: helytelen használat esetén a könyvtárak inkompatibilitásához vezethet. A dependency_overrides csak ideiglenesen használja konfliktusok megoldására vagy új verziók tesztelésére. A fő függőségek javítása után az override-ot el kell távolítani, hogy hosszú távon ne zavarja a projekt függőségi gráfját.

Az executables szekció a pubspec.yaml-ban lehetővé teszi végrehajtható szkriptek megadását, amelyeket a pub a PATH-ba telepít a csomag aktiválásakor. Ez hasznos a Dart-ben írt CLI eszközökhöz, például a build_runner vagy a dart_code_metrics számára. A dart pub global activate parancs globálisan telepíti a csomagot, elérhetővé téve a terminálból az executables-ben megadott szkripteket. Alkalmazások esetén az executables általában nem használatos, mivel a belépési pont a lib/main.dart fájlban lévő main-en keresztül kerül meghatározásra.