pubspec.yaml — nedir, yapısı ve Flutter'da bağımlılık yapılandırması

pubspec.yaml nedir

pubspec.yaml, pub paket yöneticisinin Dart ve Flutter projelerini yönetmek için kullandığı YAML formatında bir bildirim dosyasıdır. Proje kök dizininde bulunur ve her flutter pub get komutunda işlenir. Yapılandırmanın birden çok dosyaya dağıldığı diğer platformların aksine, Flutter tüm ihtiyaçlar için tek bir merkezi bildirim kullanır.

Dosya meta veriler içerir: proje adı, açıklama, sürüm, yazar. Bu veriler, pub.dev'da bir paket yayınlarken ve App Store ile Google Play için uygulama derlerken kullanılır. description alanı, paket arama sonuçlarında görüntülenir, bu nedenle bilgilendirici olmalı ve diğer geliştiricilerin kütüphaneyi bulmasını sağlayacak anahtar kelimeler içermelidir.

Doğru bir pubspec.yaml olmadan, bir Flutter projesi derlenemez. Sözdizimi hataları veya yanlış girinti, Error on line X mesajıyla anında derleme hatasına neden olur. YAML boşluklara karşı hassastır: fazladan bir boşluk veri yapısını değiştirir ve sekmeler sözdizimi hatasına neden olur. Bu nedenle, pubspec.yaml'yi manuel olarak düzenlerken, VS Code'un resmi Flutter eklentisi gibi YAML sözdizimi vurgulamalı bir düzenleyici kullanmak önemlidir.

pubspec.yaml'in ana bölümleri

pubspec.yaml, zorunlu ve isteğe bağlı bölümlerden oluşur. Her bölüm, proje yapılandırmasının belirli bir yönünden sorumludur. Bölümlerin sırası önemli değildir, ancak topluluk geleneğine göre hiyerarşi şu şekildedir: meta veriler, ortam, bağımlılıklar, kaynaklar, platformlar.

name ve description

name alanı, yalnızca küçük harf Latin harfleri, rakamlar ve alt çizgilerden oluşan snake_case formatında benzersiz bir paket tanımlayıcısı belirler. description alanı, pub.dev'da yayınlamak için zorunlu olan, 180 karaktere kadar kısa bir proje özetidir. Açıklama, adı tekrar etmeden paketin amacını açıklamalı ve depo arama optimizasyonu için anahtar kelimeler içermelidir.

name: my_flutter_app
description: Flutter ile görev yönetimi uygulaması
publish_to: 'none'

version ve environment

version alanı, artı işaretinden (1.0.0+1) sonra isteğe bağlı bir derleme numarasıyla birlikte anlamsal sürüm oluşturma major.minor.patch kullanır. environment bölümü, uyumluluğu sağlamak için Dart ve Flutter SDK'nın minimum ve maksimum sürümlerini belirler. SDK'nın yeni bir sürümü, proje koduyla uyumsuz önemli değişiklikler içeriyorsa, derleme net bir hata mesajıyla durdurulur.

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

dependencies ve dev_dependencies

dependencies bölümü, uygulamanın çalışma zamanında çalışması için gereken paketleri listeler. dev_dependencies bölümü, test, kod oluşturma ve geliştirme için paketler içerir — bunlar sürüm derlemesine dahil edilmez. Bağımlılıkları ayırmak, performans için kritik öneme sahiptir: dependencies'deki her paket, nihai APK veya IPA boyutunu ve ayrıca ek kütüphanelerin başlatılması nedeniyle uygulama başlatma süresini artırır.

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

Varlık ve yazı tipi yapılandırması

flutter bölümü, kaynakları, yazı tiplerini ve platform parametrelerini yapılandırmak için alt bölümler içerir. Kaynaklar, belirli dosyaları veya tüm dizinleri belirten bir paths dizisi aracılığıyla bağlanır. Tüm yollar, pubspec.yaml'a göre değil, proje köküne göre belirtilir. Bu, genellikle yeni başlayan Flutter geliştiricilerinin kafasını karıştıran önemli bir ayrıntıdır.

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

pubspec.yaml aracılığıyla varlıkları bağlamak, dosyalara çalışma zamanında AssetBundle aracılığıyla erişilebilmesini sağlar. Bu, resimler, JSON, metin dosyaları ve diğer kaynaklar için çalışır. Flutter, farklı ekran çözünürlüklerini otomatik olarak destekler: images/2x/ ve images/3x/ eklerseniz, Flutter cihaz piksel oranına göre uygun resim sürümünü seçer. Bunu yapmak için, assets'te yalnızca kök images/ klasörünü belirtmek yeterlidir.

Özel yazı tipleri, bir aile adı ve stil listesiyle birlikte fonts bölümü aracılığıyla eklenir. pubspec.yaml'ı değiştirdikten sonra, değişiklikleri uygulamak için flutter pub get çalıştırmanız gerekir. Yazı tipleri, MaterialApp temasında genel olarak ve belirli widget'larda yerel olarak kullanılabilir. Her stil için weight (100–900) ve style (normal, italic) belirtebilirsiniz; bu, Flutter'ın kodda FontWeight ve FontStyle kullanırken doğru yazı tipi dosyasını seçmesini sağlar.

