تشريح pubspec.yaml

يحتوي كل مشروع Dart على ملف pubspec.yaml في مجلده الجذر. وهو البيان الذي يصف مشروعك ويسرد كل ما يعتمد عليه. 📄

يستخدم Dart لغة YAML هنا لأنها سهلة القراءة للبشر: إذ يوضح الإزاحة البنية، وتكتب المفاتيح متبوعة بنقطتين وقيمة. ولا حاجة إلى الأقواس.

حقل name مطلوب. ويجب أن يتكون من أحرف صغيرة وشرطات سفلية، ويصبح المعرّف الذي تستخدمه الشيفرات الأخرى لاستيراد الحزمة.

أضف description مختصراً حتى يعرف المستخدمون وظيفة حزمتك، وأضف version يتبع تنسيق major.minor.patch مثل 1.2.0.

يحدد مفتاح environment إصدارات Dart SDK التي يدعمها مشروعك. وترفض الأدوات التشغيل إذا كان SDK خارج هذا النطاق.

يسرد قسم dependencies الحزم التي تحتاج إليها شيفرتك وقت التشغيل. وكل إدخال هو اسم حزمة مرتبط بقيد إصدار.

استخدم dev_dependencies للأدوات التي تحتاج إليها أثناء البناء فقط، مثل حزم الاختبار أو lint. ولا تُشحن هذه الأدوات إلى مستخدمي حزمتك.

تعني caret مثل ^1.2.0 أي إصدار يبدأ من 1.2.0 وحتى ما قبل 2.0.0. ويتيح لك ذلك قبول التحديثات الآمنة والمتوافقة.

تستخدم YAML المسافات، لا علامات الجدولة، لإظهار التداخل. ويؤدي عدم محاذاة أحد المفاتيح إلى إفساد الملف، لذا حافظ على indentation من مسافتين في كل الملف.

يمكنك أيضاً إضافة الحقول homepage وrepository وpublish_to. فهي توفر روابط للمستخدمين، وتتيح لك إبقاء الحزمة خاصة عند الحاجة.

عند تشغيل أوامر pub، تقرأ الأداة pubspec.yaml أولاً لمعرفة اعتمادياتك، ثم تجلب كل شيء وتحلّه نيابةً عنك. 🔧

أين تضع الحزم التي تحتاج إليها أثناء التطوير فقط؟

تعلمت أن pubspec.yaml يسمي مشروعك، ويحدد نطاق SDK، ويسرد اعتماديات وقت التشغيل واعتماديات التطوير. إنه قلب كل مشروع Dart. 🎉