pubspec.yaml — шта је то, структура и конфигурација зависности у Flutter-у

Шта је pubspec.yaml

pubspec.yaml — манифест фајл у формату YAML који менаџер пакета pub користи за управљање Dart и Flutter пројектима. Налази се у корену пројекта и обрађује се при свакој команди flutter pub get. За разлику од других платформи где је конфигурација распоређена по неколико фајлова, Flutter користи један централизовани манифест за све потребе.

Фајл садржи метаподатке: назив пројекта, опис, верзију, аутора. Ови подаци се користе при објављивању пакета на pub.dev и при изградњи апликације за App Store и Google Play. Поље description се приказује у резултатима претраге пакета, зато треба да буде информативно и да садржи кључне речи по којима други програмери могу пронаћи библиотеку.

Без исправног pubspec.yaml-а Flutter пројекат не може бити изграђен. Грешке синтаксе или нетачна увлачења доводе до тренутног прекида компилације са поруком Error on line X. YAML је осетљив на размаке: један додатни размак мења структуру података, а табулатор изазива синтаксну грешку. Зато је при ручном уређивању pubspec.yaml-а важно користити едитор са истицањем YAML синтаксе, попут VS Code са званичним проширењем за Flutter.

Главне секције pubspec.yaml

pubspec.yaml се састоји од обавезних и опционих секција. Свака секција је одговорна за одређени аспект конфигурације пројекта. Редослед секција није битан, али се према конвенцији заједнице поштује хијерархија: метаподаци, окружење, зависности, ресурси, платформе.

name и description

Поље name поставља јединствени идентификатор пакета у формату snake_case, састављен само од малих латиничних слова, бројева и доњих црта. Поље description — кратак опис пројекта до 180 знакова, обавезан за објављивање на pub.dev. Опис треба да објасни намену пакета, не понављајући назив, и да садржи кључне речи за оптимизацију претраге репозиторијума.

name: my_flutter_app
description: Приложение для управления задачами с Flutter
publish_to: 'none'

version и environment

Поље version користи семантичко верзионисање major.minor.patch са опционим бројем изградње након знака плус (1.0.0+1). Секција environment поставља минималне и максималне верзије Dart и Flutter SDK-а за гаранцију компатибилности. Ако нова верзија SDK-а садржи критичне измене некомпатибилне са кодом пројекта, компилација ће бити прекинута са разумљивом поруком о грешци.

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

dependencies и dev_dependencies

Секција dependencies наводи пакете неопходне за рад апликације у runtime-у. Секција dev_dependencies садржи пакете за тестирање, генерисање кода и развој — они не улазе у релизну верзију. Подела зависности је критична за перформансе: сваки пакет у dependencies повећава величину коначног APK-а или IPA-а, као и време покретања апликације због иницијализације додатних библиотека.

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

Подешавање assets-а и фонтова

Секција flutter садржи подсекције за подешавање ресурса, фонтова и параметара платформе. Ресурси се повезују преко низа paths са навођењем конкретних фајлова или целих директоријума. Све путање се наводе релативно у односу на корен пројекта, а не у односу на pubspec.yaml. Ово је важна нијанса која често изазива забуну код почетника у Flutter-у.

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

Повезивање assets-а преко pubspec.yaml-а чини фајлове доступним преко AssetBundle-а у runtime-у. Ово ради за слике, JSON, текстуалне фајлове и све друге ресурсе. Flutter аутоматски подржава различите резолуције екрана: ако ставите images/2x/ и images/3x/, Flutter ће одабрати одговарајућу верзију слике на основу device pixel ratio уређаја. За ово је довољно навести у assets само коренску фасциклу images/.

Прилагођени фонтови се додају преко секције fonts са навођењем family и списком фонтова. Након измене pubspec.yaml-а потребно је извршити flutter pub get за примену подешавања. Фонтови се могу користити како глобално у теми MaterialApp, тако и локално у конкретним виџетима. За сваки фонт се може навести weight (100-900) и style (normal, italic), што омогућава Flutter-у да правилно одабере фајл фонта при коришћењу FontWeight и FontStyle у коду.

