إصدارات Java في إصدارات Android

سواء كان رمز المصدر مكتوبًا بلغة Java أو Kotlin أو كليهما، هناك عدة مواضع يجب فيها اختيار إصدار JDK أو لغة Java لإنشاء حِزمك.

الشكل 1. إنشاء علاقات JDK في إطار

مسرد المصطلحات

مجموعة تطوير Java ‏(JDK)

تتضمّن حزمة تطوير Java (JDK) :

• أدوات، مثل المُنشئ والمُحسِّن وبرنامج إنشاء الأرشيف ويتم استخدامها في الكواليس أثناء عملية الإنشاء ل إنشاء تطبيقك.
• المكتبات التي تحتوي على واجهات برمجة تطبيقات يمكنك الاتصال بها من رمز المصدر Kotlin أو Java يُرجى العلم أنّ بعض الدوال غير متوفرة على Android.
• ‫Java Virtual Machine ‏(JVM)، وهو مترجم ينفذ تطبيقات Java ويمكنك استخدام JVM لتشغيل بيئة التطوير المتكاملة (IDE) من "استوديو Android" وأداة إنشاء Gradle. لا يتم استخدام "آلة Java الافتراضية" على أجهزة Android أو المحاكيات.

JetBrains Runtime ‏(JBR)

JetBrains Runtime (JBR) هو إصدار مُحسَّن من حزمة Java Development Kit (JDK) ويتم توزيعه مع Android Studio. يتضمّن العديد من التحسينات لاستخدامها في Studio ومنتجات JetBrains ذات الصلة، ولكن يمكن استخدامه أيضًا لتشغيل تطبيقات Java أخرى.

كيف يمكنني اختيار حزمة JDK لتشغيل "استوديو Android"؟

ننصحك باستخدام JBR لتشغيل Android Studio. ويتم نشره مع "استوديو Android" واستخدامه لاختباره، ويتضمن تحسينات لأفضل استخدام لخدمة "استوديو Android". لضمان ذلك، لا تضبط متغيّر البيئة STUDIO_JDK.

تبحث نصوص التشغيل الخاصة بـ "استوديو Android" عن بيئة Java الافتراضية بالترتيب التالي:

1. متغيّر البيئة STUDIO_JDK
2. دليل studio.jdk (في حزمة توزيع "استوديو Android")
3. دليل jbr (وقت تشغيل JetBrains) في توزيع Android Studio. يُنصح به.
4. متغيّر البيئة JDK_HOME
5. متغيّر بيئة واحد (JAVA_HOME)
6. java قابل للتنفيذ في متغيّر البيئة PATH.

كيف يمكنني اختيار حزمة JDK التي تشغّل عمليات إنشاء Gradle؟

إذا كنت تشغِّل Gradle باستخدام الأزرار في "استوديو Android"، يتم استخدام ملف JDK المحدّد في إعدادات "استوديو Android" لتشغيل Gradle. إذا شغّلت Gradle في وحدة طرفية، سواء داخل "استوديو Android" أو خارجه، سيحدِّد متغيّر بيئة JAVA_HOME (في حال تحديده) نظام JDK الذي يشغِّل نصوص Gradle البرمجية. في حال عدم ضبط JAVA_HOME ، يتم استخدام الأمر java في متغيّر PATH الخاص بالبيئة.

للحصول على النتائج الأكثر اتساقًا، احرص على ضبط متغيّر بيئة JAVA_HOME وضبط Gradle JDK في "استوديو Android" على نفس قيمة JDK.

ملاحظة: في حال تنفيذ أمر Gradle في "وحدة تحكّم Android Studio الطرفية" من خلال النقر بزرّ الماوس الأيمن واختيار تنفيذ الأمر المميّز باستخدام IDE، سيتم استخدام JDK في إعدادات "استوديو Android"، وليس JAVA_HOME.

عند تشغيل عملية الإنشاء، تنشئ Gradle عملية تُعرف باسم الخادم الدائم للقيام بعملية الإنشاء الفعلية. يمكن إعادة استخدام هذه العملية، ما دامت عمليات الإنشاء تستخدم إصدار JDK وGradle نفسهما. يؤدي إعادة استخدام الخادم الدائم إلى تقليل وقت بدء تشغيل Java Virtual Machine (JVM) الجديد وإعداد نظام الإنشاء.

