プラットフォームを使った構築

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

Bazel は、プラットフォームとツールチェーンのモデリングを高度にサポートしています。これを実際のプロジェクトに統合するには、コード所有者、ルールメンテナー、コア Bazel デベロッパー間の慎重な連携が必要です。

このページでは、プラットフォームの目的と、プラットフォームを使用したビルド方法について説明します。

要約: Bazel のプラットフォームとツールチェーンの API は利用可能ですが、すべての言語ルール、select()、その他のレガシー参照が更新されるまで、どこでも機能するわけではありません。これは継続的な取り組みです。最終的には、すべてのビルドがプラットフォームベースになります。ビルドがどこに適合するかについては、以下をご覧ください。

より正式なドキュメントについては、以下をご覧ください。

背景

ソフトウェアプロジェクトがさまざまなマシンをターゲットとし、適切な言語ツールでビルドする方法を標準化するために、プラットフォームとツールチェーンが導入されました。

これは、Bazel に比較的最近追加されたものです。言語メンテナーがアドホックで互換性のない方法でこれを行っているという観察から着想を得ました。たとえば、C++ ルールでは、--cpu と --crosstool_top を使用して、ビルドのターゲット CPU と C++ ツールチェーンを設定します。どちらも「プラットフォーム」を正しくモデル化していません。これを行おうとすると、不自然で不正確なビルドが発生しました。また、これらのフラグは Java コンパイルを制御しません。Java コンパイルは、独自の独立したインターフェースを--java_toolchain使用して進化させました。

Bazel は、大規模な多言語、マルチプラットフォームプロジェクトを対象としています。そのため、言語とプロジェクトの相互運用性を促進する明確な API など、これらのコンセプトに対するより原則的なサポートが求められます。これらが新しい API の目的です。

移行

プラットフォームとツールチェーンの API は、プロジェクトが実際に使用する場合にのみ機能します。プロジェクトのルールロジック、ツールチェーン、依存関係、 select() がサポートしている必要があるため、これは簡単ではありません。すべてのプロジェクトとその依存関係が正しく機能するように、慎重な移行シーケンスが必要です。

たとえば、Bazel の C++ ルールはプラットフォームをサポートしています。ただし、Apple ルールはサポートしていません。C++ プロジェクトは Apple を気にしないかもしれません。しかし、他のプロジェクトはそうかもしれません。そのため、すべての C++ ビルドでプラットフォームをグローバルに有効にすることはまだ安全ではありません。

このページの残りの部分では、この移行シーケンスと、プロジェクトがいつどのように適合するかについて説明します。

目標

すべてのプロジェクトが次の形式でビルドされると、Bazel のプラットフォーム移行が完了します。

bazel build //:myproject --platforms=//:myplatform

これは以下を意味します。

プロジェクトで使用するルールは、 //:myplatform から正しいツールチェーンを推測できます。
プロジェクトの依存関係で使用するルールは、正しいツールチェーンを推測できます from //:myplatform.
プロジェクトに依存するプロジェクトが //:myplatform をサポートしているか、プロジェクトがレガシー API（--crosstool_top など）をサポートしている必要があります。
//:myplatform は、プロジェクト間の自動互換性をサポートする CPU、OS、その他の汎用コンセプトの [共通宣言][Common Platform Declaration]{: .external} を参照します。
関連するすべてのプロジェクトの select()s は、//:myplatformで暗示されるマシンプロパティを理解します。
//:myplatform は、明確で再利用可能な場所に定義されます。プラットフォームがプロジェクトに固有の場合はプロジェクトのリポジトリに、それ以外の場合はこのプラットフォームを使用する可能性のあるすべてのプロジェクトが検索できる場所に定義されます。

この目標が達成されるとすぐに、古い API は削除されます。その後、プロジェクトがプラットフォームとツールチェーンを選択する標準的な方法になります。

プラットフォームを使用する必要がありますか？

プロジェクトをビルドまたはクロスコンパイルする場合は、プロジェクトの公式ドキュメントに従ってください。

