Dart: تركيب بيئة التطوير والأدوات في Dart — من تثبيت SDK

# 5 دقائق لتبدأ — كل ما تحتاجه
$ brew install dart  # macOS
$ dart --version     # Dart SDK version 3.4.0
$ dart create hello_dart
$ cd hello_dart && dart run
Hello, world!*

قبل: 2 أيام من الإحباط ← استسلام 60%
بعد: 5 دقائق من التثبيت ← كتابة 10 دقائق "Hello World"
ROI: 288 مرة أسرع في التثبيت

# التحديث أولاً
$ brew update

# تثبيت Dart
$ brew install dart

# التحقق
$ dart --version
Dart SDK version 3.4.0 (stable)

# تنزيل من الموقع الرسمي
$ curl -O https://storage.googleapis.com/dart-archive/channels/stable/release/3.4.0/sdk/dartsdk-macos-x64-release.zip

# فك الضغط
$ unzip dartsdk-macos-x64-release.zip -d /opt

# تكوين PATH (zsh: ~/.zshrc، bash: ~/.bash_profile)
$ echo 'export PATH="/opt/dart-sdk/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

# التحقق
$ dart --version

> choco install dart-sdk

# أو winget
> winget install Dart.DartSDK

> dart --version
Dart SDK version 3.4.0 (stable)

# 1. إضافة مفتاح GPG
$ wget -qO- https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /usr/share/keyrings/dart.gpg

# 2. إضافة مستودع APT
$ echo 'deb [signed-by=/usr/share/keyrings/dart.gpg arch=amd64] https://storage.googleapis.com/download.dart.tv/linux/debian stable main' | sudo tee /etc/apt/sources.list.d/dart_stable.list

# 3. التثبيت
$ sudo apt update
$ sudo apt install dart

# 4. تكوين PATH
$ echo 'export PATH="/usr/lib/dart/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc

# التحقق
$ dart --version

# بعد التثبيت، نفّذ هذه الأوامر للتحقق
$ dart --version
Dart SDK version 3.4.0 (stable)         # ✅ الإصدار صحيح

$ dart doctor
[✓] Dart (version 3.4.0)                # ✅ Dart نفسها
[✓] Pub (version 3.4.0)                 # ✅ مدير الحزم
[✓] Dart Analysis Server                # ✅ خدمة تحليل الكود
[✓] Connected Devices                  # ✅ الاتصال بالأجهزة
[✓] HTTP connectivity                  # ✅ اتصال الشبكة

# إذا رأيت [✗]، يجب إصلاح المشكلة قبل المتابعة

> **الإخراج:** كل التحققات [✓] تعني أن البيئة جاهزة للتطوير. أي [�] يحتاج إصلاح قبل كتابة كود Dart.

# 1. تنزيل VS Code: https://code.visualstudio.com/
# 2. التثبيت
$ sudo snap install code --classic  # Linux

# 3. تثبيت امتدادات Dart
$ code --install-extension Dart-Code.dart-code
$ code --install-extension Dart-Code.flutter

{
  "dart.sdkPath": "/usr/lib/dart",
  "editor.formatOnSave": true,
  "editor.tabSize": 2,
  "editor.rulers": [80, 100],
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "[dart]": {
    "editor.tabSize": 2,
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "Dart-Code.dart-code"
  }
}

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Dart",
      "type": "dart",
      "request": "launch",
      "program": "bin/main.dart"
    },
    {
      "name": "Dart (attach)",
      "type": "dart",
      "request": "attach"
    }
  ]
}

# 1. إنشاء مجلد المشروع
$ mkdir -p ~/projects/hello_dart
$ cd ~/projects/hello_dart

# 2. تهيئة مشروع Dart
$ dart create -t console-full .
$ ls
analysis_options.yaml  bin/  lib/  pubspec.yaml  test/

# 3. فتح VS Code
$ code .

# 4. تعديل bin/main.dart
$ cat bin/main.dart
void main(List<String> arguments) {
  print('Hello, Dart!');
}

> **الإخراج:** هيكل المشروع الكامل:
> - `bin/main.dart` — نقطة دخول البرنامج
> - `lib/` — ملفات المكتبة
> - `test/` — ملفات الاختبار
> - `pubspec.yaml` — تكوين التبعيات
> - `analysis_options.yaml` — تكوين linter

# تشغيل البرنامج مباشرة
$ dart run
Hello, Dart!

