عند العمل على مشاريع Flutter الكبيرة، لا تكون المشكلة دائمًا في كتابة الكود فقط، بل تبدأ التحديات الحقيقية عند تجهيز التطبيق للإصدار وبناء ملفات APK أو IPA أو AAB، خصوصًا عندما يحتوي المشروع على أكثر من Flavor أو أكثر من بيئة مثل Development وStaging وProduction.

في هذه الحالة نحتاج إلى تنفيذ مجموعة من الأوامر بشكل متكرر، مثل تغيير رقم Build، وتشغيل أمر Flutter Build، وإعادة تسمية الملفات، ونقلها إلى مجلد معين، وربما رفعها إلى خدمة أخرى بعد انتهاء عملية البناء.

هنا تأتي مكتبة dartdosh، وهي أداة CLI مخصصة لمطوري Flutter تهدف إلى أتمتة هذه الخطوات وتقليل العمل اليدوي أثناء عملية بناء وتوزيع التطبيقات.

في هذا المقال سنتعرف على مكتبة dartdosh، وطريقة تثبيتها، وكيفية إعدادها داخل مشروع Flutter، وكيف يمكن استخدامها مع Flavors، وإدارة Build Number، وتنظيم ملفات APK وIPA وAAB، بالإضافة إلى مثال عملي كامل.

dartdosh هي أداة CLI مبنية باستخدام Dart ومخصصة لمشاريع Flutter، وتساعد على تبسيط عمليات Build وDistribution التي يتم تنفيذها بشكل متكرر أثناء تطوير التطبيق. وتوفر الأداة أوامر لبناء APK وIPA وApp Bundle، مع إمكانية تحديد البيئة المستخدمة في المشروع وإدارة أرقام الإصدارات وأسماء ملفات البناء. :contentReference[oaicite:1]{index=1}

بدلًا من تشغيل عدة أوامر يدويًا في كل مرة تريد فيها إنشاء نسخة Production من تطبيق Flutter، يمكنك استخدام أمر واحد من خلال DartDosh لتنفيذ العملية وفق الإعدادات الموجودة في المشروع.

وهذا يجعلها من الأدوات المفيدة عند التعامل مع مكتبات فلاتر وأدوات Flutter التي تساعد على تسريع دورة التطوير والإصدار، خصوصًا في المشاريع التي تعتمد على أكثر من بيئة أو Flavor.

توفر مكتبة dartdosh مجموعة من الوظائف التي تستهدف بشكل مباشر عملية Build وإدارة ملفات التطبيق.

وتوثيق المشروع يوضح أن الأداة تدعم Dart SDK 3.0 أو أحدث، مع وجود Flutter SDK مثبت على الجهاز، ويمكن تشغيلها على Mac وLinux وWindows. :contentReference[oaicite:2]{index=2}

على عكس كثير من مكتبات فلاتر التي تتم إضافتها إلى ملف pubspec.yaml، فإن dartdosh عبارة عن أداة CLI يتم تثبيتها بشكل Global من خلال Dart.

dart pub global activate dartdosh

بعد انتهاء عملية التثبيت يمكنك التأكد من أن الأمر أصبح متاحًا من خلال:

dartdosh --version

وفي حال لم يتعرف Terminal على الأمر، يمكنك إضافة مجلد Pub Cache إلى PATH. على Mac وLinux استخدم:

export PATH="$PATH:$HOME/.pub-cache/bin"

أما على Windows PowerShell:

$env:PATH += ";$env:USERPROFILE\.pub-cache\bin"

هذه الخطوات موثقة ضمن دليل DartDosh الرسمي. :contentReference[oaicite:3]{index=3}

بعد تثبيت الأداة انتقل إلى مجلد مشروع Flutter الخاص بك:

cd my_flutter_project

ثم قم بتشغيل:

dartdosh init

تقوم الأداة بتهيئة إعدادات المشروع وإنشاء مجلد خاص بالإعدادات، ويتضمن ملفات مثل build_config.json وإعدادات شخصية يمكن فصلها عن إعدادات الفريق. :contentReference[oaicite:4]{index=4}

في الإصدارات التي تستخدم النظام الحالي للإعدادات، يكون من المفيد الاحتفاظ بإعدادات البناء المشتركة للفريق بشكل منفصل عن الإعدادات الشخصية، خصوصًا عندما يحتوي المشروع على بيانات اعتماد أو إعدادات خاصة بكل مطور.

