1. ما هي مكتبة R.swift ولماذا تحتاجها؟

R.swift هي مكتبة قوية للغة Swift توفر وصولاً آمنًا من حيث النوع (type-safe) إلى موارد تطبيقك على iOS/macOS/tvOS/watchOS. بدلاً من استخدام النصوص الحرفية (string literals) للإشارة إلى الصور والخطوط والألوان والنصوص المترجمة والموارد الأخرى، تقوم R.swift بتوليد هياكل (structs) محددة الأنواع لها. هذا يعني أن المترجم (compiler) يمكنه التحقق من صحة اسم المورد في مرحلة الترجمة، وليس أثناء تشغيل التطبيق.

لماذا تحتاجها؟ في التطوير التقليدي لمنصة Apple، غالباً ما تكتب كوداً مثل UIImage(named: "myImage") أو NSLocalizedString("hello_key", comment: ""). إذا أخطأت في كتابة اسم الملف أو مفتاح الترجمة، سيتعطل التطبيق فقط أثناء التشغيل. R.swift تحل هذه المشكلة بشكل جذري: بعد توليد الكود، تصل إلى الموارد كخصائص لهياكل مولدة. على سبيل المثال: R.image.myImage أو R.string.localizable.helloKey(). سيشير المترجم فوراً إلى أي مورد غير موجود، وسيقدم لك Xcode الإكمال التلقائي (autocomplete).

علاوة على ذلك، تتعامل R.swift تلقائياً مع Asset Catalogs وملفات .strings و.storyboard و.xib و.json و.plist والخطوط والألوان وحتى ملفات البيانات (Data). هذا يجعل الكود أنظف وأكثر أماناً ويسرّع التطوير بشكل كبير بفضل الإكمال التلقائي في Xcode. المكتبة مدعومة بنشاط من المجتمع وتُستخدم في آلاف المشاريع حول العالم.

2. طريقة التثبيت

يتم تثبيت R.swift عبر Swift Package Manager (SPM) أو CocoaPods. نوصي باستخدام SPM لأنه المعيار الحديث لمشاريع Swift.

التثبيت عبر Swift Package Manager (SPM)

أضف الحزمة إلى مشروعك من خلال Xcode:

1. افتح مشروعك في Xcode.
2. اذهب إلى File > Add Packages....
3. الصق الرابط: https://github.com/mac-cain13/R.swift
4. اختر الإصدار (يُفضل الأحدث المستقر) واضغط Add Package.
5. تأكد من إضافة الحزمة إلى الهدف الرئيسي (main target) الخاص بك.

يمكنك أيضاً الإضافة يدوياً في ملف Package.swift:

// swift-tools-version:5.7
import PackageDescription

let package = Package(
    name: "YourProject",
    dependencies: [
        .package(url: "https://github.com/mac-cain13/R.swift", from: "7.0.0")
    ],
    targets: [
        .target(
            name: "YourTarget",
            dependencies: [
                .product(name: "RswiftLibrary", package: "R.swift")
            ]
        )
    ]
)

التثبيت عبر CocoaPods

إذا كنت تستخدم CocoaPods، أضف في ملف Podfile:

platform :ios, '13.0'
use_frameworks!

target 'YourApp' do
  pod 'R.swift', '~> 7.0'
end

ثم نفّذ الأمر:

pod install

إعداد Build Phase (إلزامي!)

بعد التثبيت، يجب إضافة Run Script Phase في Build Phases للهدف الخاص بك:

1. اذهب إلى Build Phases للهدف الخاص بك.
2. اضغط + واختر New Run Script Phase.
3. اسحب هذه المرحلة لتكون قبل مرحلة Compile Sources.
4. في حقل النص البرمجي، الصق:

"$PODS_ROOT/R.swift/rswift" generate "$SRCROOT/R.generated.swift"

إذا كنت تستخدم SPM، سيكون النص البرمجي كالتالي:

"${BUILD_DIR%/Build/*}/SourcePackages/checkouts/R.swift/rswift" generate "$SRCROOT/R.generated.swift"

بعد بناء المشروع، سيتم توليد ملف R.generated.swift. أضفه إلى مشروعك (لا تنسَ سحبه إلى قائمة الملفات).