# تشغيل ملف محدد
$ dart run bin/main.dart

# تشغيل في وضع hot reload (لـ Flutter)
$ dart run --observe

# تمرير معاملات سطر الأوامر
$ dart run bin/main.dart arg1 arg2

# الترجمة إلى AOT أصلي
$ dart compile exe bin/main.dart -o build/hello
$ ./build/hello
Hello, Dart!

# الترجمة إلى JavaScript
$ dart compile js bin/main.dart -o build/hello.js
$ node build/hello.js
Hello, Dart!

# الترجمة إلى AOT kernel (حجم أصغر، أبطأ)
$ dart compile aot-snapshot bin/main.dart

# تنسيق ملف واحد
$ dart format bin/main.dart
Formatted 1 file in 0.05s.

# تنسيق المشروع بأكمله
$ dart format .

# التحقق من التنسيق دون تعديل
$ dart format --output=none --set-exit-if-changed .
# الإرجاع 0 إذا كان منسقًا، 1 إذا احتاج إلى تنسيق

# إعدادات مخصصة (.dart_tool/dartfmt.cfg)
$ cat .dart_tool/dartfmt.cfg
line-length=100

# التحليل الأساسي
$ dart analyze
Analyzing hello_dart...
No issues found!

# عند وجود أخطاء
$ dart analyze lib/calculator.dart
error • The argument type 'String' can't be assigned to the parameter type 'int' • calculator.dart:10:5

# أنواع المشاكل
$ dart analyze --show=type
# info: تلميحات أسلوب
# warning: مشكلات محتملة
# error: أخطاء لا يمكن تشغيلها

# 1. إنشاء مشروع جديد
$ dart create my_app
$ cd my_app

# 2. تشغيل البرنامج (تعديل bin/main.dart أولاً)
$ dart run
Hello, world!

# 3. التحقق من الكود
$ dart analyze
No issues found!

# 4. تنسيق الكود
$ dart format .

# 5. تشغيل الاختبارات
$ dart test
+00:00 ✓ All tests passed!

# 6. ترجمة إلى ثنائي إنتاجي
$ dart compile exe bin/main.dart -o build/my_app
$ ./build/my_app
Hello, world!

> **الإخراج:** سير العمل اليومي الكامل: تطوير → فحص → تنسيق → اختبار → نشر. كل أمر يخدم غرضًا محددًا.

# تهيئة مشروع جديد
$ dart pub get

# إضافة تبعية
$ dart pub add http
Resolving dependencies...
+ http 1.2.0
Changed 1 dependency in my_app!

# إضافة تبعية تطوير
$ dart pub add --dev test

# ترقية التبعيات
$ dart pub upgrade

# عرض الحزم المثبتة
$ dart pub deps

# pubspec.yaml — مركز تكوين مشروع Dart
name: hello_dart
description: "تطبيق Dart الأول من Bob"
version: 1.0.0
publish_to: none  # لا تنشر على pub.dev

environment:
  sdk: ^3.4.0      # تبعية إصدار Dart SDK

dependencies:
  # الحزم التي يحتاجها وقت التشغيل
  http: ^1.2.0
  args: ^2.4.2

dev_dependencies:
  # تبعيات التطوير والاختبار فقط
  test: ^1.24.0
  lints: ^3.0.0

# بناء جملة ضبط الإصدار: ^major.minor.patch
dependencies:
  http: ^1.2.0    # ≥ 1.2.0 < 2.0.0
  args: ^2.4.2    # ≥ 2.4.2 < 3.0.0
  collection: ^1.18.0

# pubspec.yaml لمشروع Bob DataPipeline
name: data_pipeline
description: "أداة معالجة بيانات التجارة الإلكترونية متعددة المنصات"
version: 0.1.0
publish_to: none

environment:
  sdk: ^3.4.0

dependencies:
  args: ^2.4.2       # تحليل معاملات CLI
  http: ^1.2.0      # طلبات HTTP
  path: ^1.9.0      # معالجة مسارات الملفات
  csv: ^6.0.0       # تحليل/تسلسل CSV
  json_annotation: ^4.9.0  # تعليقات JSON

dev_dependencies:
  test: ^1.24.0
  lints: ^3.0.0
  coverage: ^1.7.0

// bin/main.dart
void main() {
  print('Hello, Dart!');
}

$ dart run
Hello, Dart!

