pub: temel kavramlar, Dart paket yöneticisi ve pubspec.yaml

pub nedir?

pub (Package Universal Browser) — Dart SDK ile birlikte gelen yerleşik bir paket yöneticisidir. Harici kütüphaneleri yönetir, sürüm çakışmalarını çözer, geçişli bağımlılıkları indirir ve paketleri yerel olarak önbelleğe alır. Flutter ekosisteminde pub, navigasyon eklentilerini, HTTP istemcilerini, durum yöneticilerini ve diğer bileşenleri bağlamak için ana araç olarak kullanılır.

pub'un temel işlevleri şunları içerir: pub.dev kaydından bağımlılıkları yükleme, yerel yollar (yol bağımlılıkları) ve git depoları; anlamsal sürümleme kurallarına göre sürüm çözümleme; sistem dizininde indirilen paketlerin önbelleğe alınması; genel kayıtta kendi paketlerinin yayımlanması. Tüm bu işlemler CLI komutu dart pub veya eşdeğeri flutter pub aracılığıyla kullanılabilir.

pub'un mimarisi kapalı bağımlılık grafiğine dayanır: yönetici, her paketin tam olarak bir kez göründüğü bir ağaç oluşturur. İki kütüphane aynı paketin farklı sürümlerini gerektiriyorsa, pub uyumlu bir aralık bulmaya çalışır veya bir çakışma hatası bildirir. Bu, aynı paketin birden çok sürümüne farklı ağaç düğümlerinde izin veren npm yaklaşımından farklıdır.

pubspec.yaml yapısı

pubspec.yaml dosyası — herhangi bir Dart veya Flutter projesinin merkezi yapılandırma dosyasıdır. YAML formatında yazılır ve meta veriler, bağımlılıklar, derleme yapılandırması ve SDK kısıtlamalarını içerir. Aşağıda bir Flutter uygulaması için tipik bir örnek verilmiştir:

name: my_app
description: Örnek Flutter uygulaması
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/

pubspec.yaml'ın temel alanları: name — benzersiz paket adı (yalnızca Latin harfleri, alt çizgi, rakamlar); description — kısa açıklama (yayımlama için zorunlu); version — artı işaretinden sonra isteğe bağlı derleme numarasıyla anlamsal sürüm; environment — minimum Dart SDK ve Flutter SDK sürümleri; dependencies — ana uygulama bağımlılıkları; dev_dependencies — yalnızca geliştirme ve test için bağımlılıklar; flutter — Flutter yapılandırma bölümü (varlıklar, yazı tipleri, eklentiler).

publish_to alanı yayımlama kullanılabilirliğini kontrol eder: none değeri yayımlamayı yasaklar (uygulamalar için tipik), varsayılan değer — https://pub.dev. dependency_overrides alanı, çakışma durumlarında bir paket sürümünü zorla geçersiz kılmaya izin verir — dikkatli kullanın, yalnızca geçici çözüm olarak.

Bağımlılıklar ve türleri

pub, her biri pubspec.yaml içinde kendi sözdizimiyle belirtilen dört tür bağımlılığı destekler:

Barındırılan (hosted)

Standart tür — paket pub.dev kaydından veya başka bir uyumlu kayıttan indirilir. Paket adı ve sürümü belirtilir. Örnek: http: ^1.1.0, caret sürümleme kurallarına göre >=1.1.0 ve <2.0.0 aralığından en son uyumlu sürümü indirir.

SDK bağımlılıkları

Flutter SDK veya Dart SDK'yı dahil etmek için kullanılır. Sözdizimi: flutter: sdk: flutter. Paket, kayıttan değil, yerel Flutter SDK kurulumundan alınır. SDK bağımlılıkları sürümlenmez — sürümleri, yüklü olan Flutter sürümü tarafından belirlenir.

Yol (path)

Bir paket içeren yerel bir dizini işaret eder. Yayımlamadan kütüphane geliştirirken ve test ederken kullanışlıdır. Sözdizimi:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Yol bağımlılıkları pubspec.lock'ta sabitlenmez — her güncelleme belirtilen yoldan yeniden çözümlenir.

Git

Bir paketi doğrudan bir git deposundan dahil etmeye izin verir. Dallar, etiketler ve commit'ler desteklenir:

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

Git bağımlılıkları, çatallar, yayımlanmamış düzeltmeler veya Pull Request'ler üzerinde çalışmak için uygundur. Derleme sırasında beklenmeyen değişiklikleri önlemek için bir dal yerine belirli bir etiket veya commit belirtilmesi önerilir.

Sürümleme ve aralıklar

pub, Semantic Versioning 2.0'ı sıkı bir şekilde takip eder: biçim MAJOR.MINOR.PATCH (MAJOR — uyumsuz değişiklikler, MINOR — geriye dönük uyumlu eklemeler, PATCH — geriye dönük uyumlu düzeltmeler). Bu şemaya dayanarak pub, paket uyumluluğunu belirler ve çakışmaları çözer.

pubspec.yaml'da sürümleri belirtmek için üç ana operatör kullanılır:

• Caret (^) — ^1.2.3, >=1.2.3 ve <2.0.0'a eşdeğerdir. En yaygın operatör, çünkü ana sürüm içinde uyumluluk anlamına gelir. Ana sürümü 0 (sıfır) olan paketler için — ^0.1.2, >=0.1.2 ve <0.2.0 anlamına gelir ve kararsız sürümler için SemVer kurallarını izler.
• Tilde (~) — ~1.2.3, >=1.2.3 ve <1.3.0'a eşdeğerdir. Alt sürümü sabitler, yalnızca yama güncellemelerine izin verir. Daha az kullanılır, esas olarak alt sürüm düzeyinde uyumsuzluk bilindiğinde.
• Kesin aralık — >=1.2.0 <2.0.0 — tam kontrol sağlayan açık gösterim. Karmaşık kısıtlamalar için kullanışlıdır, örneğin geçişli bağımlılıkların birden çok sürümü kullanılırken.