أبسط استخدام للأداة هو تشغيل Build لملف APK.

dartdosh build apk

هذا الاستخدام يشغّل عملية Flutter Build العادية بدون تحديد Environment.

ويمكن كذلك استخدام Production:

dartdosh build apk --production

أو استخدام الاختصار:

dartdosh build apk -p

وتتوفر اختصارات أخرى للبيئات:

# Production
dartdosh build apk --production
dartdosh build apk -p
dartdosh build apk -prod

# Staging
dartdosh build apk --staging
dartdosh build apk -s

# Development
dartdosh build apk --development
dartdosh build apk -d
dartdosh build apk -dev

توضح وثائق المشروع أن Environment تكون اختيارية، وفي حال عدم تحديدها يتم تنفيذ Flutter Build عادي بدون إدارة تلقائية للنسخة. :contentReference[oaicite:5]{index=5}

إذا كنت تريد إنشاء ملف AAB لرفع التطبيق إلى Google Play، يمكنك استخدام:

dartdosh build appbundle --production

كما يدعم DartDosh الاختصار aab لنفس نوع البناء:

dartdosh build aab --production

ويمكن كذلك استخدام Staging أو Development بحسب Flavors الموجودة في مشروعك. :contentReference[oaicite:6]{index=6}

يمكن استخدام DartDosh لإنشاء ملف IPA الخاص بتطبيقات iOS من خلال:

dartdosh build ipa --production

كما يمكنك إضافة Flags أخرى إلى الأمر، مثل:

dartdosh build ipa --production --split

وتدعم الأداة تمرير Flags إضافية إلى Flutter Build بحسب إعداد المشروع. :contentReference[oaicite:7]{index=7}

من أكثر الوظائف المفيدة في dartdosh إمكانية زيادة رقم Build تلقائيًا أثناء بناء Flavors.

افترض أن ملف pubspec.yaml يحتوي على:

version: 1.2.3+45

بعد تفعيل:

{
  "auto_increment_build_number": true
}

يمكن أن يتحول رقم Build تلقائيًا إلى:

version: 1.2.3+46

وهذا السلوك مرتبط باستخدام Environment في عملية البناء، بينما عمليات البناء العادية بدون Environment لا تقوم بتغيير رقم النسخة. :contentReference[oaicite:8]{index=8}

من المشاكل المتكررة في مشاريع Flutter كثرة الملفات الناتجة عن عمليات Build، خصوصًا عندما يكون لديك أكثر من Flavor وأكثر من نسخة.

تقوم dartdosh بإعادة تسمية الملفات باستخدام معلومات مثل البيئة ورقم الإصدار ورقم Build.

على سبيل المثال:

prod_1.2.3_46.apk
stg_2.0.0_12.ipa
dev_1.5.0_78.aab

كما يمكن أن تتضمن ملفات Split APK اسم المعمارية:

prod_1.2.3_46_arm64-v8a.apk
prod_1.2.3_46_armeabi-v7a.apk
prod_1.2.3_46_x86_64.apk

أما في حالة البناء بدون Environment فقد تكون أسماء الملفات مثل:

apk_1.2.3_46.apk
ipa_2.0.0_12.ipa
appbundle_1.5.0_78.aab

وهذه الطريقة تساعد على معرفة نسخة الملف ونوعه وبيئته مباشرة من اسم الملف. :contentReference[oaicite:9]{index=9}

يمكنك أيضًا تحديد مكان مخصص لحفظ ملفات البناء من خلال output_path.

على سبيل المثال:

{
  "project_name": "my_app",
  "output_path": "~/Desktop/dartdosh-builds"
}

عند استخدام هذا الخيار تقوم الأداة بتنظيم الملفات داخل مجلد المشروع ومجلدات منفصلة لكل نوع من أنواع Build.

dartdosh-builds/
└── my_app/
    ├── apk/
    │   ├── prod_1.0.0_100.apk
    │   └── dev_1.0.0_101.apk
    ├── ipa/
    │   └── prod_1.0.0_100.ipa
    └── aab/
        └── prod_1.0.0_100.aab

ويمكن أن يكون المسار Absolute أو Relative إلى مشروع Flutter، ويتم إنشاء المجلدات تلقائيًا عند الحاجة. :contentReference[oaicite:10]{index=10}

يمكن أن يحتوي ملف الإعدادات على أوامر مختلفة لكل نوع من أنواع البناء.

