KAL
Menu

pubspec.yaml

pubspec.yaml untuk dependensi, batasan versi, dan batas SDK.

Daftar isi

pubspec.yaml adalah berkas konfigurasi utama yang wajib ada pada setiap proyek Dart. Berkas ini mendeklarasikan identitas proyek, batas versi SDK yang dituntut, dan daftar dependensi (dependency) yang dibutuhkan program, sehingga seluruh ketergantungan pada package eksternal terbaca dalam satu tempat. Topik ini membahas bidang-bidang utamanya, sintaks batasan versi, pemisahan dependensi produksi dan dependensi pengujian, pengalihan dependensi dengan dependency_overrides, serta perintah dart pub get dan dart pub outdated. Seluruh contoh menggunakan satu proyek kecil konversi satuan, sehingga setiap perubahan pada pubspec.yaml beserta keluarannya dapat diikuti dari awal hingga akhir.

Bidang utama pubspec.yaml#

Bidang name mendefinisikan pengenal package, dan aturannya membatasi karakter pada huruf kecil Latin, angka, serta garis bawah, misalnya konversi_satuan. Nama tidak boleh diawali angka dan tidak boleh berupa kata tercadang (reserved word) Dart, karena nama package digunakan langsung sebagai pengenal dalam kode. Nama inilah yang digunakan pernyataan import untuk merujuk package dan yang ditampilkan di pub.dev apabila package dipublikasikan, sehingga pencarian singkat di pub.dev sebelum menetapkan nama dianjurkan untuk menghindari persamaan nama.

Bidang description memuat satu kalimat tujuan package dalam teks polos tanpa Markdown maupun HTML, dengan panjang yang disarankan 60 sampai 180 karakter. Bidang ini bersifat opsional untuk package pribadi, tetapi menjadi wajib ketika package akan dipublikasikan. Bidang version menampung versi package menurut aturan semantic versioning, yaitu pola major.minor.patch yang menaikkan tiap komponen sesuai besar perubahannya. Versi yang sama digunakan pub.dev dan CHANGELOG untuk menandai setiap rilis.

Bidang environment mendeklarasikan batasan SDK (SDK constraint), yaitu rentang versi Dart yang dituntut proyek, dan bidang ini wajib ada sejak Dart 2. Nilai sdk: ^3.13.0 berarti proyek berjalan pada Dart 3.13.0 atau lebih baru yang masih termasuk mayor 3. Eksekusi dart pub get pada SDK yang lebih tua ditolak dengan pesan error batasan yang tidak terpenuhi.

Berkas awal proyek contoh didefinisikan sebagai berikut.

yaml pubspec.yaml 
name: konversi_satuan
description: Konverter satuan panjang untuk latihan pubspec.yaml.
version: 1.0.0
environment:
  sdk: ^3.13.0
bash 
export PATH=/home/kal/dart-sdk/bin:$PATH
# siapkan proyek konversi satuan dari awal
rm -rf ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
mkdir -p ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan/bin
cd ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
cat > pubspec.yaml <<'EOF'
name: konversi_satuan
description: Konverter satuan panjang untuk latihan pubspec.yaml.
version: 1.0.0
environment:
  sdk: ^3.13.0
EOF
cat > bin/konversi_satuan.dart <<'EOF'
void main() {
  print('1 kilometer = 1000 meter');
}
EOF
# validasi pubspec dan siapkan lingkungan proyek
dart pub get
# jalankan program untuk memastikan proyek siap dipakai
dart run bin/konversi_satuan.dart
text Keluaran 
Resolving dependencies...
Downloading packages...
Got dependencies!
1 kilometer = 1000 meter

Tiga baris pertama keluaran adalah tahap kerja dart pub get, yaitu menyelesaikan grafik dependensi, mengunduh package, dan menandai selesai. Tidak ada baris berawalan + karena pubspec belum memuat dependensi, sedangkan pesan Got dependencies! menandakan pubspec valid sehingga proyek siap digunakan. Baris terakhir berasal dari dart run dan membuktikan bahwa proyek berjalan hanya dengan empat bidang di atas.

Sintaks batasan versi#

pub menawarkan sintaks caret (caret syntax), yaitu notasi tanda ^ yang menyatakan rentang versi tanpa menuliskan batas bawah dan batas atasnya secara eksplisit. Batasan ^1.6.0 menaikkan komponen mayor, sehingga rentangnya setara dengan >=1.6.0 <2.0.0. Pada versi di bawah 1.0.0, caret menaikkan komponen bukan nol yang terdepan, sehingga ^0.1.2 setara dengan >=0.1.2 <0.2.0. Konvensi ini mengikuti spesifikasi semantic versioning bahwa kenaikan mayor berpotensi merusak kompatibilitas, sedangkan kenaikan minor dan patch dianggap aman.

