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

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

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

حزمة تطوير برامج Java‏ (JDK)

تحتوي حزمة تطوير Java‏ (JDK) على:

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

JetBrains Runtime (JBR)

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

كيف يمكنني اختيار حزمة تطوير برامج Java (JDK) لتشغيل استوديو Android؟

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

تبحث النصوص البرمجية للتشغيل في "استوديو Android" عن جهاز JVM بالترتيب التالي:

1. متغيّر البيئة STUDIO_JDK
2. دليل studio.jdk (في توزيعة "استوديو Android")
3. دليل jbr (JetBrains Runtime) في توزيعة "استوديو Android". حقل يُنصح به.
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 عملية تُسمى برنامج خفي لتنفيذ الإصدار الفعلي. ويمكن إعادة استخدام هذه العملية، طالما أنّ الإصدارات تستخدم إصدار JDK وGradle نفسهما. وتؤدي إعادة استخدام البرنامج الخفي إلى تقليل الوقت اللازم لبدء جهاز افتراضي جديد لـ Java وإعداد نظام الإصدار.

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

إعدادات Gradle JDK في "استوديو Android"

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

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

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

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

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

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

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

على سبيل المثال، يتطلّب الإصدار 8.x من المكوّن الإضافي لنظام Gradle المتوافق مع Android الإصدار 17 من حزمة تطوير البرامج في Java‏ (JDK). إذا حاولت تشغيل إصدار 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.

android {
    ...
    compileSdk = 36
}

android {
    ...
    compileSdk 36
}

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

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

ما هي حزمة JDK التي تجمع رمز المصدر Java؟

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

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

لإنشاء إصدار أكثر اتساقًا، يمكنك تحديد إصدار سلسلة أدوات Java بشكل صريح. يؤدي تحديد ذلك إلى:

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

ننصحك بتحديد سلسلة أدوات Java دائمًا، والتأكّد من تثبيت حزمة تطوير البرامج (JDK) المحدّدة أو إضافة أداة حلّ سلاسل الأدوات إلى عملية الإنشاء.

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

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

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) الخاص بالوحدة على النحو التالي:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
    }
}

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

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

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

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

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

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

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

إذا كنت تستخدم إصدارًا من Kotlin أقدم من 2.2، عليك أيضًا ضبط kotlinOptions:

android {
    kotlinOptions {
        jvmTarget = "17"
    }
}

android {
    kotlinOptions {
        jvmTarget = "17"
    }
}

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