جافا وبازيل

تحتوي هذه الصفحة على موارد تساعدك على استخدام Bazel مع مشاريع جافا. يرتبط هذا البرنامج التعليمي ببرنامج تعليمي وبناء قواعد ومعلومات أخرى خاصة بإنشاء مشاريع جافا باستخدام Bazel.

العمل مع البازل

ستساعدك المراجع التالية على العمل مع Bazel على مشاريع Java:

نقل البيانات إلى Bazel

إذا كنت تُنشئ حاليًا مشاريع Java التابعة لك باستخدام Maven، اتّبِع الخطوات الواردة في دليل نقل البيانات لبدء إنشاء مشاريع Maven باستخدام Bazel:

إصدارات جافا

يتوفّر إصداران مناسبان من جافا تم وضعهما علامات الضبط:

  • إصدار الملفات المصدر في المستودع
  • إصدار وقت تشغيل جافا المستخدَم لتنفيذ الرمز واختباره

ضبط إصدار رمز المصدر في مستودعك

بدون ضبط إضافي، تفترض Bazel أن جميع ملفات مصدر Java في المستودع مكتوبة في إصدار Java واحد. لتحديد إصدار المصادر في المستودع، أضِف build --java_language_version={ver} إلى ملف .bazelrc حيث يكون {ver} على سبيل المثال 11. على مالكي مستودعات البازل ضبط هذه العلامة حتى تتمكّن Babel ومستخدميها من الرجوع إلى رمز المصدر رقم إصدار Java. للاطّلاع على مزيد من التفاصيل، راجِع علامة إصدار لغة جافا.

إعداد JVM المستخدَم لتنفيذ الرمز واختباره

تستخدم Bazel ملف JDK للتجميع والآخر JVM لتنفيذ الرمز واختباره.

تجمع Bazel تلقائيًا الرمز باستخدام JDK يتم تنزيله وتنفيذ الرمز واختباره مع الجهاز الافتراضي (VM) المثبّت على الجهاز المحلي. تبحث البازل عن JVM باستخدام JAVA_HOME أو المسار.

تتوافق البرامج الثنائية الناتجة مع JVM المثبّتة محليًا في مكتبات النظام، ما يعني أنّ البرامج الثنائية الناتجة تعتمد على ما تم تثبيته على الجهاز.

لإعداد JVM المستخدَم للتنفيذ والاختبار، يمكنك استخدام علامة --java_runtime_version. القيمة التلقائية هي local_jdk.

اختبار مجمّع وتركيب

لإنشاء تجميع مُجمَّع، يمكنك استخدام علامة سطر الأوامر --java_runtime_version=remotejdk_11. يتم تجميع الرمز وتنفيذه واختباره على JVM التي تم تنزيلها من مستودع عن بُعد. لمزيد من التفاصيل، راجِع علامة إصدار وقت تشغيل جافا.

تجميع خدمات تجميع أدوات التنفيذ وتنفيذها في Java

هناك زوج ثاني من JDK وJVM يستخدمان لإنشاء الأدوات وتنفيذها، والتي يتم استخدامها في عملية الإصدار، ولكن ليست في نتائج الإصدار. ويتم التحكم في JDK وJVM باستخدام --tool_java_language_version و--tool_java_runtime_version. والقيمتان التلقائيتان هما 11 وremotejdk_11، على التوالي.

تجميع باستخدام JDK مثبت محليًا

يتم تجميع Bazel تلقائيًا باستخدام JDK عن بُعد، لأن ذلك يلغي الأجهزة الداخلية JDK's. ومع ذلك، تم إعداد سلاسل برامج التجميع التي تستخدم JDK المثبّتة محليًا، ولكن لم يتم استخدامها.

للتجميع باستخدام JDK المثبتة محليًا، والذي يستخدم سلاسل أدوات التجميع لبرنامج JDK المحلي، استخدِم علامة إضافية --extra_toolchains=@local_jdk//:all، ولكن ضع في اعتبارك أن هذا قد لا يعمل على JDK من المورّدين العشوائي.

لمزيد من التفاصيل، اطّلِع على إعداد سلاسل أدوات Java.

أفضل الممارسات

بالإضافة إلى أفضل الممارسات العامة الخاصة بشركة Bazel، في ما يلي بعض أفضل الممارسات المتعلّقة بمشاريع Java.

بنية الدليل

تفضيل تنسيق الدليل التقليدي Maven' (المصادر ضمن src/main/java، الاختبارات ضمن src/test/java).

ملفات BUILD

اتّبِع هذه الإرشادات عند إنشاء ملفات BUILD:

  • استخدِم ملف BUILD واحدًا لكل دليل يحتوي على مصادر جافا، لأن هذا يحسّن أداء الإصدار.

  • يجب أن يحتوي كل ملف BUILD على قاعدة java_library واحدة تبدو كما يلي:

    java_library(
    name = "directory-name",
    srcs = glob(["*.java"]),
    deps = [...],
)

  • يجب أن يكون اسم المكتبة هو اسم الدليل الذي يحتوي على الملف BUILD. يؤدي هذا إلى جعل تصنيف المكتبة أقصر، وهو استخدام "//package" بدلاً من "//package:package".

  • يجب أن تكون المصادر glob غير متكرّرة من جميع ملفات Java في الدليل.

  • يجب أن تكون الاختبارات في دليل مطابق ضمن src/test وتعتمد على هذه المكتبة.