BatasanRentang yang dicakup
^1.6.0>=1.6.0 <2.0.0
^0.1.2>=0.1.2 <0.2.0
>=1.2.0 <1.5.0mulai 1.2.0 hingga sebelum 1.5.0
1.6.0persis satu versi tanpa ruang gerak
anysemua versi yang tersedia

Batasan rentang ditulis dengan dua operator, yaitu batas bawah >= dan batas atas <, sehingga pub dapat memilih versi mana pun di dalamnya. Batasan versi persis seperti 1.6.0 menutup seluruh pembaruan termasuk pembaruan patch yang biasanya aman, sehingga bentuk ini jarang digunakan. Nilai any menyerahkan pemilihan versi sepenuhnya kepada pub dan berlaku sampai kondisi resolusi berubah.

yaml Contoh: penulisan batasan versi 
dependencies:
  http: ^1.6.0
  intl: '>=0.19.0 <0.21.0'
bash 
export PATH=/home/kal/dart-sdk/bin:$PATH
# bangun ulang proyek dengan batasan rentang pada package http
rm -rf ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
mkdir -p ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
cd ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
cat > pubspec.yaml <<'EOF'
name: konversi_satuan
description: Konverter satuan panjang untuk latihan pubspec.yaml.
version: 1.0.0
environment:
  sdk: ^3.13.0
dependencies:
  http: '>=1.5.0 <2.0.0'
EOF
dart pub get
text Keluaran 
Resolving dependencies...
Downloading packages...
+ async 2.13.1
+ collection 1.19.1
+ http 1.6.0
+ http_parser 4.1.2
+ meta 1.19.0
+ path 1.9.1
+ source_span 1.10.2
+ string_scanner 1.4.1
+ term_glyph 1.2.2
+ typed_data 1.4.0
+ web 1.1.2
Changed 11 dependencies!

pub memilih versi tertinggi yang berada di dalam rentang, sehingga batasan >=1.5.0 <2.0.0 menghasilkan http 1.6.0. Sepuluh baris berawalan + lainnya merupakan dependensi turunan yang ikut masuk karena dibutuhkan oleh http. Pesan Changed 11 dependencies! menghitung seluruh entri baru pada pubspec.lock, bukan hanya dependensi langsung yang tertulis pada pubspec.yaml. Batasan ini tetap berlaku sebagai batas atas, sehingga versi http di atas 2.0.0 tidak akan terpilih tanpa penyuntingan pubspec.yaml.

Bidang dependencies dan dev_dependencies#

pub mendukung dua bagian daftar dependensi pada pubspec.yaml, yaitu dependencies untuk package yang dibutuhkan saat program berjalan dan dev_dependencies untuk package yang hanya dibutuhkan saat pengembangan. Aturan penempatannya sederhana: package yang diimpor dari kode pada folder lib atau bin wajib tercantum pada dependencies, sedangkan package yang hanya digunakan dalam pengujian dan alat bantu pengembangan masuk ke dev_dependencies. Perbedaan keduanya baru tampak ketika proyek dipublikasikan atau dijadikan dependensi proyek lain. pub mengambil dev_dependencies milik proyek sendiri, tetapi mengabaikan dev_dependencies milik package yang diandalkan, sehingga alat pengujian sebuah package tidak ikut diunduh oleh penggunanya.

bash 
export PATH=/home/kal/dart-sdk/bin:$PATH
# bangun ulang proyek dengan dependensi produksi dan dependensi pengujian
rm -rf ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
mkdir -p ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
cd ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
cat > pubspec.yaml <<'EOF'
name: konversi_satuan
description: Konverter satuan panjang untuk latihan pubspec.yaml.
version: 1.0.0
environment:
  sdk: ^3.13.0
dependencies:
  http: ^1.6.0
dev_dependencies:
  test: ^1.33.0
EOF
# jalankan pub get, lalu tampilkan hanya baris dependensi langsung
dart pub get | grep -E '^(Resolving|Downloading|\+ http |\+ test |Changed)'
text Keluaran 
Resolving dependencies...
Downloading packages...
+ http 1.6.0
+ test 1.33.0
Changed 50 dependencies!

Keluaran disaring dengan grep agar daftar resolusi yang memuat lima puluh entri tidak memenuhi contoh, sedangkan pembaca yang menjalankan perintahnya langsung akan melihat daftar lengkapnya. Dua baris berawalan + adalah dependensi langsung, yaitu http pada bagian dependencies dan test pada bagian dev_dependencies. Pesan Changed 50 dependencies! menghitung seluruh entri yang masuk ke pubspec.lock, dan sebagian besar merupakan dependensi turunan dari package test. Dengan pemisahan ini, alat pengujian tetap tersedia saat pengembangan tanpa memberatkan pengguna yang hanya mengonsumsi package.