في حال بدء عمليات الإنشاء باستخدام إصدارات مختلفة من JDK أو Gradle، يتم إنشاء عمليات خلفية إضافية تستهلك المزيد من وحدة المعالجة المركزية والذاكرة.

ملاحظة: عند العمل على مشاريع متعدّدة في الوقت نفسه، حدِّد، إن أمكن، إصدار Gradle نفسه في ملف gradle-wrapper.properties لتقليل عدد برامج Gradle الخفيّة التي يتم إنشاؤها.

ضبط Gradle JDK في "استوديو Android"

لتعديل إعدادات Gradle JDK للمشروع الحالي، افتح إعدادات Gradle من ملف (أو Android Studio على نظام التشغيل macOS) > الإعدادات > الإنشاء والتنفيذ والنشر > أدوات الإنشاء > Gradle. تحتوي القائمة المنسدلة Gradle JDK على الخيارات التالية للاختيار من بينها:

• وحدات الماكرو، مثل JAVA_HOME وGRADLE_LOCAL_JAVA_HOME
• إدخالات جدول JDK بتنسيق vendor-version مثل jbr-17 التي يتم تخزينها في ملفات إعداد Android
• تنزيل حزمة تطوير Java (JDK)
• إضافة حزمة JDK معيّنة
• حِزم JDK التي تم رصدها محليًا من ملف التثبيت التلقائي لحِزم JDK في نظام التشغيل

يتم حفظ الخيار المحدَّد في الخيار gradleJvm ضمن ملف .idea/gradle.xml الخاص بالمشروع، ويتم استخدام دقة مسار JDK لتشغيل Gradle عند البدء من خلال "استوديو Android".

الشكل 2. إعدادات JDK في Gradle في "استوديو Android"

تتيح الوحدات النمطية اختيار مسار JDK الديناميكي للمشروع:

• JAVA_HOME: يستخدم متغيّر البيئة بالاسم نفسه
• GRADLE_LOCAL_JAVA_HOME: يستخدم السمة java.home في ملف .gradle/config.properties الذي يتم ضبطه تلقائيًا على "وقت تشغيل JetBrains".

يتم استخدام حزمة JDK المحدّدة لتشغيل عملية إنشاء Gradle وحلّ مراجع JDK API عند تعديل نصوص إنشاء البرامج والرموز المصدرية. يُرجى العِلم أنّ الcompileSdk المحدّد سيفرض قيودًا إضافية على رموز Java التي ستكون متوفّرة عند تعديل رمز المصدر وإنشاءه.

ملاحظة: في معظم الحالات، ننصحك باستخدام GRADLE_LOCAL_JAVA_HOME، وهو الخيار التلقائي للمشاريع التي تم إنشاؤها حديثًا. يتيح لك ذلك تحديدJDK خاص بالمشروع بدون فتح المشروع أولاً.

تأكد من اختيار إصدار JDK أعلى من أو يساوي إصدارات JDK المستخدمة بواسطة المكونات الإضافية التي تستخدمها في إصدار Gradle الخاص بك. لتحديد الحد الأدنى من إصدار JDK المطلوب لمكوّن Android Gradle الإضافي (AGP)، اطّلِع على جدول التوافق في ملاحظات الإصدار.

على سبيل المثال، يتطلّب الإصدار 8.x من المكوّن الإضافي لنظام Gradle المتوافق مع Android استخدام JDK 17. إذا حاولت تشغيل إصدار Gradle يستخدم هذا الإصدار مع إصدار سابق منJDK، سيُرسِل رسالة مثل:

An exception occurred applying plugin request [id: 'com.android.application']
> Failed to apply plugin 'com.android.internal.application'.
   > Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
      Your current JDK is located in /usr/local/buildtools/java/jdk
      You can try some of the following options:
       - changing the IDE settings.
       - changing the JAVA_HOME environment variable.
       - changing `org.gradle.java.home` in `gradle.properties`.

