ชวาและบาเซล

รายงานปัญหา ดูแหล่งที่มา รุ่น Nightly · 7.4 7.3 · 7.2 · 7.1 · 7.0 · 6.5

หน้านี้มีแหล่งข้อมูลที่จะช่วยให้คุณใช้ Bazel กับโปรเจ็กต์ Java ได้ ซึ่งลิงก์ไปยังบทแนะนำ กฎการสร้าง และข้อมูลอื่นๆ สำหรับการสร้างโปรเจ็กต์ Java ด้วย Bazel โดยเฉพาะ

การทำงานกับ Bazel

แหล่งข้อมูลต่อไปนี้จะช่วยคุณใช้งาน Bazel ในโปรเจ็กต์ Java

การย้ายข้อมูลไปยัง Bazel

หากปัจจุบันคุณสร้างโปรเจ็กต์ Java ด้วย Maven ให้ทำตามขั้นตอนในคำแนะนำการย้ายข้อมูลเพื่อเริ่มสร้างโปรเจ็กต์ Maven ด้วย Bazel

เวอร์ชัน Java

Java เวอร์ชันที่เกี่ยวข้องซึ่งตั้งค่าด้วย Flag การกําหนดค่ามี 2 เวอร์ชัน ได้แก่

  • เวอร์ชันของไฟล์ต้นฉบับในที่เก็บ
  • เวอร์ชันรันไทม์ Java ที่ใช้ในการเรียกใช้โค้ดและทดสอบ

การกำหนดค่าเวอร์ชันของซอร์สโค้ดในที่เก็บ

ถ้าไม่มีการกำหนดค่าเพิ่มเติม Bazel จะถือว่าไฟล์ซอร์สของ Java ทั้งหมดในที่เก็บเขียนด้วย Java เวอร์ชันเดียว หากต้องการระบุเวอร์ชันของแหล่งที่มาในที่เก็บ ให้เพิ่มไฟล์ build --java_language_version={ver} ไปยังไฟล์ .bazelrc โดยที่ {ver} เป็นตัวอย่าง 11 เจ้าของที่เก็บ Bazel ควรตั้งค่าแฟล็กนี้เพื่อให้ Bazel และผู้ใช้อ้างอิงหมายเลขเวอร์ชัน Java ของซอร์สโค้ดได้ ดูรายละเอียดเพิ่มเติมได้ที่Flag เวอร์ชันภาษา Java

การกำหนดค่า JVM ที่ใช้เพื่อเรียกใช้และทดสอบโค้ด

Bazel ใช้ JDK 1 ตัวสําหรับการคอมไพล์และ JVM อีก 1 ตัวเพื่อเรียกใช้และทดสอบโค้ด

โดยค่าเริ่มต้น Bazel จะคอมไพล์โค้ดโดยใช้ JDK ที่ดาวน์โหลดมา จากนั้นจะเรียกใช้และทดสอบโค้ดด้วย JVM ที่ติดตั้งในเครื่อง Bazel จะค้นหา JVM โดยใช้ JAVA_HOME หรือเส้นทาง

ไฟล์ไบนารีที่ได้จะเข้ากันได้กับ JVM ที่ติดตั้งในเครื่องในไลบรารีของระบบ ซึ่งหมายความว่าไฟล์ไบนารีที่ได้จะขึ้นอยู่กับสิ่งที่ติดตั้งในเครื่อง

หากต้องการกำหนดค่า JVM ที่ใช้สำหรับการดำเนินการและการทดสอบ ให้ใช้--java_runtime_version flag ค่าเริ่มต้นคือ local_jdk

การทดสอบและการคอมไพล์แบบแยกต่างหาก

หากต้องการสร้างคอมไพล์แบบต่อเนื่อง ให้ใช้แฟล็กบรรทัดคำสั่ง --java_runtime_version=remotejdk_11 ระบบจะคอมไพล์โค้ด ดำเนินการ และทดสอบใน JVM ที่ดาวน์โหลดจากที่เก็บระยะไกล ดูรายละเอียดเพิ่มเติมได้ที่Flag เวอร์ชันรันไทม์ของ Java

การกําหนดค่าการคอมไพล์และการดำเนินการของเครื่องมือสร้างใน Java

มี JDK และ JVM คู่ที่ 2 ที่ใช้สร้างและเรียกใช้เครื่องมือ ซึ่งใช้ในกระบวนการสร้าง แต่ไม่อยู่ในผลลัพธ์การสร้าง JDK และ JVM นั้นควบคุมโดยใช้ --tool_java_language_version และ --tool_java_runtime_version ค่าเริ่มต้นคือ 11 และ remotejdk_11 ตามลำดับ

การคอมไพล์โดยใช้ JDK ที่ติดตั้งไว้ในเครื่อง