Mengalihkan dependensi dengan dependency_overrides#

Bidang dependency_overrides mengalihkan penyelesaian terhadap sebuah dependensi tanpa menyunting deklarasi dependensinya. Bentuk yang umum adalah pengalihan ke salinan lokal melalui path, misalnya saat perbaikan dilakukan pada salinan package tanpa harus menyunting setiap pubspec yang merujuknya. Pengalihan hanya berlaku pada pubspec tempat bidang itu ditulis, sedangkan dependency_overrides pada package dependen diabaikan, sehingga pengguna package yang dipublikasikan tidak mewarisi pengalihannya. Contoh berikut memperlihatkan proyek konversi_satuan yang mendeklarasikan dependensi satuan_dasar seperti biasa, sedangkan dependency_overrides mengalihkan sumbernya ke folder tetangga.

bash 
export PATH=/home/kal/dart-sdk/bin:$PATH
# buat package lokal pendamping sebagai salinan kerja
rm -rf ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
rm -rf ~/contoh/package-dan-pub/pubspec-yaml/satuan_dasar
mkdir -p ~/contoh/package-dan-pub/pubspec-yaml/satuan_dasar/lib
cat > ~/contoh/package-dan-pub/pubspec-yaml/satuan_dasar/pubspec.yaml <<'EOF'
name: satuan_dasar
description: Definisi satuan dasar untuk latihan dependency_overrides.
version: 1.0.0
environment:
  sdk: ^3.13.0
EOF
cat > ~/contoh/package-dan-pub/pubspec-yaml/satuan_dasar/lib/satuan_dasar.dart <<'EOF'
String identitas() => 'satuan_dasar 1.0.0 dari salinan lokal';
EOF
mkdir -p ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan/bin
cd ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
cat > pubspec.yaml <<'EOF'
name: konversi_satuan
description: Konverter satuan panjang untuk latihan pubspec.yaml.
version: 1.0.0
environment:
  sdk: ^3.13.0
dependencies:
  satuan_dasar: ^1.0.0
dependency_overrides:
  satuan_dasar:
    path: ../satuan_dasar
EOF
cat > bin/konversi_satuan.dart <<'EOF'
import 'package:satuan_dasar/satuan_dasar.dart';

void main() {
  print(identitas());
}
EOF
dart pub get
dart run bin/konversi_satuan.dart
text Keluaran 
Resolving dependencies...
Downloading packages...
! satuan_dasar 1.0.0 from path ../satuan_dasar (overridden)
Got dependencies!
satuan_dasar 1.0.0 dari salinan lokal

pub menandai entri yang dialihkan dengan awalan ! beserta keterangan (overridden), sehingga asal satuan_dasar segera terlihat. Tidak ada versi yang diambil dari pub.dev untuk package ini karena sumbernya sudah digantikan folder lokal. Program utama mengimpor package:satuan_dasar/satuan_dasar.dart dan menjalankan fungsi identitas() dari salinan lokal, sehingga dart run mencetak pesan dari folder tetangga. Pengalihan bersifat sementara, dan bidang dependency_overrides dihapus setelah perbaikan selesai agar proyek kembali menyelesaikan versi dari pub.dev.

Memantau versi dengan dart pub outdated#

Perintah dart pub outdated membandingkan versi terkunci pada pubspec.lock dengan versi yang tersedia di pub.dev, lalu menyusun tabel per package. Kolom Current menunjukkan versi yang terkunci pada pubspec.lock. Kolom Upgradable menunjukkan hasil dart pub upgrade di dalam batasan pubspec.yaml saat ini, sedangkan kolom Resolvable menunjukkan versi tertinggi yang masih dapat diselesaikan dengan mempertimbangkan dependensi lain. Kolom Latest menunjukkan versi terbaru yang tersedia di pub.dev.

Contoh berikut menetapkan batasan >=1.2.0 <1.5.0 yang menutup versi 1.5.0 ke atas, menjalankan dart pub get, lalu memantau posisinya dengan dart pub outdated.

bash 
export PATH=/home/kal/dart-sdk/bin:$PATH
# bangun ulang proyek dengan batasan yang menutup versi terbaru
rm -rf ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
mkdir -p ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
cd ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
cat > pubspec.yaml <<'EOF'
name: konversi_satuan
description: Konverter satuan panjang untuk latihan pubspec.yaml.
version: 1.0.0
environment:
  sdk: ^3.13.0
dependencies:
  http: '>=1.2.0 <1.5.0'