Bağımlılık ve sürüm yönetimi

pub, bağımlılıkların kaynaklarını belirtmek için çeşitli yolları destekler: pub.dev, Git depoları, yerel yollar ve özel depolar. Kaynak seçimi, geliştirme aşamasına bağlıdır: kararlı sürümler için pub.dev, çatallar ve özel değişiklikler için Git, paralel olarak geliştirilen kütüphaneler için yerel yol kullanılır.

^version operatörü, uyumlu bir sürüm anlamına gelir: ^1.2.0, >=1.2.0 ve <2.0.0 sürümlerine izin verir. Bu, CocoaPods'taki ~> operatörüne ve npm'deki Caret operatörüne benzer. pub, tüm kısıtlamaları karşılayan bir sürüm kombinasyonu bulan bir SAT çözücü algoritması aracılığıyla Bağımlılık Cehennemini otomatik olarak çözer. Böyle bir kombinasyon yoksa pub, çakışan paketleri belirten ayrıntılı bir mesaj görüntüler.

pubspec.lock dosyası, bağımlılıkların tam sürümlerini sabitler. Ekip içindeki tüm makinelerde tekrarlanabilir derlemeler sağlamak için uygulamalar için sürüm kontrolünde saklanmalıdır. Kütüphaneler için pubspec.lock depoya dahil edilmez, çünkü kütüphane kullanıcılarının onu farklı bağımlılık sürümleriyle kullanabilmesi gerekir. flutter pub upgrade komutu, pubspec.yaml kısıtlamalarına göre tüm bağımlılıkları güncellerken, flutter pub outdated hangi paketlerin güncellenebileceğini gösterir.

Derleme ve yayınlama yapılandırması

pub.dev'da bir uygulama yayınlamak için ayarlar publish_to bölümünde belirtilir. 'none' değeri, paketin yanlışlıkla yayınlanmasını önler; bu, dahili veya herkese açık olmayan projeler için önemlidir. publish_to eksikse, pub varsayılan pub.dev'da paketi yayınlamaya çalışır ve bu da istenmeyen kod sızıntılarına yol açabilir.

flutter bölümü, platform parametrelerini içerir: platform dosyalarının otomatik oluşturulması için generate ve modüler işlev yüklemesi için deferred-components. generate: true parametresi, flutter create --platforms aracılığıyla yeni platformlar eklenirken Flutter'ın platform projelerini (iOS, Android, Web) otomatik olarak oluşturmasını ve güncellemesini sağlar. Bu parametre olmadan, platform klasör yapısı pubspec.yaml ile senkronize olmayabilir.

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

platforms bölümü, paket için hedef platformları belirler. Uygulamalar için, flutter create aracılığıyla belirli bir platform desteği eklenirken otomatik olarak belirlenir. Platformlar, pubspec.yaml düzenlenerek manuel olarak eklenebilir ve kaldırılabilir. Ertelenmiş Bileşenler, uygulamanın bölümlerinin talep üzerine yüklenmesine izin vererek kurulum boyutunu azaltır — bu özellikle oyunlar ve çok miktarda nadiren kullanılan içeriğe sahip uygulamalar için geçerlidir.

Bir paket yayınlarken pub, pubspec.yaml'in tüm alanlarının depo gereksinimlerine uygun olup olmadığını kontrol eder. Zorunlu name, version ve description alanlarının eksikliği, yayının reddedilmesine yol açar. Ayrıca, lisansın doğruluğu ve README.md ile CHANGELOG.md'nin varlığı kontrol edilir. Kod analizörü hataları (dart analyze) olan paketler de doğrulamada başarısız olur. Başarılı yayından sonra, paket birkaç dakika içinde pub.dev'da kullanılabilir hale gelir.

dependency_overrides bölümü, geçişli bağımlılıklardaki kısıtlamaları yok sayarak belirli bir paket sürümünü zorlamaya olanak tanır. Bu güçlü ancak tehlikeli bir mekanizmadır: yanlış kullanılırsa, kütüphane uyumsuzluklarına yol açabilir. dependency_overrides'i yalnızca çakışmaları çözmek veya yeni sürümleri test etmek için geçici olarak kullanın. Ana bağımlılıklar düzeltildikten sonra, uzun vadede projenin bağımlılık grafiğini bozmamak için geçersiz kılma kaldırılmalıdır.

pubspec.yaml'deki executables bölümü, bir paket etkinleştirilirken pub'un PATH'e yüklediği yürütülebilir komut dosyalarını belirtmeye olanak tanır. Bu, build_runner veya dart_code_metrics gibi Dart ile yazılmış CLI araçları için kullanışlıdır. dart pub global activate komutu, paketi genel olarak yükleyerek executables'da belirtilen komut dosyalarını terminalden erişilebilir hale getirir. Uygulamalar için, giriş noktası lib/main.dart'taki main aracılığıyla tanımlandığından executables genellikle kullanılmaz.