โดยค่าเริ่มต้น Bazel จะคอมไพล์โดยใช้ JDK ระยะไกล เนื่องจากมีการลบล้างข้อมูลภายในของ JDK ระบบจะกําหนดค่าชุดเครื่องมือการคอมไพล์โดยใช้ JDK ที่ติดตั้งในเครื่อง แต่ไม่ได้ใช้งาน

หากต้องการคอมไพล์โดยใช้ JDK ที่ติดตั้งในเครื่อง นั่นคือใช้ชุดเครื่องมือคอมไพล์สำหรับ JDK ในเครื่อง ให้ใช้ Flag เพิ่มเติม --extra_toolchains=@local_jdk//:all แต่โปรดทราบว่าวิธีนี้อาจใช้ไม่ได้กับ JDK ของผู้ให้บริการรายใดก็ได้

ดูรายละเอียดเพิ่มเติมได้ที่การกำหนดค่าชุดเครื่องมือ Java

แนวทางปฏิบัติแนะนำ

นอกจากแนวทางปฏิบัติแนะนำทั่วไปของ Bazel แล้ว ด้านล่างนี้คือแนวทางปฏิบัติแนะนำสำหรับโปรเจ็กต์ Java โดยเฉพาะ

โครงสร้างไดเรกทอรี

โปรดใช้เลย์เอาต์ไดเรกทอรีมาตรฐานของ Maven (sources อยู่ภายใต้ src/main/java, tests อยู่ภายใต้ src/test/java)

สร้างไฟล์

ปฏิบัติตามหลักเกณฑ์ต่อไปนี้เมื่อสร้างไฟล์ BUILD

  • ใช้ไฟล์ BUILD 1 ไฟล์ต่อไดเรกทอรีที่มีซอร์สโค้ด Java เนื่องจากวิธีนี้จะช่วยปรับปรุงประสิทธิภาพการสร้าง

  • ไฟล์ BUILD ทุกไฟล์ควรมีกฎ java_library 1 รายการที่มีลักษณะดังนี้ 

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

  • ชื่อไลบรารีควรเป็นชื่อของไดเรกทอรีที่มีไฟล์ BUILD วิธีนี้จะทำให้ป้ายกำกับของคลังสั้นลง ซึ่งก็คือใช้ "//package" แทน "//package:package"

  • แหล่งที่มาควรเป็น glob ที่ไม่ซ้ำกันของไฟล์ Java ทั้งหมดในไดเรกทอรี

  • การทดสอบควรอยู่ในไดเรกทอรีที่ตรงกันภายใน src/test และใช้ไลบรารีนี้

การสร้างกฎใหม่สำหรับบิลด์ Java ขั้นสูง

หมายเหตุ: การสร้างกฎใหม่มีไว้สําหรับสถานการณ์บิลด์และทดสอบขั้นสูง คุณไม่จำเป็น เมื่อเริ่มต้นใช้งาน Bazel

โมดูล เศษการกำหนดค่า และผู้ให้บริการต่อไปนี้จะช่วยคุณขยายความสามารถของ Bazel เมื่อสร้างโปรเจ็กต์ Java

การกำหนดค่า Java Toolchain

Bazel ใช้เครื่องมือ Java 2 ประเภท ได้แก่ - การดำเนินการ, ใช้สำหรับดำเนินการและทดสอบไบนารีของ Java, ควบคุมด้วย Flag --java_runtime_version - การคอมไพล์ ซึ่งใช้เพื่อคอมไพล์ซอร์สของ Java ควบคุมด้วย --java_language_version Flag

การกําหนดค่าเครื่องมือทางเทคนิคการดําเนินการเพิ่มเติม

เครื่องมือเชนการดำเนินการคือ JVM ซึ่งอาจเป็นในเครื่องหรือจากที่เก็บข้อมูล โดยมีข้อมูลเพิ่มเติมเกี่ยวกับเวอร์ชัน ระบบปฏิบัติการ และสถาปัตยกรรม CPU

คุณเพิ่มเครื่องมือทางเทคนิคสำหรับการเรียกใช้ Java ได้โดยใช้กฎของที่เก็บ local_java_repository หรือ remote_java_repository ในส่วนขยายโมดูล การเพิ่มกฎจะทำให้ JVM พร้อมใช้งานโดยใช้ Flag เมื่อมีการระบุคำจำกัดความหลายรายการสำหรับระบบปฏิบัติการและสถาปัตยกรรม 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
)

ตัวอย่างการกําหนดค่า JVM ระยะไกล

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 = ...
)

การกำหนดค่า Toolchain การคอมไพล์เพิ่มเติม

เครื่องมือการคอมไพล์ประกอบด้วย JDK และเครื่องมือมากมายที่ Bazel ใช้ในระหว่างการคอมไพล์และมีฟีเจอร์เพิ่มเติม เช่น ข้อผิดพลาด "ข้อผิดพลาดได้ง่าย" การพึ่งพา Java ที่เข้มงวด การคอมไพล์ส่วนหัว การนำน้ำตาลออกของ Android การใช้เครื่องมือที่ครอบคลุม และการจัดการ Genclass สำหรับ IDE