ما هي واجهات برمجة تطبيقات Java التي يمكنني استخدامها في رمز المصدر Java أو Kotlin؟

يمكن لتطبيق Android استخدام بعض واجهات برمجة التطبيقات المحددة في JDK، لكن ليس كلها. تحدِّد حزمة تطوير البرامج (SDK) لنظام التشغيل Android عمليات تنفيذ العديد من وظائف مكتبة Java كجزء من واجهات برمجة التطبيقات المتاحة. تحدِّد السمة compileSdk إصدار حزمة تطوير البرامج (SDK) لنظام التشغيل Android المطلوب استخدامه عند تجميع رمز المصدر Kotlin أو Java.

Kotlin

android {
    ...
    compileSdk = 33
}

رائع

android {
    ...
    compileSdk 33
}

يتوافق كل إصدار من Android مع إصدار محدّد من حزمة تطوير البرامج (JDK) ومجموعة فرعية من واجهات برمجة تطبيقات Java المتاحة. إذا كنت تستخدم واجهة برمجة تطبيقات Java متاحة في compileSdk غير متوفّرة في minSdk المحدّد، قد تتمكّن من استخدام واجهة برمجة التطبيقات في الإصدار الأقدم من Android من خلال عملية تُعرف باسم إزالة السكر. راجِع واجهات برمجة تطبيقات Java 11 والإصدارات الأحدث المتاحة من خلال إزالة التصنيف للاطّلاع على واجهات برمجة التطبيقات المتوافقة.

استخدِم هذا الجدول لتحديد إصدار Java الذي تتوافق مع كل واجهة برمجة تطبيقات Android، وأين يمكنك العثور على تفاصيل حول توفُّر واجهات برمجة تطبيقات Java.

Android	Java	ميزات واجهة برمجة التطبيقات واللغة المتاحة
14 (واجهة برمجة التطبيقات 34)	17	المكتبات الأساسية
13 (المستوى 33 لواجهة برمجة التطبيقات)	11	المكتبات الأساسية
12 (المستوى 32 لواجهة برمجة التطبيقات)	11	Java API
11 والإصدارات الأدنى		إصدارات Android

ما هو إصدار JDK الذي يُجمِّع رمز مصدر Java الخاص بي؟

يحتوي JDK في مجموعة أدوات Java على مُجمِّع Java المستخدَم لتجميع أي رمز برمجي مصدر لـ Java. يُشغِّل هذا الإصدار من حزمة تطوير البرامج (JDK) أيضًا javadoc واختبارات الوحدات أثناء عملية الإنشاء.

تكون سلسلة الأدوات تلقائيًا هي JDK المستخدَمة لتشغيل Gradle. في حال استخدام الإصدار التلقائي وتشغيل عملية إنشاء على أجهزة مختلفة (على سبيل المثال، جهازك المحلي وخادم منفصل لدمج الإصدارات)، يمكن أن تختلف نتائج عملية الإنشاء في حال استخدام إصدارات مختلفة من JDK.

لإنشاء إصدار أكثر اتساقًا، يمكنك تحديد إصدار مجموعة أدوات Java صراحةً. عند تحديد هذا الخيار:

• يحدِّد هذا الخيار موقع حزمة Java Development Kit (JDK) المتوافقة على النظام الذي يشغِّل عملية الإنشاء.
  • في حال عدم توفّر JDK متوافق (وتحديد برنامج تعيين سلسلة أدوات)، يتم تنزيل أحد البرامج.
• تعرِض واجهات برمجة تطبيقات Java لسلسلة الأدوات طلبات البيانات من رمز المصدر.
• لتجميع مصدر Java باستخدام إصدار لغة Java.
• الإعدادات التلقائية للمواد المستهلكة في sourceCompatibility و targetCompatibility

ننصحك بأن تحدّد دائمًا سلسلة أدوات Java، وأن تتأكّد من تثبيت JDK المحدّد، أو إضافة أداة تعيين سلسلة الأدوات إلى تصميمك.

يمكنك تحديد سلسلة الأدوات سواء كان رمز المصدر مكتوبًا بلغة Java أو Kotlin أو كليهما. حدِّد سلسلة الأدوات في أعلى مستوى من ملف build.gradle(.kts) الخاص بالوحدة.