プロジェクト、言語、ツールチェーンのメンテナーは、最終的に新しい API をサポートする必要があります。グローバル移行が完了するまで待つか早期にオプトインするかは、具体的な価値 / コストのニーズによって異なります。

値

関心のある正確なプロパティでツールチェーンを select() または選択できます。代わりに、--cpu などのハードコードされたフラグを使用します。たとえば、複数の CPU が同じ命令セットをサポートできます。
より正確なビルド。上記の例で select() を使用して --cpu し、同じ命令セットをサポートする新しい CPU を追加すると、select() は新しい CPU を認識できません。ただし、プラットフォームでの select() は正確なままです。
シンプルなユーザーエクスペリエンス。すべてのプロジェクトが --platforms=//:myplatform を理解します。コマンドラインで言語固有のフラグを複数指定する必要はありません。
シンプルな言語設計。すべての言語で、ツールチェーンの定義、ツールチェーンの使用、プラットフォームに適したツールチェーンの選択に共通の API を使用します。
ターゲットプラットフォームと互換性がない場合、ビルドフェーズとテストフェーズでターゲットをスキップできます。

料金

プラットフォームをまだサポートしていない依存プロジェクトは、自動的に動作しない可能性があります。
動作させるには、一時的なメンテナンスが必要になる場合があります。
新しい API とレガシー API の共存には、混乱を避けるために、より慎重なユーザーガイダンスが必要です。
一般的なプロパティの正規定義はまだ進化しており、追加の初期貢献が必要になる場合があります。OSCPU
言語固有のツールチェーンの正規定義はまだ進化しており、追加の初期貢献が必要になる場合があります。

API による審査

platform は constraint_value ターゲットのコレクションです。