Управљање зависностима и верзијама

pub подржава неколико начина навођења извора зависности: pub.dev, Git репозиторијуми, локалне путање и приватни репозиторијуми. Избор извора зависи од фазе развоја: за стабилне верзије се користи pub.dev, за форкове и прилагођене измене — Git, за паралелно развијане библиотеке — локална путања.

Оператор ^version означава компатибилну верзију: ^1.2.0 дозвољава верзије >=1.2.0 и <2.0.0. Ово је аналогно оператору ~> у CocoaPods и Caret оператору у npm-у. pub аутоматски решава Dependency Hell кроз SAT-солвер алгоритам који проналази комбинацију верзија која задовољава сва ограничења. Ако таква комбинација не постоји, pub приказује детаљну поруку са навођењем конфликтних пакета.

Фајл pubspec.lock фиксира тачне верзије зависности. Треба да се чува у систему контроле верзија за апликације како би се обезбедиле поновљиве изградње на свим машинама тима. За библиотеке pubspec.lock се не укључује у репозиторијум, јер корисници библиотеке треба да имају могућност да је користе са различитим верзијама зависности. Команда flutter pub upgrade ажурира све зависности према ограничењима pubspec.yaml-а, а flutter pub outdated показује који пакети се могу ажурирати.

Конфигурација изградње и објављивања

За објављивање апликације на pub.dev подешавања се наводе у секцији publish_to. Вредност 'none' забрањује случајно објављивање пакета, што је важно за интерне или нејавне пројекте. Ако publish_to недостаје, pub покушава да објави пакет на подразумеваном pub.dev-у, што може довести до нежељеног цурења кода.

Секција flutter укључује параметре платформи: generate за аутоматско генерисање платформских фајлова и deferred-components за модуларно учитавање функционалности. Параметар generate: true чини да Flutter аутоматски креира и ажурира платформске пројекте (iOS, Android, Web) при додавању нових платформи кроз flutter create --platforms. Без овог параметра, структура платформских фасцикли може се десинхронизовати са pubspec.yaml-ом.

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

Секција platforms поставља циљне платформе за пакет. За апликације се аутоматски одређује при додавању подршке за конкретну платформу кроз flutter create. Платформе се могу додавати и уклањати ручно кроз уређивање pubspec.yaml-а. Deferred Components омогућавају учитавање делова апликације на захтев, смањујући величину инсталације — ово је посебно важно за игре и апликације са великом количином ретко коришћеног садржаја.

При објављивању пакета pub проверава сва поља pubspec.yaml-а у погледу усаглашености са захтевима репозиторијума. Недостатак обавезних поља name, version и description доводи до одбијања објављивања. Додатно се проверава исправност лиценце, постојање README.md и CHANGELOG.md. Пакети са грешкама анализатора кода (dart analyze) такође не пролазе валидацију. Након успешног објављивања, пакет постаје доступан на pub.dev-у у року од неколико минута.

Секција dependency_overrides омогућава принудно навођење верзије пакета, игноришући ограничења из транзитивних зависности. Ово је моћан, али опасан механизам: при неправилној употреби може довести до некомпатибилности библиотека. Користите dependency_overrides само привремено за решавање конфликата или тестирање нових верзија. Након поправљања главних зависности, override треба уклонити како не би нарушио граф зависности пројекта на дужи рок.

Секција executables у pubspec.yaml-у омогућава навођење извршних скрипти које pub инсталира у PATH при активацији пакета. Ово је корисно за CLI алате написане у Dart-у, на пример build_runner или dart_code_metrics. Команда dart pub global activate инсталира пакет глобално, чинећи скрипте наведене у executables доступним из терминала. За апликације executables се обично не користе, јер се улазна тачка одређује кроз main у lib/main.dart-у.