{
  "language": "en",
  "project_name": "my_app",
  "auto_increment_build_number": true,
  "output_path": "~/Desktop/dartdosh-builds",

  "apk": {
    "production": "flutter build apk --release --flavor production",
    "staging": "flutter build apk --release --flavor staging",
    "development": "flutter build apk --debug --flavor development"
  },

  "ipa": {
    "production": "flutter build ipa --release --flavor production",
    "staging": "flutter build ipa --release --flavor staging"
  },

  "appbundle": {
    "production": "flutter build appbundle --release --flavor production",
    "staging": "flutter build appbundle --release --flavor staging",
    "development": "flutter build appbundle --debug --flavor development"
  }
}

تسمح هذه الطريقة بجعل أوامر البناء الخاصة بالمشروع موجودة في مكان واحد، وهو أمر مفيد عندما يعمل أكثر من مطور على نفس مشروع Flutter. :contentReference[oaicite:11]{index=11}

لا تقتصر الأداة على تنفيذ الأوامر فقط، بل تحتوي أيضًا على نظام لرسائل Terminal متعددة اللغات.

حاليًا تدعم الأداة:

ويمكن تحديد اللغة من خلال:

{
  "language": "en"
}

وفي حال تم وضع لغة غير مدعومة، يتم الرجوع إلى English مع إظهار تحذير. :contentReference[oaicite:12]{index=12}

يمكن أيضًا استخدام DartDosh لأتمتة رفع ملفات IPA إلى App Store Connect بعد نجاح عملية Build.

يعتمد هذا الجزء على macOS وXcode، مع وجود تطبيق تم إنشاؤه في App Store Connect وإعدادات حساب Apple المناسبة.

ويمكن تفعيل الرفع التلقائي من خلال إعداد ipa_upload:

{
  "ipa_upload": {
    "enabled": true,
    "apple_id": "developer@example.com",
    "app_specific_password": "xxxx-xxxx-xxxx-xxxx"
  }
}

بعد ذلك يمكنك تشغيل:

dartdosh build ipa --production

وعند نجاح البناء يتم تجهيز ملف IPA ثم محاولة رفعه إلى App Store Connect باستخدام إعدادات الرفع المحددة. وتوضح الوثائق أن هذه الوظيفة تعتمد على أدوات Apple الرسمية مثل Transporter، وتتطلب macOS مع Xcode. :contentReference[oaicite:13]{index=13}

إذا كنت ترغب في إنشاء APKs منفصلة لكل ABI، توفر dartdosh اختصار --split.

dartdosh build apk --production --split

وتقوم الأداة بتحويل هذا الخيار إلى استخدام --split-per-abi في Flutter Build، مما يؤدي إلى إنشاء ملفات مختلفة لمعمارية الجهاز. :contentReference[oaicite:14]{index=14}

من المميزات المفيدة أن DartDosh لا يحصر المطور في الأوامر الأساسية فقط، بل يسمح بإضافة Flags أخرى إلى عملية البناء.

مثل:

dartdosh build apk --production --obfuscate

ويمكن كذلك استخدام --dart-define:

dartdosh build apk --production --dart-define=ENV=production

كما يمكن تمرير Flags أخرى يدعمها Flutter Build بحسب احتياجات المشروع. :contentReference[oaicite:15]{index=15}

إذا كان مشروع Flutter يحتوي على Flavors مثل:

فإن DartDosh تصبح مفيدة في توحيد أوامر البناء لكل بيئة.

على سبيل المثال يمكن استخدام:

dartdosh build apk -d
dartdosh build apk -s
dartdosh build apk -p

وبذلك يصبح من السهل تنفيذ Build لكل بيئة دون الحاجة إلى كتابة أوامر Flutter الكاملة في كل مرة.

لنفترض أن لدينا مشروع Flutter يحتوي على ثلاث بيئات:

development
staging
production

وأن الإصدار الحالي هو:

version: 2.4.0+100

يمكن تشغيل Production:

dartdosh build apk --production

مع تفعيل زيادة Build Number، يمكن أن يصبح الإصدار:

version: 2.4.0+101

ويتم حفظ الملف باسم منظم مثل:

prod_2.4.0_101.apk

وإذا استخدمت Split APK فقد تحصل على:

prod_2.4.0_101_arm64-v8a.apk
prod_2.4.0_101_armeabi-v7a.apk
prod_2.4.0_101_x86_64.apk