dart pub get çalıştırıldıktan sonra pub, çözümlenen tüm paketlerin (doğrudan ve geçişli) kesin sürümlerini sabitleyen bir pubspec.lock dosyası oluşturur. Bu dosya, tüm makinelerde tekrarlanabilir derlemeler sağlamak için sürüm kontrolüne dahil edilmelidir. dart pub upgrade çalıştırıldığında, kilit dosyası belirtilen kısıtlamalar dahilinde en son uyumlu sürümlere güncellenir.

Bir bağımlılık çakışması hatası, iki paket aynı bağımlılığın örtüşmeyen aralıklarını gerektirdiğinde oluşur. pub, hangi paketlerin çakıştığını ve nedenini bildirir. Çözüm: çakışan paketlerden birini uyumlu bir sürüme güncelleyin, dependency_overrides (geçici önlem) kullanın veya alternatif bir pakete geçin.

pub temel komutları

Tüm pub işlemleri birleşik bir CLI arayüzü üzerinden gerçekleştirilir. Dart SDK dart pub komutunu kullanır, Flutter SDK eşdeğer flutter pub'u kullanır (ek olarak Flutter SDK bağımlılıklarını ve eklentilerini dikkate alır). Temel komutlar aşağıda verilmiştir:

• dart pub get — pubspec.yaml'de belirtilen tüm bağımlılıkları indirir, sürümleri çözümler ve pubspec.lock oluşturur/günceller. Bir projeyi ilk kez klonlarken veya bağımlılıkları değiştirdikten sonra çalıştırın.
• dart pub upgrade — tüm bağımlılıkları pubspec.yaml kısıtlamaları dahilinde en son sürümlere günceller ve pubspec.lock'u üzerine yazar. Tek bir paket güncellenebilir: dart pub upgrade http.
• dart pub add <package> — pubspec.yaml'e yeni bir bağımlılık ekler ve hemen pub get'i çalıştırır. Örnek: dart pub add dio, dio paketinin en son sürümünü ekler.
• dart pub remove <package> — pubspec.yaml'den bir bağımlılığı kaldırır ve grafik çözümlemeyi yeniden başlatır.
• dart pub cache repair — önbelleğe alınmış tüm paketleri yeniden yükler. Yerel önbellek bozulduğunda veya sağlama toplamı hatalarında yardımcı olur.
• dart pub deps — bağımlılık ağacını kullanışlı bir metin biçiminde yazdırır. Geçişli bağımlılıkları analiz etmek ve kopyaları bulmak için kullanışlıdır.
• dart pub publish — mevcut paketi pub.dev'de yayımlar. Yayımlamadan önce pubspec.yaml, lisans ve açıklamayı doğrular.
• dart pub outdated — geçerli, istenen ve mevcut en son sürümü belirterek güncel olmayan bağımlılıkların bir listesini gösterir. npm outdated ile benzer.

Tüm komutlar ayrıca kısaltılmış biçimde dart pub get olarak dart pub g şeklinde de mevcuttur (tüm kısaltmalar değil). Flutter projelerinde, komutların önüne flutter eklenir: flutter pub get, flutter pub add vb. Flutter sürümü ayrıca eklentilerin hedef platformla uyumluluğunu da kontrol eder.

pub.dev'de yayımlama

pub.dev — Dart ve Flutter ekosisteminin merkezi paket kaydıdır. Ocak 2025 itibarıyla burada 50.000'den fazla paket yayımlanmış olup toplam indirme sayısı 10 milyarı aşmıştır. Her paketin açıklama, belgeler, popülerlik puanları, Pub Points derecelendirmeleri ve sürümler içeren bir sayfası vardır.

Pub Points — 0'dan 130'a kadar otomatik bir paket kalite değerlendirme sistemidir. Şunları dikkate alır: lisans varlığı, açıklama, örnekler, en son kararlı Dart sürümüyle uyumluluk, güvenlik açıklarının olmaması, test kapsamı, biçimlendirme doğruluğu. Yüksek puan, paketin aramada görünürlüğünü ve kullanıcı güvenini artırır.

Yayımlama süreci birkaç adım içerir:

1. pubspec.yaml'ı kontrol edin: name, description, version, license'ın mevcut olduğundan emin olun (SPDX tanımlayıcısı önerilir, örn. MIT).
2. dart pub publish --dry-run çalıştırın — sunucuya göndermeden yayımlama simülasyonu, pakete dahil edilecek tüm dosyaları ve olası hataları gösterir.
3. İlk yayımlamada Google hesabıyla kimlik doğrulama: dart pub publish, OAuth kimlik doğrulaması için bir tarayıcı açacaktır.
4. Terminalde yayımlamayı onaylayın. Başarılı yüklemeden sonra paket birkaç dakika içinde pub.dev'de görünür.

Önemli kurallar: yalnızca benzersiz ada sahip paketler yayımlanabilir; bir kez yayımlanan sürüm silinemez (yalnızca 7 gün içinde dart pub unpublish ile gizlenebilir); büyük güncellemeler için Semantic Versioning kurallarına uyun, ana sürümü değiştirmeden genel API'yi bozmayın.