// bin/main.dart
void main(List<String> arguments) {
  print('مرحبًا، Dart!');
  print('معاملات سطر الأوامر: ${arguments.length}');

  for (var i = 0; i < arguments.length; i++) {
    print('  [$i]: ${arguments[i]}');
  }
}

$ dart run arg1 arg2 --flag value
مرحبًا، Dart!
معاملات سطر الأوامر: 4
  [0]: arg1
  [1]: arg2
  [2]: --flag
  [3]: value

// bin/main.dart
import 'package:args/args.dart';

void main(List<String> arguments) {
  final parser = ArgParser()
    ..addOption('name', abbr: 'n', defaultsTo: 'World')
    ..addFlag('verbose', abbr: 'v');

  final results = parser.parse(arguments);
  final name = results['name'] as String;
  final verbose = results['verbose'] as bool;

  if (verbose) {
    print('الوضع المفصّل مُمكّن');
  }
  print('مرحبًا، $name!');
}

$ dart run
مرحبًا، World!

$ dart run --name Bob
مرحبًا، Bob!

$ dart run --verbose --name Alice
الوضع المفصّل مُمكّن
مرحبًا، Alice!

// bin/main.dart
int fibonacci(int n) {
  if (n < 2) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

void main() {
  final n = 10;
  print('fibonacci($n) = ${fibonacci(n)}');
}

> **الإخراج:** fibonacci(10) = 55
> يساعد التصحيح في فهم التنفيذ العودي لـ fibonacci، وهو أداة تعليمية رائعة.

// مشروع DataPipeline لـ Bob
import 'package:args/args.dart';

void main(List<String> arguments) {
  final parser = ArgParser()
    ..addOption('input', abbr: 'i', help: 'مسار ملف البيانات')
    ..addOption('output', abbr: 'o', help: 'مسار الإخراج')
    ..addFlag('verbose', abbr: 'v');

  final results = parser.parse(arguments);

  print('=== DataPipeline Starter ===');
  print('الإدخال: ${results['input']}');
  print('الإخراج: ${results['output']}');
  print('المفصّل: ${results['verbose']}');
}

$ dart run --input data.csv --output result.json --verbose
=== DataPipeline Starter ===
الإدخال: data.csv
الإخراج: result.json
المفصّل: true

> **الإخراج:** مشروع CLI بسيط يقبل معاملات سطر الأوامر ويطبع الإعدادات. هذا هو أساس خط أنابيب البيانات الذي ستوسعه طوال المسار التعليمي.

# المشكلة
$ dart --version
zsh: command not found: dart

# الحل 1: تكوين PATH
$ echo 'export PATH="/opt/dart-sdk/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

# الحل 2: استخدام المسار الكامل
$ /opt/dart-sdk/bin/dart --version

# الحل 3 (macOS Homebrew): إعادة التثبيت
$ brew reinstall dart

# المشكلة: انقطاع الاتصال بـ pub.dev
$ dart pub get
Resolving dependencies...
Got socket error trying to find package ... at https://pub.dev.

# الحل 1: تكوين مرآة محلية
$ export PUB_HOSTED_URL=https://pub.flutter-io.cn
$ dart pub get

# الحل 2: استخدام VPN
# أو تكوين proxy الشركات

# المشكلة: تعارض إصدارات الحزم
$ dart pub get
Because my_app depends on http ^1.0.0 which requires SDK version ^3.0.0,
and my_app depends on http ^2.0.0 which requires SDK version ^3.4.0,
version solving failed.

# الحل: ترقية حزم التبعيات
$ dart pub upgrade
# أو تعديل pubspec.yaml يدويًا
$ vim pubspec.yaml
$ dart pub get

# المشكلة: VS Code لا يمكنه الاتصال بـ Dart Analysis Server
# الحل 1: إعادة تشغيل Dart Analysis Server
# Ctrl+Shift+P → "Dart: Restart Analysis Server"

# الحل 2: التحقق من sdkPath
# settings.json → dart.sdkPath

# الحل 3: مسح ذاكرة التخزين المؤقت
$ rm -rf .dart_tool
$ dart pub get

# تثبيت fvm
$ dart pub global activate fvm

# تثبيت إصدارات متعددة
$ fvm install 3.0.0
$ fvm install 3.4.0

# تبديل الإصدار لكل مشروع
$ fvm use 3.4.0

analyzer:
  exclude:
    - "**/*.g.dart"