بهذه الطريقة يمكن تقليل عدد الخطوات اليدوية المطلوبة أثناء تجهيز نسخ المشروع. :contentReference[oaicite:16]{index=16}

عند الحديث عن مكتبات فلاتر وأدوات Flutter، غالبًا ما يكون التركيز على Widgets أو Packages التي تضيف وظيفة داخل التطبيق، ولكن أدوات CLI مثل dartdosh تستهدف جانبًا مختلفًا وهو دورة بناء التطبيق وتجهيزه للتوزيع.

فهي لا تضيف Widget جديدة إلى التطبيق، وإنما تعمل من خلال Terminal وتساعد المطور على تنظيم عملية Build وإدارة النسخ والملفات بطريقة أكثر وضوحًا.

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

من المهم الانتباه إلى أن إصدارات dartdosh السابقة شهدت تغييرًا أمنيًا متعلقًا بميزة Telegram.

في الإصدار 0.9.0 تمت إزالة بيانات اعتماد Telegram المشتركة التي كانت موجودة ضمن الإصدارات السابقة، وأصبح استخدام الرفع إلى Telegram يعتمد على بيانات اعتماد يملكها المستخدم نفسه من خلال إعداد خاص به. كما أضيفت أوامر مثل:

dartdosh telegram setup

dartdosh telegram status

وذلك بعد إلغاء الـ Shared Telegram Bot السابق. لذلك عند استخدام ميزة Telegram يجب الاعتماد على تعليمات الإصدار الحالي بدلًا من نسخ إعدادات قديمة من مقالات أو مشاريع سابقة. :contentReference[oaicite:17]{index=17}

مكتبة dartdosh ليست مكتبة UI تقليدية، وإنما أداة CLI تم تصميمها لمساعدة مطوري Flutter على أتمتة عمليات Build وإدارة الإصدار وتنظيم الملفات الناتجة.

يمكن من خلالها تنفيذ Build لملفات APK وIPA وAAB، والتعامل مع Flavors مثل Production وStaging وDevelopment، وزيادة Build Number تلقائيًا، وإعادة تسمية الملفات، ونقلها إلى مجلدات منظمة، مع دعم عدد من Flutter Build Flags. :contentReference[oaicite:18]{index=18}

كما توفر الأداة تكاملات مرتبطة بالتوزيع، ومن أبرزها رفع IPA إلى App Store Connect، وهو ما يجعلها مفيدة في المشاريع التي تتكرر فيها عمليات الإصدار بشكل مستمر.

إذا كنت تعمل على مشروع Flutter يحتوي على أكثر من Flavor أو تقوم ببناء نسخ التطبيق بشكل متكرر، فإن dartdosh يمكن أن تكون أداة عملية لتقليل الأوامر اليدوية وتنظيم عملية تجهيز الإصدارات.

# تثبيت dartdosh
dart pub global activate dartdosh

# التحقق من الإصدار
dartdosh --version

# الانتقال إلى مشروع Flutter
cd my_flutter_project

# تهيئة المشروع
dartdosh init

# بناء APK
dartdosh build apk

# Production
dartdosh build apk --production

# Production باختصار
dartdosh build apk -p

# Staging
dartdosh build apk --staging

# Development
dartdosh build apk --development

# بناء App Bundle
dartdosh build appbundle --production

# بناء IPA
dartdosh build ipa --production

# إنشاء Split APKs
dartdosh build apk --production --split

# Obfuscation
dartdosh build apk --production --obfuscate

# dart-define
dartdosh build apk --production --dart-define=ENV=production

{
  "language": "en",
  "project_name": "my_app",
  "auto_increment_build_number": true,
  "output_path": "~/Desktop/dartdosh-builds",

  "apk": {
    "production": "flutter build apk --release --flavor production",
    "staging": "flutter build apk --release --flavor staging",
    "development": "flutter build apk --debug --flavor development"
  },

  "ipa": {
    "production": "flutter build ipa --release --flavor production",
    "staging": "flutter build ipa --release --flavor staging"
  },

  "appbundle": {
    "production": "flutter build appbundle --release --flavor production",
    "staging": "flutter build appbundle --release --flavor staging",
    "development": "flutter build appbundle --debug --flavor development"
  },

  "ipa_upload": {
    "enabled": false,
    "apple_id": "",
    "app_specific_password": ""
  }
}