EOF
dart pub get
dart pub outdated
text Keluaran 
Resolving dependencies...
Downloading packages...
+ async 2.13.1
+ collection 1.19.1
+ http 1.4.0 (1.6.0 available)
+ http_parser 4.1.2
+ meta 1.19.0
+ path 1.9.1
+ source_span 1.10.2
+ string_scanner 1.4.1
+ term_glyph 1.2.2
+ typed_data 1.4.0
+ web 1.1.2
Changed 11 dependencies!
1 package has newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.
Showing outdated packages.
[*] indicates versions that are not the latest available.

Package Name  Current  Upgradable  Resolvable  Latest

direct dependencies:
http          *1.4.0   *1.4.0      1.6.0       1.6.0

1 dependency is constrained to a version that is older than a resolvable version.
To update it, edit pubspec.yaml, or run `dart pub upgrade --major-versions`.

Batasan <1.5.0 membuat pub memilih http 1.4.0, dan baris resolusinya menyertakan keterangan (1.6.0 available) karena versi yang lebih tinggi berada di luar batasan. Tanda * pada kolom Current dan Upgradable menandai versi yang bukan versi terbaru. dart pub upgrade hanya dapat mencapai 1.4.0 karena Upgradable mengikuti batasan pubspec.yaml, sedangkan kolom Resolvable 1.6.0 menunjukkan versi yang dapat dicapai setelah batasan dilonggarkan. Pesan penutup menegaskan langkahnya, yaitu menyunting pubspec.yaml atau menjalankan dart pub upgrade --major-versions untuk mencapai versi tersebut.

Kesalahan umum#

Kesalahan pertama adalah menuliskan batasan yang tidak tersedia di pub.dev, sehingga resolusi dependensi gagal sepenuhnya. Contoh berikut menetapkan batasan >=99.0.0 yang tidak mendekati versi http mana pun, lalu menjalankan dart pub get untuk memperlihatkan bentuk errornya.

bash 
export PATH=/home/kal/dart-sdk/bin:$PATH
# bangun ulang proyek dengan batasan yang tidak tersedia di pub.dev
rm -rf ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
mkdir -p ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
cd ~/contoh/package-dan-pub/pubspec-yaml/konversi_satuan
cat > pubspec.yaml <<'EOF'
name: konversi_satuan
description: Konverter satuan panjang untuk latihan pubspec.yaml.
version: 1.0.0
environment:
  sdk: ^3.13.0
dependencies:
  http: '>=99.0.0'
EOF
dart pub get
text Keluaran 
Resolving dependencies...
Because konversi_satuan depends on http >=99.0.0 which doesn't match any versions, version solving failed.

You can try the following suggestion to make the pubspec resolve:
* Consider downgrading your constraint on http: dart pub add http:^1.6.0

Pesan error menyebutkan dependensi yang bermasalah beserta batasannya, sehingga penyebabnya ditemukan tanpa membuka pubspec.lock. pub juga menawarkan perbaikan langsung berupa perintah dart pub add http:^1.6.0 yang menuliskan batasan caret pada versi terbaru. Error serupa muncul apabila batasan SDK pada environment lebih baru daripada SDK yang terpasang, sehingga pesan error resolusi selalu layak dibaca dari baris pertama.

Kesalahan kedua adalah menyunting pubspec.yaml tanpa menjalankan dart pub get setelahnya. Pemetaan package pada folder .dart_tool hanya diperbarui oleh perintah itu, sehingga program yang mengimpor package yang baru ditambahkan langsung memunculkan error bahwa package tidak ditemukan, padahal entri dependensinya sudah benar. Perbaikannya hanya satu langkah, yaitu menjalankan dart pub get sebelum dart run atau dart test, sehingga kebiasaan menyunting pubspec.yaml selalu disertai dart pub get.

Kesalahan ketiga adalah menempatkan package pengujian seperti test pada dependencies. Konsekuensinya muncul apabila package dipublikasikan, karena setiap pengguna ikut mengunduh alat yang sebenarnya hanya dibutuhkan pengembangnya. Pemeriksaannya cepat, yaitu memastikan setiap entri dependencies benar-benar diimpor dari lib atau bin, sedangkan entri yang hanya dirujuk folder test dipindahkan ke dev_dependencies.

Ringkasan#

  • pubspec.yaml mendeklarasikan name, description, version, batasan SDK pada environment, serta dua bagian dependensi, yaitu dependencies dan dev_dependencies.
  • Batasan versi ditulis dengan caret (^1.6.0), rentang (>=1.2.0 <1.5.0), versi persis, atau any, dan batasan yang diawali >= wajib diapit tanda kutip.
  • dart pub get menyelesaikan grafik dependensi dan menulis pubspec.lock, sedangkan dependency_overrides mengalihkan penyelesaian ke sumber lain seperti salinan lokal.
  • dart pub outdated membandingkan versi terkunci dengan versi di pub.dev melalui kolom Current, Upgradable, Resolvable, dan Latest.

Referensi#