إنشاء قواعد جديدة لإصدارات Java المتقدّمة

ملاحظة: يُستخدَم إنشاء قواعد جديدة للسيناريوهات المتقدّمة للإصدار والاختبار. ولن تحتاج إليها عند بدء استخدام Bazel.

ستساعدك الوحدات التالية وأجزاء التكوين والمزوّدون في توسيع إمكانيات Bazel's عند إنشاء مشاريع Java:

ضبط سلاسل أدوات جافا

تستخدم Bazel نوعين من سلاسل Java: - التنفيذ، وتُستخدم لتنفيذ البرامج الثنائية في Java، واختبار التحكّم فيها باستخدام علامة --java_runtime_version - التجميع، وتُستخدم لتجميع مصادر Java، التي يتم التحكّم فيها باستخدام العلامة --java_language_version

ضبط سلاسل الأدوات الإضافية للتنفيذ

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

قد تتم إضافة سلاسل أدوات تنفيذ JavaScript باستخدام القواعد local_java_repository أو remote_java_repository في الملف WORKSPACE. تؤدي إضافة القاعدة إلى إتاحة JVM باستخدام علامة. عندما يتم تقديم تعريفات متعددة لنظام التشغيل وبنية وحدة المعالجة المركزية (CPU) نفسها، يتم استخدام أول تعريف.

مثال على إعداد JVM محلي:

load("@bazel_tools//tools/jdk:local_java_repository.bzl", "local_java_repository")

local_java_repository(
  name = "additionaljdk",          # Can be used with --java_runtime_version=additionaljdk, --java_runtime_version=11 or --java_runtime_version=additionaljdk_11
  version = 11,                    # Optional, if not set it is autodetected
  java_home = "/usr/lib/jdk-15/",  # Path to directory containing bin/java
)

مثال على إعداد جهاز JavaScript عن بُعد:

load("@bazel_tools//tools/jdk:remote_java_repository.bzl", "remote_java_repository")

remote_java_repository(
  name = "openjdk_canary_linux_arm",
  prefix = "openjdk_canary", # Can be used with --java_runtime_version=openjdk_canary_11
  version = "11",            # or --java_runtime_version=11
  target_compatible_with = [   # Specifies constraints this JVM is compatible with "@platforms//cpu:arm",
    "@platforms//os:linux",
  ],
  urls = ...,               # Other parameters are from http_repository rule.
  sha256 = ...,
  strip_prefix = ...
)

ضبط سلاسل الأدوات الإضافية للتجميع

تتألف سلسلة الأدوات المجمّعة من JDK والأدوات المتعددة التي تستخدمها Bazel أثناء التجميع وتوفّر ميزات إضافية، مثل: الأخطاء عرضة للاعتماديات الصارمة بلغة Java والجملة المركّبة وإلغاء ترتيب برامج Android ومعالجة التغطية وأدوات خوارزمية IDE.

JavaBuilder هي أداة مجمعة من Bazel تعمل على تجميع، وتوفّر الميزات المذكورة أعلاه. يتم تنفيذ التجميع الفعلي باستخدام برامج التجميع الداخلية بواسطة JDK. يتم تحديد JDK المستخدم للتجميع من خلال السمة java_runtime لسلسلة الأدوات.

تلغي Bazel بعض الأنواع الداخلية من JDK. في حالة إصدار JDK &gt؛ 9 و java.compiler وjdk.compiler يتم تصحيح الوحدات باستخدام علامة JDK's --patch_module. في حال استخدام الإصدار 8 JDK، يتم تصحيح برنامج التجميع Java باستخدام العلامة -Xbootclasspath.

VanillaJavaBuilder هو تنفيذ ثانٍ لـ JavaBuilder، والذي لا يعدل برنامج التجميع الداخلي لـ JDK&#39، ولا يحتوي على أي من الميزات الإضافية. لا يمكن استخدام VanillaJavaBuilder من خلال أي من سلسلة الأدوات المدمجة.

بالإضافة إلى JavaBuilder، تستخدم Bazel العديد من الأدوات الأخرى أثناء التجميع.

تعالج أداة ijar ملفات jar لإزالة كل العناصر باستثناء توقيعات المكالمات. تُطلق الجرارات الناتجة على هذه الأوعية. وتُستخدم لتحسين تزايد تجميع البيانات من خلال إعادة تشكيل الروابط بدءًا من الإحالة الناجحة فقط عندما يتغير نص الدالة.

تجمع أداة singlejar ملفات jar المتعددة في ملف واحد.

تعالج الأداة genclass مخرجات تجميع جافا وتُنتج jar التي تحتوي على ملفات الفئة فقط للمصادر التي تم إنشاؤها بواسطة معالجات التعليقات التوضيحية.