platform(
    name = "myplatform",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

A constraint_value はマシンプロパティです。同じ「種類」の値は、共通の constraint_settingの下にグループ化されます。

constraint_setting(name = "os")
constraint_value(
    name = "linux",
    constraint_setting = ":os",
)
constraint_value(
    name = "mac",
    constraint_setting = ":os",
)

toolchain は Starlark ルールです。その属性は、言語のツール（compiler = "//mytoolchain:custom_gcc"など）を宣言します。そのプロバイダは、これらのツールでビルドする必要があるルールにこの情報を渡します。

ツールチェーンは、ターゲットにできるマシンのconstraint_value（target_compatible_with = ["@platforms//os:linux"]）と、ツールを実行できるマシン（exec_compatible_with = ["@platforms//os:mac"]）を宣言します。

$ bazel build //:myproject --platforms=//:myplatform をビルドすると、Bazel はビルドマシンで実行でき、//:myplatform のバイナリをビルドできるツールチェーンを自動的に選択します。これはツールチェーンの解決と呼ばれます。

使用可能なツールチェーンのセットは、WORKSPACE で register_toolchains を使用して登録するか、コマンドラインで --extra_toolchains を使用して登録できます。

詳細については、こちらをご覧ください。

ステータス

現在のプラットフォームのサポートは言語によって異なります。Bazel の主要なルールはすべてプラットフォームに移行しています。ただし、このプロセスには時間がかかります。これには主に 3 つの理由があります。

新しいツールチェーン API（ctx.toolchains）からツール情報を取得し、 --cpu や --crosstool_top などのレガシー設定の読み取りを停止するように、ルールロジックを更新する必要があります。これは比較的簡単です。
ツールチェーンのメンテナーは、ツールチェーンを定義し、ユーザーがアクセスできるようにする必要があります（GitHub リポジトリと WORKSPACE エントリ）。これは技術的には簡単ですが、ユーザーエクスペリエンスを維持するためにインテリジェントに整理する必要があります。

プラットフォーム定義も必要です（Bazel が実行されるマシンと同じマシンでビルドする場合を除く）。通常、プロジェクトは独自のプラットフォームを定義する必要があります。
既存のプロジェクトを移行する必要があります。select() と切り替えも移行する必要があります。これが最大の課題です。特に、多言語プロジェクトでは困難です（すべての言語で --platformsを読み取れない場合、失敗する可能性があります）。

新しいルールセットを設計する場合は、最初からプラットフォームをサポートする必要があります。これにより、プラットフォーム API が普及するにつれて価値が高まり、ルールが他のルールやプロジェクトと自動的に互換性を持つようになります。

一般的なプラットフォームプロパティ

プロジェクト間で共通の OS や CPU などのプラットフォームプロパティは、標準化された一元的な場所で宣言する必要があります。これにより、プロジェクト間および言語間の互換性が促進されます。

たとえば、MyApp に constraint_value @myapp//cpus:arm の select() があり、SomeCommonLib に @commonlib//constraints:arm の select() がある場合、これらは互換性のない条件で「arm」モードをトリガーします。

グローバルに共通のプロパティは @platforms リポジトリで宣言されます（上記の例の正規ラベルは @platforms//cpu:arm です）。言語に共通のプロパティは、それぞれの言語のリポジトリで宣言する必要があります。

デフォルトのプラットフォーム

通常、プロジェクトオーナーは、ビルドするマシンの種類を記述する明示的なプラットフォームを定義する必要があります。これらは --platformsでトリガーされます。

--platforms が設定されていない場合、Bazel はデフォルトでローカルビルドマシンを表す platform になります。これは @local_config_platform//:host で自動生成されるため、明示的に定義する必要はありません。ローカルマシンの OS と CPU を constraint_values で宣言された @platformsにマッピングします。

C++

Bazel の C++ ルールは、プラットフォームを使用してツールチェーンを選択します。これは、 --incompatible_enable_cc_toolchain_resolution （#7260）を設定した場合です。

つまり、C++ プロジェクトを次のように構成できます。

bazel build //:my_cpp_project --platforms=//:myplatform

レガシーの代わりに:

bazel build //:my_cpp_project` --cpu=... --crosstool_top=...  --compiler=...

プロジェクトが純粋な C++ であり、C++ 以外のプロジェクトに依存していない場合は、プラットフォームを安全に使用できます。ただし、selectと切り替えが互換性がある場合に限ります。詳細については、 #7260 と C++ ツールチェーンの構成をご覧ください。

このモードはデフォルトでは有効になっていません。これは、Apple プロジェクトが --cpu と --crosstool_top （例）を使用して C++ 依存関係を構成しているためです。そのため、これは Apple ルールがプラットフォームに移行するかどうかによって異なります。

Java

Bazel の Java ルールはプラットフォームを使用します。

これにより、レガシーフラグ --java_toolchain、--host_java_toolchain、 --javabase、--host_javabase が置き換えられます。

構成フラグの使用方法については、Bazel と Java のマニュアルをご覧ください。詳細については、設計ドキュメントをご覧ください。

レガシーフラグをまだ使用している場合は、Issue #7849 の移行プロセスに従ってください。

Android

Bazel の Android ルールは、 --incompatible_enable_android_toolchain_resolution を設定すると、プラットフォームを使用してツールチェーンを選択します。

これはデフォルトでは有効になっていません。ただし、移行は順調に進んでいます。

Apple

Bazel の Apple ルールは、Apple ツールチェーンを選択するプラットフォームをまだサポートしていません。

また、プラットフォーム対応の C++ 依存関係もサポートしていません。これは、レガシー --crosstool_top を使用して C++ ツールチェーンを設定するためです。これが移行されるまで、Apple プロジェクトとプラットフォーム対応の C++ をプラットフォームマッピング（例）と組み合わせることができます。

その他の言語

Bazel の Rust ルールはプラットフォームを完全にサポートしています。
Bazel の Go ルールはプラットフォームを完全にサポートしています（詳細）。

新しい言語のルールを設計する場合は、プラットフォームを使用して言語のツールチェーンを選択します。詳細については、ツールチェーンのドキュメントをご覧ください。

`select()`

プロジェクトは select() ターゲットで constraint_value できますが、完全なプラットフォームではできません。これは、select() ができるだけ多くの種類のマシンをサポートするように意図されています。ARM-specific ソースを含むライブラリは、より具体的な理由がない限り、 すべての ARM-搭載マシンをサポートする必要があります。

1 つ以上の constraint_value で選択するには、次のようにします。

config_setting(
    name = "is_arm",
    constraint_values = [
        "@platforms//cpu:arm",
    ],
)

これは、従来 --cpu で選択するのと同じです。

config_setting(
    name = "is_arm",
    values = {
        "cpu": "arm",
    },
)

詳しくはこちらをご覧ください。こちら。

select は --cpu、--crosstool_top などの `select` を認識しません。--platformsプロジェクトをプラットフォームに移行する場合は、に変換するか、プラットフォームマッピングを使用して移行期間中に両方のスタイルをサポートする必要があります。constraint_values

切り替え効果

Starlark の切り替えは、ビルドグラフの一部でフラグを変更します。プロジェクトで、 --cpu、--crossstool_top、その他のレガシーフラグを設定する切り替えを使用している場合、 --platforms を読み取るルールではこれらの変更は認識されません。

プロジェクトをプラットフォームに移行する場合は、 return { "//command_line_option:cpu": "arm" } などの変更を return { "//command_line_option:platforms": "//:my_arm_platform" } に変換するか、プラットフォームマッピングを使用して移行期間中に両方のスタイルをサポートする必要があります。

現在のプラットフォームの使用方法

プロジェクトをビルドまたはクロスコンパイルする場合は、プロジェクトの公式ドキュメントに従ってください。プラットフォームとの統合方法とタイミング、およびその価値を判断するのは、言語とプロジェクトのメンテナーです。

プロジェクト、言語、ツールチェーンのメンテナーで、ビルドでデフォルトでプラットフォームを使用しない場合は、グローバル移行を待つ以外に 3 つのオプションがあります。

プロジェクトの言語（存在する場合）の [プラットフォームを使用] フラグをオンにして、関心のあるプロジェクトが動作するかどうかを確認するために必要なテストを行います。
関心のあるプロジェクトが --cpu や --crosstool_top などのレガシーフラグに依存している場合は、これらを --platforms と組み合わせて使用します。
```
bazel build //:my_mixed_project --platforms==//:myplatform --cpu=... --crosstool_top=...
```
これにはメンテナンスコストがかかります（設定が一致していることを手動で確認する必要があります）。ただし、不正な切り替えがない場合は、これで動作するはずです。
両方のスタイルをサポートするために、プラットフォームマッピングを作成し、 --cpu スタイルの設定を対応するプラットフォームにマッピングし、その逆も同様に行います。

プラットフォームマッピング

プラットフォームマッピングは、プラットフォーム対応ロジックとレガシー対応ロジックが、後者の非推奨期間中に同じビルドに共存できるようにする一時的な API です。

プラットフォームマッピングは、platform() から対応するレガシーフラグのセットへのマッピング、またはその逆のマッピングです。次に例を示します。

platforms:
  # Maps "--platforms=//platforms:ios" to "--cpu=ios_x86_64 --apple_platform_type=ios".
  //platforms:ios
    --cpu=ios_x86_64
    --apple_platform_type=ios

flags:
  # Maps "--cpu=ios_x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
  --cpu=ios_x86_64
  --apple_platform_type=ios
    //platforms:ios

  # Maps "--cpu=darwin --apple_platform_type=macos" to "//platform:macos".
  --cpu=darwin
  --apple_platform_type=macos
    //platforms:macos

Bazel はこれを使用して、プラットフォームベースとレガシーの両方のすべての設定が、切り替えを含め、ビルド全体に一貫して適用されるようにします。

デフォルトでは、Bazel はワークスペースルートの platform_mappings ファイルからマッピングを読み取ります。 --platform_mappings=//:my_custom_mapping を設定することもできます。

詳細については、こちらをご覧ください。

質問

一般的なサポートと移行タイムラインに関する質問については、 bazel-discuss@googlegroups.com または適切なルールのオーナーにお問い合わせください。

プラットフォーム/ツールチェーン API の設計と進化に関するディスカッションについては、次にご連絡ください bazel-dev@googlegroups.com。

プラットフォームを使った構築 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

背景

移行

目標