عرض مصدر Kotlin/multiplatform

<noinclude>{{DISPLAYTITLE:المشاريع متعددة المنصات (Multiplatform) في لغة Kotlin}}</noinclude>
'''ملاحظة:''' ما تزال ميّزة تعدّد منصّات العمل تجريبيّة في الإصدار Kotlin 1.2 وبالتالي فإن ما تحتويه هذه الصفحة قد يخضع للتغيير في إصدارات Kotlin القادمة.

يسمح مشروع Kotlin متعدّد المنصّات بترجمة الشيفرة ذاتها إلى عدّة منصّاتٍ للعمل (platforms)، وتدعم Kotlin حاليًا البيئات: JVM و JavaScript بالإضافة إلى Native والتي لا زلت قيد التطوير وستُضاف رسميًا فيما بعد.

== بُنية المشروع متعدّد المنصّات (Multiplatform Project Structure) ==
يتألف من ثلاثة أنواع من الوحدات (modules):
* '''الوحدة المشتركة (common module)''': تحتوي على الشيفرة العامّة التي لا تتبع لمنصّة عمل مُحدَّدة، بالإضافة إلى التصريحات التي ليس لها تعريف استخدامٍ (implementations) للواجهات API بحسب المنصّة، إذ تسمح هذه التصريحات للشيفرة المشتركة بالاعتماد على تعريفات الاستخدام الخاصّة بالمنصّة.

* '''وحدة المنصّة ( platform module)''': تتضمن تعاريف الاستخدام (implementations) للتصريحات الواردة في الوحدة المشتركة وذلك بحسب منصّة العمل الحاليّة، بالإضافة إلى الشيفرة التي تتناسب مع هذه المنصّة، وتكون وحدة المنصّة دائمًا بمثابة تعريف الاستخدام لواحدةٍ -فقط- من الوحدات المشتركة.

* '''الوحدة النظاميّة (regular module):''' تستهدف منصّةً معيّنةً وإما أن تكون تابعةً (dependency) لوحدات المنصّة أو أن تعتمد عليها.
ويمكن أن تعتمد الوحدة المشتركة على وحداتٍ مشتركةٍ أخرى وبعض المكتبات فقط، متضمنةً الإصدار المشترك من المكتبة القياسيّة في Kotlin‏ (<code>kotlin-stdlib-common</code>)، وتحتوي على شيفرة Kotlin فقط ولا يُسمح بوجود شيفرة أيّ لغةٍ أخرى ضمنها.

أمّا وحدة المنصّة فهي تعتمد على أيّ وحدةٍ أخرى بالإضافة إلى المكتبات المُتاحة في المنصّة المستهدفة (أي مكتبات Java عند العمل في بيئة Kotlin/JVM ومكتبات JS عند العمل في بيئة Kotlin/JS)، إذ تشمل بيئة Kotlin/JVM أيّ لغة برمجةٍ متوافقةٍ مع JVM ولا تقتصر على لغة Java وحسب.

سينتُج عن ترجمة (compiling) الشيفرة الموجودة في الوحدة المشتركة ملفٌ بمعلوماتٍ توصيفيّةٍ (metadata) تشمل كافّة التصريحات الموجودة في الوحدة، أمّا ترجمة وحدة المنصّة فستنتِج شيفرةً خاصّة بالمنصّة المستهدفة (أي bytecode في حالة JVM وشيفرة مصدرية [source code] في حالة JavaScript)، وتكون هذه الشيفرة ناتجةً عن الشيفرة في وحدة المنصّة والوحدة المشتركة التي يُعرَّف استخدامها (implemented).

وبالتالي فإنّ كلّ مكتبةٍ متعدّدة المنصّات يجب تكون موزّعةً على شكل مجموعاتٍ من الأدوات، وهي عبارة عن ملف ‎.jar مشتركٍ يحتوي على البيانات التوصيفيّة للشيفرة المشتركة، بالإضافة إلى ملفات ‎.jar (مخصَّصة المنصّة) والتي تحتوي على تعريف الاستخدام المُترجَم (compiled implementation) لكلِّ منصّة.