تشغّل أداة JacocoRunner Jacoco على الملفات التي يتم قياسها وتعرض النتائج بتنسيق LCOV.

تنفّذ الأداة TestRunner اختبارات JUnit 4 في بيئة خاضعة للرقابة.

يمكنك إعادة ضبط التجميع عن طريق إضافة وحدة ماكرو default_java_toolchain إلى ملف BUILD وتسجيله إما عن طريق إضافة قاعدة register_toolchains إلى ملف WORKSPACE أو باستخدام العلامة --extra_toolchains.

لا يتم استخدام سلسلة الأدوات إلا عندما تتطابق السمة source_version مع القيمة المحدّدة بالعلامة --java_language_version.

مثال لإعداد سلسلة الأدوات:

load(
  "@bazel_tools//tools/jdk:default_java_toolchain.bzl",
  "default_java_toolchain", "DEFAULT_TOOLCHAIN_CONFIGURATION", "BASE_JDK9_JVM_OPTS", "DEFAULT_JAVACOPTS"
)

default_java_toolchain(
  name = "repository_default_toolchain",
  configuration = DEFAULT_TOOLCHAIN_CONFIGURATION,        # One of predefined configurations
                                                          # Other parameters are from java_toolchain rule:
  java_runtime = "@bazel_tools//tools/jdk:remote_jdk11", # JDK to use for compilation and toolchain's tools execution
  jvm_opts = BASE_JDK9_JVM_OPTS + ["--enable_preview"],   # Additional JDK options
  javacopts = DEFAULT_JAVACOPTS + ["--enable_preview"],   # Additional javac options
  source_version = "9",
)

التي يمكن استخدامها باستخدام --extra_toolchains=//:repository_default_toolchain_definition أو عن طريق إضافة register_toolchains("//:repository_default_toolchain_definition") إلى مساحة العمل.

عمليات الضبط المحددة مسبقًا:

  • DEFAULT_TOOLCHAIN_CONFIGURATION: جميع الميزات، متوافقة مع إصدارات JDK >= 9
  • VANILLA_TOOLCHAIN_CONFIGURATION: لا تتوفّر ميزات إضافية، وتتيح استخدام JDK للمورّدين العشوائي.
  • PREBUILT_TOOLCHAIN_CONFIGURATION: مثل الإعداد التلقائي، لكن يتم استخدام الأدوات التي تم إنشاؤها مسبقًا (ijar وsinglejar) فقط
  • NONPREBUILT_TOOLCHAIN_CONFIGURATION: هو نفسه التلقائي، ولكن يتم إنشاء جميع الأدوات من مصادر (قد يكون هذا مفيدًا على نظام التشغيل مع libc مختلف).

ضبط علامات برامج التجميع JVM وJava

يمكنك ضبط علامات JVM وJavac إما مع علامات أو مع سمات default_java_toolchain.

العلامات ذات الصلة هي --jvmopt و--host_jvmopt و--javacopt و--host_javacopt.

سمات default_java_toolchain ذات الصلة هي javacopts وjvm_opts و javabuilder_jvm_opts وturbine_jvm_opts.

ضبط علامات برامج التجميع الخاصة بلغة Java على مستوى الحزمة

يمكنك ضبط علامات برامج التجميع المختلفة لـ Java لملفات المصدر المحددة باستخدام السمة package_configuration لـ default_java_toolchain. يُرجى الاطّلاع على المثال أدناه.

load("@bazel_tools//tools/jdk:default_java_toolchain.bzl", "default_java_toolchain")

# This is a convenience macro that inherits values from Bazel's default java_toolchain
default_java_toolchain(
    name = "toolchain",
    package_configuration = [
        ":error_prone",
    ],
    visibility = ["//visibility:public"],
)

# This associates a set of javac flags with a set of packages
java_package_configuration(
    name = "error_prone",
    javacopts = [
        "-Xep:MissingOverride:ERROR",
    ],
    packages = ["error_prone_packages"],
)

# This is a regular package_group, which is used to specify a set of packages to apply flags to
package_group(
    name = "error_prone_packages",
    packages = [
        "//foo/...",
        "-//foo/bar/...", # this is an exclusion
    ],
)

إصدارات متعددة من رمز مصدر Java في مستودع واحد

لا تدعم Bazel تجميع سوى إصدار واحد من مصادر Java في تصميم واحد. وهذا يعني أنه عند إنشاء اختبار Java أو تطبيق، يتم إنشاء جميع الاعتماديات على إصدار Java نفسه.

ومع ذلك، يمكن تنفيذ إصدارات منفصلة باستخدام علامات مختلفة.

لتسهيل مهمة استخدام علامات مختلفة، قد يتم تجميع مجموعات العلامات لإصدار معيّن مع .bazelrc configs&quot:

build:java8 --java_language_version=8
build:java8 --java_runtime_version=localjdk_8
build:java11 --java_language_version=11
build:java11 --java_runtime_version=remotejdk_11

ويمكن استخدام هذه الإعدادات مع العلامة --config، على سبيل المثال bazel test --config=java11 //:java11_test.