حدِّد إصدار سلسلة أدوات Java على النحو التالي:

Kotlin

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

رائع

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

ويعمل هذا الإجراء إذا كان المصدر هو Kotlin أو Java أو مزيجًا من كليهما.

يمكن أن يكون إصدار JDK الخاص بسلسلة الأدوات هو نفسه إصدار JDK المستخدَم لتشغيل Gradle، ولكن تجدر الإشارة إلى أنّهما يخدمان أغراضًا مختلفة.

ما هي ميزات لغة Java المصدر التي يمكنني استخدامها في رمز Java المصدر؟

تحدّد السمة sourceCompatibility ميزات لغة Java والمتاحة أثناء تجميع مصدر Java. ولا يؤثّر ذلك في مصدر Kotlin.

حدِّد sourceCompatibility في ملف build.gradle(.kts) الخاص بالوحدة على النحو التالي:

Kotlin

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
    }
}

رائع

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
    }
}

في حال عدم تحديد هذه السمة، يتم ضبطها تلقائيًا على إصدار مجموعة أدوات Java . إذا كنت لا تستخدم سلسلة أدوات Java، يتم ضبطها تلقائيًا على الإصدار الذي يختاره المكوّن الإضافي لنظام Gradle المتوافق مع Android (على سبيل المثال، Java 8 أو الإصدارات الأحدث).

ملاحظة: اعتبارًا من الإصدار Giraffe من Android Studio، عند استيراد المشاريع، يتم أيضًا استخدام الخيار sourceCompatibility كخيار تلقائي لميزة "مساعدة رموز الترميز" في بيئة تطوير البرامج المتكاملة وميزة "فحص الأخطاء النحوية" عند كتابة مصدر Java. تتطلّب بعض ميزات لغة Java توفُّر مكتبة برمجية وهي غير متاحة على Android. يحدّد الخيار compileSdk المكتبات المتاحة. أمّا الميزات الأخرى، مثل تعبيرات التبديل، فلا تتطلّب سوى مُجمِّع Java وتعمل على Android.

ما هي ميزات Java الثنائية التي يمكن استخدامها عند تجميع مصدر Kotlin أو Java؟

تحدّد السمتَان targetCompatibility وjvmTarget إصدار تنسيق فئة Java المستخدَم عند إنشاء رمز برمجي ثنائي لملف برمجي Java وملف Kotlin المجمَّعَين على التوالي.

كانت بعض ميزات Kotlin متوفّرة قبل إضافة ميزات Java المماثلة لها. كان على مجمعات Kotlin الأولى إنشاء طريقتها الخاصة لتمثيل ميزات Kotlin هذه. وتمّت إضافة بعض هذه الميزات لاحقًا إلى Java. وفي مستويات jvmTarget اللاحقة، قد يستخدم المحول البرمجي لـ Kotlin ميزة Java مباشرةً، ما قد يؤدي إلى تحسين الأداء.

تتوافق إصدارات Android المختلفة مع إصدارات Java المختلفة. يمكنك الاستفادة من ميزات Java الإضافية من خلال زيادة targetCompatibility وjvmTarget، ولكن قد يفرض عليك ذلك أيضًا زيادة الحد الأدنى لإصدار حزمة تطوير البرامج (SDK) لنظام التشغيل Android لضمان توفّر الميزة.

يُرجى العلم أنّ السمة targetCompatibility يجب أن تكون أكبر من أو تساوي sourceCompatibility. من الناحية العملية، يجب أن تستخدم القيم sourceCompatibility targetCompatibility وjvmTarget بشكل عام القيمة نفسها. يمكنك ضبطها على النحو التالي:

Kotlin

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

رائع

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget '17'
    }
}

في حال عدم تحديدها، يتم ضبط هذه السمات تلقائيًا على إصدار مجموعة أدوات Java. إذا لم تكن تستخدِم مجموعة أدوات Java، قد تختلف القيم التلقائية وتتسبّب في حدوث مشاكل في عملية الإنشاء. لذلك، ننصحك دائمًا بتحديد هذه القيم صراحةً أو استخدام مجموعة أدوات Java.