== إعداد مشروعٍ متعدّد المنصّات (Setting Up a Multiplatform Project) ==
يجب إعداد المشروع باستخدام نظام Gradle في الإصدار Kotlin 1.2 إذ لا يتوفر الدعم لأيّ نظام بناءٍ آخر غيره، فلإنشاء مشروعٍ جديدٍ يجب تحديد الخيار "Kotlin (Multiplatform)‎" الموجود تحت مسمّى "Kotlin" في مربع الحوار "New Project" (مشروع جديد)، وسيُنشَأ مشروعٌ جديدٌ يحتوي على ثلاث وحدات (modules): الوحدة المشتركة ووحدتين لبيئتيّ JVM و JS، ولإضافة المزيد من الوحدات اختر أحد الخيارات من "Kotlin (Multiplatform)‎" الموجودة تحت المُسمّى Gradle في مربع الحوار "New Module" (وحدة جديدة).

أمّا عند الحاجة لضبط إعدادت المشروع يدويًا فيجب القيام بالخطوات الآتية:
# أضف الإضافة (plugin)‏ Kotlin Gradle إلى مسار صنف نصّ البناء (buildscript classpath):‏ <code>classpath‎ "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"</code>.
# - طبِّق الإضافة <code>kotlin-platform-common</code> على الوحدة المشتركة.
# - طبق الإضافات <code>kotlin-platform-jvm</code> و <code>kotlin-platform-android</code> و  <code>kotlin-platform-js</code> على وحدات المنصّة لكلِّ من  JVM و Android و JS على الترتيب.
# - أضف بعض الاعتماديّات (dependencies) بالمجال <code>expectedBy</code> من وحدات المنصّة إلى الوحدة المشتركة.
ويوضح المثال الآتي ملفًا كاملًا (<code>build.gradle</code>) للوحدة المشتركة بالإصدار Kotlin 1.2-Beta :<syntaxhighlight lang="kotlin">
buildscript {
    ext.kotlin_version = '1.2.30'

    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

apply plugin: 'kotlin-platform-common'

repositories {
    mavenCentral()
}

dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib-common:$kotlin_version"
    testCompile "org.jetbrains.kotlin:kotlin-test-common:$kotlin_version"
}
</syntaxhighlight>كما يوضِّح المثال الآتي ملفًا كاملًا <code>build.gradle</code> لوحدة منصّة JVM  (لاحظ السطر <code>expectedBy</code> الموجود في بُنية <code>dependencies</code>):<syntaxhighlight lang="kotlin">
buildscript {
    ext.kotlin_version = '1.2.30'

    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

apply plugin: 'kotlin-platform-jvm'

repositories {
    mavenCentral()
}

dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
    expectedBy project(":")
    testCompile "junit:junit:4.12"
    testCompile "org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version"
    testCompile "org.jetbrains.kotlin:kotlin-test:$kotlin_version"
}
</syntaxhighlight>

== التصريحات المُخصَّصة لمنصَّة العمل (Platform-Specific Declarations) ==
إنّ من إحدى المميّزات القويّة في Kotlin هو أنّ الشيفرة متعدّدة المنصّات تسمح للشيفرة المشتركة بالاعتماد على تصريحاتٍ مُخصَّصةٍ للمنصّة، وسيتطلَّب هذا في لغات البرمجة الأخرى بناء مجموعةٍ من الواجهات في الشيفرة المشتركة وتعريف استخدامها (implementing) في وحدات المنصّة، ولكن بالمقابل لا تكون هذه الطريقة مثاليةً في بعض الحالات عند وجود مكتبةٍ في إحدى المنصّات التي تعرِّف استخدام الوظائف (functionality) المطلوبة، ومن الأفضل استخدام الواجهة (API) من هذه المكتبة مباشرةً بدون أي مغلِّفات إضافيّة (extra wrappers)، كما يجب أيضًا التعبير عن التصريحات المشتركة كواجهاتٍ (interfaces)  لا تشمل كافّة الحالات الممكنة.

توفِّر Kotlin -كبديلٍ عن ذلك- آليّة التصريحات المتوقَّعة (expected) والفعليّة (actual) حيث تعرِّف الوحدة المشتركة بعض التصريحات المتوقَّعة، وتعرِّف وحدة المنصّة التصريحات الفعليّة للتصريحات المتوقّعة في الوحدة المشتركة، ويتَّضح ذلك عبر المثال الآتي (وهو جزءٌ من الوحدة المشتركة):<syntaxhighlight lang="kotlin">
package org.jetbrains.foo

expect class Foo(bar: String) {
    fun frob()
}

fun main(args: Array<String>) {
    Foo("Hello").frob()
}
</syntaxhighlight>وهذه شيفرة الوحدة الموافقة للشيفرة السابقة في JVM:<syntaxhighlight lang="kotlin">
package org.jetbrains.foo

