Java ve Bazel

Sorun bildir Kaynağı görüntüle Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Bu sayfada, Bazel'i Java projeleriyle kullanmanıza yardımcı olacak kaynaklar yer alır. Bazel ile Java projeleri oluşturmaya özel bir eğitime, derleme kurallarına ve diğer bilgilere bağlantı verir.

Bazel ile çalışma

Aşağıdaki kaynaklar, Java projelerinde Bazel ile çalışmanıza yardımcı olur:

Bazel'e geçiş

Java projelerinizi şu anda Maven ile oluşturuyorsanız Maven projelerinizi Bazel ile oluşturmaya başlamak için taşıma kılavuzundaki adımları uygulayın:

Java sürümleri

Yapılandırma işaretleriyle ayarlanan iki alakalı Java sürümü vardır:

  • Depodaki kaynak dosyaların sürümü
  • Kodu yürütmek ve test etmek için kullanılan Java çalışma zamanı sürümü

Deponuzdaki kaynak kodunun sürümünü yapılandırma

Ek bir yapılandırma olmadan Bazel, depodaki tüm Java kaynak dosyalarının tek bir Java sürümünde yazıldığını varsayar. Depodaki kaynakların sürümünü belirtmek için build --java_language_version={ver} dosyasını .bazelrc dosyasına ekleyin. Burada {ver}, örneğin 11'dır. Bazel ve kullanıcılarının kaynak kodun Java sürüm numarasına başvurabilmesi için Bazel deposu sahipleri bu işareti ayarlamalıdır. Daha fazla bilgi için Java dil sürümü işareti başlıklı makaleyi inceleyin.

Kodu yürütmek ve test etmek için kullanılan JVM'yi yapılandırma

Bazel, derleme için bir JDK, kodu yürütmek ve test etmek için ise başka bir JVM kullanır.

Varsayılan olarak Bazel, indirdiği bir JDK'yı kullanarak kodu derler ve kodu yerel makineye yüklenen JVM ile yürütüp test eder. Bazel, JAVA_HOME veya yolu kullanarak JVM'yi arar.

Elde edilen ikili dosyalar, sistem kitaplıklarında yerel olarak yüklenen JVM ile uyumludur. Bu nedenle, elde edilen ikili dosyalar makineye yüklenenlere bağlıdır.

Yürütme ve test için kullanılan JVM'yi yapılandırmak üzere --java_runtime_version işaretini kullanın. Varsayılan değer local_jdk'dır.

Hermetik test ve derleme

Hermetik derleme oluşturmak için komut satırı işareti --java_runtime_version=remotejdk_11 kullanabilirsiniz. Kod, uzak depodan indirilen JVM'de derlenir, yürütülür ve test edilir. Daha fazla bilgi için Java çalışma zamanı sürümü işareti başlıklı makaleyi inceleyin.

Java'da derleme araçlarının derlenmesini ve yürütülmesini yapılandırma

Araçları oluşturmak ve çalıştırmak için kullanılan ikinci bir JDK ve JVM çifti vardır. Bu çift, derleme sürecinde kullanılır ancak derleme sonuçlarında yer almaz. Bu JDK ve JVM, --tool_java_language_version ve --tool_java_runtime_version kullanılarak kontrol edilir. Varsayılan değerler sırasıyla 11 ve remotejdk_11'dir.

Yerel olarak yüklenen JDK'yı kullanarak derleme

Bazel, JDK'nın iç kısımlarını geçersiz kıldığı için varsayılan olarak uzak JDK kullanarak derleme yapar. Yerel olarak yüklenen JDK'yı kullanan derleme araç zincirleri yapılandırılmış ancak kullanılmıyor.

Yerel olarak yüklenen JDK'yı kullanarak derlemek için (yani yerel JDK'ya yönelik derleme araç zincirlerini kullanmak için) ek --extra_toolchains=@local_jdk//:all işaretini kullanın. Ancak bunun, rastgele satıcılara ait JDK'larda çalışmayabileceğini unutmayın.

Daha fazla bilgi için Java araç zincirlerini yapılandırma başlıklı makaleye bakın.