JavaBuilder เป็นเครื่องมือที่มาพร้อมกับ Bazel ซึ่งจะดำเนินการคอมไพล์และให้ฟีเจอร์ที่กล่าวถึงข้างต้น JDK จะดำเนินการคอมไพล์จริงโดยใช้คอมไพเลอร์ภายใน JDK ที่ใช้สำหรับการคอมไพล์จะระบุโดยแอตทริบิวต์ java_runtime ของ Toolchain

Bazel จะลบล้างข้อมูลภายในของ JDK บางรายการ ในกรณีที่ JDK เป็นเวอร์ชันที่มากกว่า 9 ระบบจะแพตช์โมดูล java.compiler และ jdk.compiler โดยใช้ Flag ของ JDK --patch_module ในกรณีที่เป็น JDK เวอร์ชัน 8 ระบบจะแพตช์คอมไพเลอร์ Java โดยใช้ Flag -Xbootclasspath

VanillaJavaBuilder เป็นการใช้งาน JavaBuilder ครั้งที่สอง ซึ่งจะไม่แก้ไขคอมไพเลอร์ภายในของ JDK และไม่มีฟีเจอร์เพิ่มเติมใดๆ เครื่องมือเชนในตัวไม่ได้ใช้ VanillaJavaBuilder

นอกเหนือจาก JavaBuilder แล้ว Bazel ยังใช้เครื่องมืออื่นๆ อีกหลายอย่างในระหว่างการคอมไพล์

เครื่องมือ ijar จะประมวลผลไฟล์ jar รายการเพื่อนำทุกอย่างออก ยกเว้นลายเซ็นการโทร ไฟล์ jar ที่เป็นผลลัพธ์เรียกว่าไฟล์ jar ส่วนหัว ไฟล์เหล่านี้ใช้เพื่อปรับปรุงการคอมไพล์แบบเพิ่มทีละขั้นโดยจะคอมไพล์ไฟล์ที่ต้องอาศัย downstream อีกครั้งเฉพาะเมื่อเนื้อหาของฟังก์ชันมีการเปลี่ยนแปลง

เครื่องมือ singlejar จะรวมไฟล์ jar หลายไฟล์เข้าด้วยกันเป็นไฟล์เดียว

เครื่องมือ genclass จะประมวลผลเอาต์พุตของการคอมไพล์ Java ในภายหลัง และสร้าง jar ที่มีเฉพาะไฟล์คลาสสำหรับแหล่งที่มาที่สร้างโดยตัวประมวลผลคำอธิบายประกอบ

เครื่องมือ JacocoRunner จะเรียกใช้ Jacoco ในไฟล์ที่มีเครื่องมือวัดผลและแสดงผลลัพธ์ในรูปแบบ LCOV

เครื่องมือ TestRunner จะทดสอบ JUnit 4 ในสภาพแวดล้อมที่มีการควบคุม

คุณสามารถกำหนดค่าการคอมไพล์ใหม่ได้โดยเพิ่มมาโคร default_java_toolchain ลงในไฟล์ BUILD และลงทะเบียนโดยเพิ่มกฎ register_toolchains ลงในไฟล์ MODULE.bazel หรือใช้แฟล็ก --extra_toolchains

ระบบจะใช้ชุดเครื่องมือนี้เฉพาะเมื่อแอตทริบิวต์ source_version ตรงกับค่าที่ระบุโดย Flag --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 คอมไพเลอร์

คุณกำหนดค่า Flag JVM และ Javac ด้วยแฟล็กหรือแอตทริบิวต์ default_java_toolchain ได้

Flag ที่เกี่ยวข้องคือ --jvmopt, --host_jvmopt, --javacopt และ --host_javacopt

แอตทริบิวต์ default_java_toolchain ที่เกี่ยวข้องคือ javacopts, jvm_opts, javabuilder_jvm_opts และ turbine_jvm_opts

การกำหนดค่าแฟล็ก Java คอมไพเลอร์เฉพาะแพ็กเกจ

คุณสามารถกําหนดค่า Flag ต่างๆ ของคอมไพเลอร์ 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 เวอร์ชันเดียวกัน

อย่างไรก็ตาม บิลด์ที่แยกกันอาจดำเนินการโดยใช้ Flag ที่แตกต่างกัน

เพื่อให้ใช้งานแฟล็กต่างๆ ได้ง่ายขึ้น เราอาจจัดกลุ่มชุดของแฟล็กสำหรับเวอร์ชันที่เจาะจงโดยใช้การกำหนดค่า .bazelrc"

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

การกำหนดค่าเหล่านี้สามารถใช้กับ Flag --config ได้ เช่น bazel test --config=java11 //:java11_test