actual class Foo actual constructor(val bar: String) {
    actual fun frob() {
        println("Frobbing the $bar")
    }
}
</syntaxhighlight>وتتلخّص الآلية بالنقاط المهمّة الآتية:
* يكون للتصريح المُتوقَّع (في الوحدة المشتركة) والتصريح الفعليّ الموافق له (في وحدة المنصّة) نفس الاسم تمامًا.
* يُحدَّد التصريح المُتوقَّع بالكلمة المفتاحيّة <code>expect</code> والفعليّ بالكلمة المفتاحية <code>actual</code>.
* يجب أن تُحدَّد كل التصريحات الفعليّة التي تطابق (match) أيًا من التصريحات المُتوقَّعة بالكلمة المفتاحيّة <code>actual</code>.
* لا تحتوي التصريحات المُتوقَّعة على أيّ تعريفٍ للاستخدام (implementation).
ولا تقتصر التصريحات المُتوقَّعة على الواجهات (interfaces) وعناصرها فقط، ففي المثال الآتي يوجد للصنف المُتوقَّع بانٍ (constructor) ويمكن إنشاؤه مباشرةً من الشيفرة المشتركة، كما ويمكن تطبيق المُحدِّد <code>expect</code> على التصريحات الأخرى بما فيها تصريحات المستوى الأعلى (top-level) والتوصيفات (annotations)، مثل:<syntaxhighlight lang="kotlin">
// المشتركة
expect fun formatString(source: String, vararg args: Any): String

expect annotation class Test

// JVM
actual fun formatString(source: String, vararg args: Any) =
    String.format(source, args)
    
actual typealias Test = org.junit.Test
</syntaxhighlight>ويتأكَّد المُترجِم من وجود تصريحٍ فعليّ لكل تصريحٍ مُتوقَّعٍ، وذلك في كلِّ وحدات المنصّات التي تعرَّف استخدام (implement) الوحدة المشتركة، وسيُعلِم بوجود خطأٍ عند عدم وجود كلِّ التصريحات الفعليّة المطلوبة، وتساعد بيئة العمل (IDE) بإنشاء غير الموجود منها.

عند الحاجة لاستخدام مكتبةٍ خاصّةٍ بالمنصّة في الوحدة المشتركة بينما يتوفَّر تعريف الاستخدام (implementation) لمنصّة أخرى، فيمكن الاعتماد حينئذٍ على التسمية البديلة للنوع (typealias) للصنف الموجود باعتباره التصريحَ الفعليّ، كما في الشيفرة:<syntaxhighlight lang="kotlin">
expect class AtomicRef<V>(value: V) {
  fun get(): V
  fun set(value: V)
  fun getAndSet(value: V): V
  fun compareAndSet(expect: V, update: V): Boolean
}

actual typealias AtomicRef<V> = java.util.concurrent.atomic.AtomicReference<V>
</syntaxhighlight>

== اختبارات المنصّات المتعدِّدة (Multiplatform Tests) ==
تتيح لغة Kotlin إمكانيّة كتابة الاختبارات في المشروع المشترك بحيث تُترجَم وتُنفَّذ في كلّ مشروعٍ خاصٍ بالمنصّة، وهناك أربعة توصيفاتٍ (annotations) مُتاحةٍ في الحزمة <code>kotlin.test</code> والمستخدَمة لترميز (markup) الاختبارات في الشيفرة المشتركة وهي: <code>‎@Test</code> و <code>‎@Ignore</code> و <code>‎‎@BeforeTest</code> و <code>‎@AfterTest</code> وهي متوافقةٌ مع توصيفات JUnit الأربعة الموجودة في JVM ، وهي متاحة في JS بدءًا من الإصدار 1.1.4 وذلك لدعم اختبارات وحدات JS.

ولاستخدامها تجب إضافة الاعتماديّة (dependency) على <code>kotlin-test-annotations-common</code> إلى الوحدة المشتركة، والاعتماديّة على <code>kotlin-test-junit</code> إلى وحدة JVM، والاعتماديّة على <code>kotlin-test-js</code> إلى وحدة JS.

== مصادر<span> </span> ==
* [https://kotlinlang.org/docs/reference/multiplatform.html صفحة المشاريع متعدّدة المنصّات في التوثيق الرسميّ للغة Kotlin]
[[تصنيف:Kotlin]]
[[تصنيف:Kotlin JavaScript]]
[[تصنيف:Kotlin Java]]
[[تصنيف:Kotlin Modules]]
[[تصنيف:Kotlin Projects]]