En iyi uygulamalar

Genel Bazel en iyi uygulamalarına ek olarak, aşağıda Java projelerine özel en iyi uygulamalar verilmiştir.

Dizin yapısı

Maven'in standart dizin düzenini (kaynaklar src/main/java altında, testler src/test/java altında) tercih edin.

BUILD dosyaları

BUILD dosyalarınızı oluştururken aşağıdaki kurallara uyun:

  • Java kaynaklarını içeren her dizin için bir BUILD dosyası kullanın. Bu, derleme performansını artırır.

  • Her BUILD dosyası, şu şekilde görünen bir java_library kuralı içermelidir:

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

  • Kitaplığın adı, BUILD dosyasını içeren dizinin adı olmalıdır. Bu, kitaplığın etiketini kısaltır. Örneğin, "//package:package" yerine "//package" kullanılır.

  • Kaynaklar, dizindeki tüm Java dosyalarının yinelemeli olmayan bir glob olmalıdır.

  • Testler, src/test altında eşleşen bir dizinde olmalı ve bu kitaplığa bağlı olmalıdır.

Gelişmiş Java derlemeleri için yeni kurallar oluşturma

Not: Yeni kurallar oluşturmak, gelişmiş derleme ve test senaryoları için kullanılır. Bazel'i kullanmaya başlarken buna ihtiyacınız yoktur.

Aşağıdaki modüller, yapılandırma parçaları ve sağlayıcılar, Java projelerinizi oluştururken Bazel'in özelliklerini genişletmenize yardımcı olur:

Java araç zincirlerini yapılandırma

Bazel, iki tür Java araç zinciri kullanır: - Yürütme: Java ikililerini yürütmek ve test etmek için kullanılır. --java_runtime_version işaretiyle kontrol edilir. - Derleme: Java kaynaklarını derlemek için kullanılır. --java_language_version işaretiyle kontrol edilir.

Ek yürütme araç zincirlerini yapılandırma

Yürütme araç zinciri, sürümü, işletim sistemi ve CPU mimarisi hakkında bazı ek bilgiler içeren, yerel veya depodan alınan JVM'dir.

Java yürütme araç zincirleri, bir modül uzantısında local_java_repository veya remote_java_repository depo kuralları kullanılarak eklenebilir. Kural eklendiğinde JVM bir işaret kullanılarak kullanılabilir. Aynı işletim sistemi ve CPU mimarisi için birden fazla tanım verildiğinde ilk tanım kullanılır.

Yerel JVM'nin örnek yapılandırması:

load("@rules_java//toolchains: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
)

Uzak JVM'nin örnek yapılandırması:

load("@rules_java//toolchains: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 = ...
)

Ek derleme araç zincirlerini yapılandırma

Derleme araç zinciri, JDK'dan ve Bazel'in derleme sırasında kullandığı, ek özellikler sağlayan birden fazla araçtan oluşur. Bu özellikler arasında Error Prone, katı Java bağımlılıkları, üstbilgi derleme, Android desugaring, kapsam enstrümantasyonu ve IDE'ler için genclass işleme yer alır.

JavaBuilder, derlemeyi yürüten ve yukarıda bahsedilen özellikleri sağlayan, Bazel ile birlikte gelen bir araçtır. Gerçek derleme, JDK tarafından dahili derleyici kullanılarak yürütülür. Derleme için kullanılan JDK, araç zincirinin java_runtime özelliğiyle belirtilir.

Bazel, bazı JDK dahili işlevlerini geçersiz kılar. JDK sürümü > 9 ise, java.compiler ve jdk.compiler modülleri JDK'nın --patch_module işareti kullanılarak düzeltilir. JDK sürümü 8 söz konusu olduğunda, Java derleyicisi -Xbootclasspath işareti kullanılarak düzeltilir.

VanillaJavaBuilder, JavaBuilder'ın ikinci bir uygulamasıdır. Bu uygulama, JDK'nın dahili derleyicisini değiştirmez ve ek özelliklerin hiçbirini içermez. VanillaJavaBuilder, yerleşik araç zincirlerinin hiçbirinde kullanılmaz.

