Java と Bazel

このページでは、Java プロジェクトで Bazel を使用する際に役立つリソースを紹介します。Bazel を使用した Java プロジェクトのビルドに固有のチュートリアル、ビルドルール、その他の情報へのリンクがあります。

Bazel の操作

Java プロジェクトで Bazel を使用する場合は、次のリソースをご覧ください。

• チュートリアル: Java プロジェクトのビルド
• Java ルール

Bazel への移行

現在 Maven を使用して Java プロジェクトをビルドしている場合は、移行ガイドの手順に沿って Bazel を使用した Maven プロジェクトの構築を開始してください。

• Maven から Bazel への移行

Java のバージョン

構成フラグで設定される Java には、次の 2 つの関連するバージョンがあります。

• リポジトリ内のソースファイルのバージョン
• コードの実行とテストに使用される Java ランタイムのバージョン

リポジトリ内のソースコードのバージョンを構成する

追加の構成がない場合、Bazel は、リポジトリ内のすべての Java ソースファイルが単一の Java バージョンで記述されていると想定します。リポジトリ内のソースのバージョンを指定するには、build --java_language_version={ver} を .bazelrc ファイルに追加します。ここで、{ver} は 11 です。Bazel リポジトリのオーナーは、Bazel とそのユーザーがソースコードの Java バージョン番号を参照できるように、このフラグを設定する必要があります。詳細については、Java 言語バージョン フラグをご覧ください。

コードの実行とテストに使用する JVM を構成する

Bazel はコンパイルに 1 つの JDK を使用し、コードの実行とテストに別の JVM を使用します。

デフォルトでは、Bazel はダウンロードした JDK を使用してコードをコンパイルし、ローカルマシンにインストールされた JVM でコードを実行し、テストします。Bazel は、JAVA_HOME またはパスを使用して JVM を検索します。

生成されるバイナリは、システム ライブラリでローカルにインストールされている JVM と互換性があります。つまり、生成されるバイナリはマシンにインストールされているものによって異なります。

実行とテストに使用する JVM を構成するには、--java_runtime_version フラグを使用します。デフォルト値は local_jdk です。

密閉型のテストとコンパイル

密閉型のコンパイルを作成するには、コマンドライン フラグ --java_runtime_version=remotejdk_11 を使用します。コードは、リモート リポジトリからダウンロードした JVM でコンパイル、実行、テストされます。詳細については、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 用のコンパイル ツールチェーンを使用する）を使用してコンパイルするには、追加のフラグ --extra_toolchains=@local_jdk//:all を使用します。ただし、これは任意のベンダーの JDK では機能しない場合があります。

詳細については、Java ツールチェーンの構成をご覧ください。

ベスト プラクティス

Bazel の一般的なベスト プラクティスに加えて、Java プロジェクトに固有のベスト プラクティスを以下に示します。

ディレクトリ構造

Maven の標準ディレクトリ レイアウトを優先します（src/main/java の下にあるソース、src/test/java にあるテスト）。

BUILD ファイル

BUILD ファイルを作成する場合は、以下のガイドラインに従ってください。

• Java ソースを含むディレクトリごとに 1 つの BUILD ファイルを使用します。これにより、ビルドのパフォーマンスが向上します。

• すべての BUILD ファイルに、次のような java_library ルールを 1 つ含める必要があります。

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

• ライブラリの名前は、BUILD ファイルを含むディレクトリの名前にする必要があります。これにより、ライブラリのラベルが短くなり、"//package:package" ではなく "//package" が使用されます。

• ソースは、ディレクトリ内のすべての Java ファイルの非再帰的な glob にする必要があります。

• テストは src/test の下の一致するディレクトリに配置する必要があり、このライブラリに依存します。

高度な Java ビルドの新しいルールの作成

注: 新しいルールの作成は、高度なビルドとテストシナリオを対象としています。Bazel を使用する場合は、これは必要ありません。

次のモジュール、構成フラグメント、プロバイダは、Java プロジェクトをビルドする際に Bazel の機能を拡張するのに役立ちます。

• メインの Java プロバイダ: java_common
• メイン Java モジュール: JavaInfo
• 構成フラグメント: java

• その他のモジュール:

  • java_annotation_processing
  • java_compilation_info
  • java_output
  • java_output_jars
  • JavaRuntimeInfo
  • JavaToolchainInfo

Java ツールチェーンの構成

Bazel では、次の 2 種類の Java ツールチェーンを使用します。- 実行、Java バイナリの実行とテストに使用、--java_runtime_version フラグで制御 - コンパイル、Java ソースのコンパイル、--java_language_version フラグで制御

追加の実行ツールチェーンの構成

実行ツールチェーンは、ローカルまたはリポジトリの JVM にバージョン、オペレーティング システム、CPU アーキテクチャに関する追加情報が入った JVM です。

Java 実行ツールチェーンは、WORKSPACE ファイルで local_java_repository ルールまたは remote_java_repository ルールを使用して追加できます。ルールを追加すると、フラグを使用して 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
)

リモート 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 = ...
)

追加のコンパイル ツールチェーンの構成

コンパイル ツールチェーンは、コンパイル時に Bazel が使用する JDK と複数のツールで構成され、Error Prone、厳密な Java 依存関係、ヘッダー コンパイル、Android の desugar、カバレッジ インストルメンテーション、IDE 用の genclass 処理などの追加機能を提供します。

JavaBuilder は Bazel にバンドルされたツールで、コンパイルを実行し、前述の機能を提供します。実際のコンパイルは、JDK により内部コンパイラを使用して実行されます。コンパイルに使用される JDK は、ツールチェーンの java_runtime 属性で指定されます。

Bazel は、一部の JDK の内部をオーバーライドします。JDK バージョン 9 より後の場合は、JDK フラグ --patch_module を使用して java.compiler モジュールと jdk.compiler モジュールにパッチが適用されます。JDK バージョン 8 の場合、-Xbootclasspath フラグを使用して Java コンパイラにパッチが適用されます。

VanillaJavaBuilder は JavaBuilder の 2 番目の実装です。この実装では JDK の内部コンパイラを変更せず、追加機能はありません。VanillaJavaBuilder は、組み込みツールチェーンのいずれでも使用しません。

Bazel は、JavaBuilder の他にもコンパイル時にいくつかのツールを使用します。

ijar ツールは、jar ファイルを処理して、コール署名を除くすべてを削除します。生成される JAR はヘッダー JAR と呼ばれます。関数の本文が変更されたときにダウンストリームの依存ファイルのみを再コンパイルすることで、コンパイルのインクリメンタリティを改善するために使用されます。

singlejar ツールは、複数の jar ファイルを 1 つにパッキングします。

genclass ツールは Java コンパイルの出力の後処理を行い、アノテーション プロセッサによって生成されたソースのクラスファイルのみを含む jar を生成します。

JacocoRunner ツールは、インストゥルメント化されたファイルに対して Jacoco を実行し、結果を LCOV 形式で出力します。

TestRunner ツールは、制御された環境で JUnit 4 テストを実行します。

コンパイルを再構成するには、BUILD ファイルに default_java_toolchain マクロを追加し、WORKSPACE ファイルに register_toolchains ルールを追加するか、--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 コンパイラ フラグの構成

default_java_toolchain の package_configuration 属性を使用すると、特定のソースファイルに対してさまざまな Java コンパイラ フラグを構成できます。以下の例を参照してください。

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 構成ファイルでグループ化できます。

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）。