multi_unzip #

أداة بسيطة لاستخراج الملفات المضغوطة (ZIP, RAR) في Flutter مع دعم متعدد الخيوط للملفات الكبيرة.

• Android: فك RAR عبر FFI وبناء مكتبة أصلية libunrar.so تلقائيًا (NDK/CMake).
• Windows: فك RAR عبر أدوات النظام (مثل unrar.exe) أو بدائل موجودة، وZIP/TAR/GZ عبر Dart.
• ZIP/TAR/GZ: عبر حزمة archive (Pure Dart) على جميع المنصات.

✨ المميزات #

• [منصات] Android، Windows (ودعم أنظمة إضافية لاحقًا).
• [صيغ] zip، rar، tar، gz.
• [واجهة موحدة] استدعاء واحد MultiUnzip.extract(...) يحدد النوع تلقائيًا.
• [ملفات كبيرة] دعم الملفات الكبيرة مع تعريفات بناء مناسبة على أندرويد.
• [إعدادات بناء محسّنة] تضمين رؤوس UnRAR عبر ${UNRAR_DIR} لضمان ترجمة صحيحة لملفات مثل coder.cpp.

📦 المتطلبات #

• على Android:
  • Android SDK + NDK + CMake مثبتة في بيئة التطوير لديك.
  • Gradle سيبني libunrar.so لواجهات ABI: armeabi-v7a، arm64-v8a (قابلة للتوسعة).
• على Windows:
  • لفك RAR قد تحتاج وجود unrar.exe في المسار PATH (إن تعذّر المسار الافتراضي).

🔧 التثبيت #

أضف إلى pubspec.yaml في تطبيقك:

dependencies:
  multi_unzip: ^2.0.4

ملاحظات هامة على الكود الأصلي (Native Code) #

• توافقية NDK/Clang: تم إجراء تعديلات على الكود الأصلي (UnRAR) لضمان التوافقية الكاملة مع مُجمّع Android NDK/Clang الحديث.
• دمج الدوال المضمنة: تم نقل تعريفات الدوال المضمنة (inline functions) من unpackinline.cpp إلى ملف الرأس unpack.hpp واستبعاد unpackinline.cpp من عملية البناء.
• تعطيل تعدد المهام: تم تعطيل بناء ملف تعدد المهام unpack50mt.cpp ضمن إعدادات CMakeLists.txt لـ Android لتجنب الأخطاء المتعلقة بالـ Threading في بيئة NDK.

ثم نفّذ:

flutter pub get

ملاحظة: الحزمة تعتمد على Flutter (Plugin مع FFI لأندرويد) وعلى ffi وarchive داخليًا.

🚀 الاستخدام السريع #

import 'package:multi_unzip/multi_unzip.dart';

Future<void> demo() async {
  await MultiUnzip.extract(
    sourcePath: '/path/to/archive.rar',
    destinationDir: '/path/to/output',
  );
}

🚢 النشر على pub.dev (للمطورين) #

• تأكد من تحديث version في pubspec.yaml.

• يوصى بإضافة أحد الحقلين لإزالة التحذير:

  • repository: https://github.com/<username>/multi_unzip
  • أو homepage: https://github.com/<username>/multi_unzip

• أوامر سريعة:

  flutter pub get
  flutter pub publish --dry-run
  flutter pub publish
  

• يحدد MultiUnzip النوع تلقائيًا من الامتداد (.zip/.rar/.tar/.gz).

• على Android، يتم فك RAR عبر FFI لمكتبة أصلية مبنية تلقائيًا.

• على منصات أخرى، يتم استخدام المسارات البديلة المجهزة (Pure Dart لـ ZIP/TAR/GZ، وبدائل RAR حيث أمكن).

🧩 تفاصيل المنصات #

• Android (RAR):

  • يتم تحميل libunrar.so واستدعاء دالة أصلية عبر dart:ffi.
  • يتطلب NDK/CMake في بيئة البناء. لا يلزم أي إعداد إضافي في مشروعك، فإعلان ffiPlugin: true يعتني بالبناء.

• Windows (RAR):

  • محاولة استخدام أدوات النظام (مثل unrar.exe). تأكد من توفرها في PATH عند الضرورة.

• جميع المنصات (ZIP/TAR/GZ):

  • باستخدام حزمة archive (Pure Dart)، لا يلزم تبعيات أصلية.

❗ ملاحظات #

• ملفات RAR المحمية بكلمة مرور غير مدعومة حاليًا في مسار FFI الافتراضي.
• الالتزام بالرخصة الخاصة بـ UnRAR مطلوب عند توزيع تطبيقاتك. راجع native/unrar/unrar/license.txt.
• تم ضبط مسار تضمين الرؤوس (headers) إلى جذر UnRAR عبر target_include_directories(unrar PRIVATE ${UNRAR_DIR}) لضمان ترجمة ملفات مثل coder.cpp بشكل صحيح.
• تم استثناء ملف dll.cpp من البناء على أندرويد لتجنب مشاكل الربط الخاصة بـ RARDLL.
• تم إضافة تضمين الرؤوس #include "rar.hpp" في unpack50.cpp, unpack50frag.cpp, unpack50mt.cpp ضمن هذا الإصدار.
• تم نقل تعريفات unpackinline.cpp إلى unpack.hpp كـ inline، واستبعاد الملف من البناء.
• تم تعطيل unpack50mt.cpp (وضع التعددية MT) في إعدادات CMake لأندرويد.

🧪 مثال أكثر تفصيلاً #

import 'dart:io';
import 'package:multi_unzip/multi_unzip.dart';

Future<void> extractExample() async {
  final src = Platform.isAndroid
      ? '/sdcard/Download/sample.zip'
      : 'C:/Users/you/Downloads/sample.zip';
  final out = Platform.isAndroid
      ? '/sdcard/Download/output'
      : 'C:/Users/you/Downloads/output';

  await MultiUnzip.extract(sourcePath: src, destinationDir: out);
}

🐞 استكشاف الأخطاء الشائعة #

• تأكد من وجود مساحة كافية للكتابة في destinationDir.
• على Android، إن واجهت خطأ في FFI:
  • تحقق من توافر NDK/CMake في بيئة Android SDK لديك.
  • حاول flutter clean && flutter pub get ثم أعد البناء.
• على Windows، إن فشل فك RAR:
  • تحقق من توفر unrar.exe في PATH أو ثبّته من موقعه الرسمي.

📝 سجل التغييرات (Changelog) #

• 1.1.0:
  • إضافة دعم فك RAR على Android عبر FFI وبناء libunrar.so تلقائيًا.
  • الحفاظ على فك ZIP/TAR/GZ عبر archive (Pure Dart).
  • تحسين واجهة الاستخدام الموحدة MultiUnzip.extract.

📄 الرخصة #

راجع ملف LICENSE. كود UnRAR يخضع لرخصته الخاصة والمشمولة مع المصادر ضمن native/unrar/unrar/.