Bazel, derleme sırasında JavaBuilder'a ek olarak başka araçlar da kullanır.

ijar aracı, jar dosyalarını işleyerek çağrı imzaları dışındaki her şeyi kaldırır. Elde edilen JAR dosyalarına başlıklı JAR dosyaları denir. Bunlar, bir işlevin gövdesi değiştiğinde yalnızca aşağı akış bağımlılarını yeniden derleyerek derleme artımlılığını iyileştirmek için kullanılır.

singlejar aracı, birden fazla jar dosyasını tek bir dosyada birleştirir.

genclass aracı, Java derlemesinin çıkışını işler ve yalnızca ek açıklama işlemcileri tarafından oluşturulan kaynaklara ait sınıf dosyalarını içeren bir jar oluşturur.

JacocoRunner aracı, Jacoco'yu enstrümanlı dosyalar üzerinde çalıştırır ve sonuçları LCOV biçiminde verir.

TestRunner aracı, kontrollü bir ortamda JUnit 4 testlerini yürütür.

default_java_toolchain makrosunu BUILD dosyasına ekleyip register_toolchains kuralını MODULE.bazel dosyasına ekleyerek veya --extra_toolchains işaretini kullanarak derlemeyi yeniden yapılandırabilirsiniz.

Araç zinciri yalnızca source_version özelliği, --java_language_version işaretiyle belirtilen değerle eşleştiğinde kullanılır.

Örnek araç zinciri yapılandırması:

load(
  "@rules_java//toolchains: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 = "@rules_java//toolchains: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 kullanılarak veya çalışma alanına register_toolchains("//:repository_default_toolchain_definition") eklenerek kullanılabilir.

Önceden tanımlanmış yapılandırmalar:

  • DEFAULT_TOOLCHAIN_CONFIGURATION: tüm özellikler, JDK sürümleri >= 9'u destekler
  • VANILLA_TOOLCHAIN_CONFIGURATION: Ek özellik yoktur ve herhangi bir satıcının JDK'larını destekler.
  • PREBUILT_TOOLCHAIN_CONFIGURATION: Varsayılanla aynıdır ancak yalnızca önceden oluşturulmuş araçlar (ijar, singlejar) kullanılır.
  • NONPREBUILT_TOOLCHAIN_CONFIGURATION: Varsayılanla aynıdır ancak tüm araçlar kaynaklardan oluşturulur (Bu, farklı libc'ye sahip işletim sistemlerinde faydalı olabilir).

JVM ve Java derleyici işaretlerini yapılandırma

JVM ve javac işaretlerini işaretlerle veya default_java_toolchain özellikleriyle yapılandırabilirsiniz.

İlgili işaretler --jvmopt, --host_jvmopt, --javacopt ve --host_javacopt'dir.

İlgili default_java_toolchain özellikleri javacopts, jvm_opts, javabuilder_jvm_opts ve turbine_jvm_opts'dir.

Pakete özel Java derleyici işaretleri yapılandırması

default_java_toolchain öğesinin package_configuration özelliğini kullanarak belirli kaynak dosyaları için farklı Java derleyici işaretleri yapılandırabilirsiniz. Lütfen aşağıdaki örneği inceleyin.

load("@rules_java//toolchains: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
    ],
)

Tek bir depoda birden fazla Java kaynak kodu sürümü

Bazel, derlemede yalnızca tek bir Java kaynakları sürümünün derlenmesini destekler. build. Bu, bir Java testi veya uygulaması oluştururken tüm bağımlılıkların aynı Java sürümüne göre oluşturulduğu anlamına gelir.

Ancak farklı işaretler kullanılarak ayrı derlemeler yürütülebilir.

Farklı işaretleri kullanma görevini kolaylaştırmak için belirli bir sürümdeki işaret kümeleri .bazelrc yapılandırmalarıyla gruplandırılabilir:

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

Bu yapılandırmalar, örneğin --config işaretiyle kullanılabilir.bazel test --config=java11 //:java11_test