Bazel 用語集

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。
問題を報告する ソースを表示

アクション

ビルド中に実行されるコマンド。アーティファクトを入力として受け取り、他のアーティファクトを出力として生成するコンパイラの呼び出しなど。コマンドライン引数、アクションキー、環境変数、宣言された入出力アーティファクトなどのメタデータが含まれます。

関連情報: ルールに関するドキュメント

アクションのキャッシュ

実行したアクションを、作成した出力にマッピングするディスク上のキャッシュ。キャッシュキーはアクションキーと呼ばれます。Bazel のインクリメンタリティ モデルのコア コンポーネント。キャッシュは出力ベース ディレクトリに保存されるため、Bazel サーバーの再起動後も保持されます。

アクション グラフ

アクションと、そのアクションが読み取って生成したアーティファクトのメモリ内グラフ。グラフには、ソースファイルとして存在するアーティファクト(ファイル システムなど)と、BUILD ファイルで指定されていない中間 / 最終アーティファクトが生成されます。分析フェーズで生成され、実行フェーズで使用されます。

アクション グラフのクエリ(aquery)

ビルドに対するクエリアクション。 これにより、ビルドルールがどのように実際の作業ビルドに変換されるかを分析できます。

アクションキー

アクションのキャッシュキー。アクションのメタデータに基づいて実行されます。これには、アクションで実行するコマンド、コンパイラ フラグ、ライブラリの場所、システム ヘッダーなどのコマンドが含まれます。Bazel で個々のアクションを確定的にキャッシュに保存または無効化できます。

分析フェーズ

ビルドの 2 番目のフェーズ。BUILD ファイルで指定されたターゲット グラフを処理して、実行フェーズで実行するアクションの順序を決定するメモリ内アクション グラフを生成します。このフェーズでは、ルールの実装が評価されます。

アーティファクト

ソースファイルまたは生成されたファイル。ツリー アーティファクトと呼ばれるファイルのディレクトリを指定することもできます。

アーティファクトは複数のアクションへの入力ですが、最大 1 つのアクションによってのみ生成する必要があります。

ファイル ターゲットに対応するアーティファクトには、ラベルでアドレス指定できます。

Aspect

ルールで依存関係に追加のアクションを作成するメカニズム。たとえば、ターゲット A が B に依存している場合、依存関係エッジを B まで移動して B で追加のアクションを実行し、追加の出力ファイルを生成して収集するアスペクトを A に適用できます。これらの追加のアクションは、同じ側面を必要とするターゲット間でキャッシュに保存され、再利用されます。aspect() Starlark Build API 関数を使用して作成されます。たとえば、IDE のメタデータを生成し、lint チェック用のアクションを作成する場合に使用できます。

関連情報: Aspect のドキュメント

アスペクト

他の側面の結果にアスペクトを適用できる構成メカニズム。たとえば、IDE で使用する情報を生成するアスペクトは、proto から .java ファイルを生成するアスペクトの上に適用できます。

アスペクト A をアスペクト B の上に適用するには、Bprovides 属性でアドバタイズするプロバイダが、required_aspect_providers 属性で宣言している A と一致する必要があります。

属性

ターゲットごとのビルド情報を表すために使用されるルールのパラメータ。例として、srcsdepscopts があります。これらはそれぞれ、ターゲットのソースファイル、依存関係、カスタム コンパイラ オプションを宣言します。特定のターゲットで使用可能な特定の属性は、ルールタイプによって異なります。

.bazelrc

Bazel の構成ファイル。起動フラグコマンドフラグのデフォルト値を変更します。また、--config フラグを使用すると、Bazel コマンドラインで共通のオプション グループを定義することもできます。Bazel は、複数の Bazel ファイル(システム全体、ワークスペースごと、ユーザーごと、またはカスタム ロケーションから)の設定を組み合わせることができます。また、bazelrc ファイルを使用して他の bazelrc ファイルから設定をインポートすることもできます。

Blaze

Bazel の Google 内部バージョン。モノ リポジトリ用の Google のメイン ビルドシステム。

BUILD ファイル

BUILD ファイルはメインのビルドファイルで、ビルドするソフトウェア出力とその依存関係、ビルド方法に関するものを Bazel に指示します。Bazel は、BUILD ファイルを入力として受け取り、それを使用して依存関係のグラフを作成します。中間および最終的なソフトウェア出力を構築するには、このアクションが必要になります。BUILD ファイルは、ディレクトリと、BUILD ファイルを含まないサブディレクトリをパッケージとしてマークし、ルールによって作成されたターゲットを格納できます。ファイルの名前は BUILD.bazel にすることもできます。

BUILD.bazel ファイル

BUILD ファイルをご覧ください。同じディレクトリの BUILD ファイルよりも優先されます。

.bzl ファイル

Starlark で記述されたルール、マクロ、定数を定義するファイル。その後、load() 関数を使用して BUILD ファイルにインポートできます。

グラフの作成

ビルドを実行するために Bazel によって構築および走査される依存関係グラフ。ターゲット構成されたターゲットアクションアーティファクトなどのノードが含まれます。リクエストされたターゲットのセットが依存するすべてのアーティファクトが最新の状態であることが検証されると、ビルドは完了したと見なされます。

ビルド設定

Starlark で定義された構成遷移ではビルド設定を設定して、サブグラフの構成を変更できます。コマンドライン フラグとしてユーザーに公開される場合(ビルドフラグとも呼ばれます)。

クリーンビルド

以前のビルドの結果を使用しないビルド。これは通常、増分ビルドよりも時間がかかりますが、通常は正しいとみなされます。Bazel は、クリーンビルドと増分ビルドの両方が正しいことを保証します。

クライアント サーバー モデル

bazel コマンドライン クライアントは、ローカルマシンでバックグラウンド サーバーを自動的に起動して、Bazel コマンドを実行します。サーバーはコマンド間で持続しますが、非アクティブな状態が続くと自動的に停止します(または、Bazel シャットダウンによって明示的に停止します)。Bazel をサーバーとクライアントに分割すると、アクション グラフがコマンド間でメモリに残るため、JVM の起動時間が平均化され、より迅速に増分ビルドがサポートされます。

コマンド

コマンドラインで、bazel buildbazel testbazel runbazel query などのさまざまな Bazel 関数を呼び出すために使用します。

コマンドフラグ

コマンドに固有のフラグのセット。コマンドフラグは、コマンド(bazel build <command flags>)の後に指定されます。フラグは 1 つ以上のコマンドに適用できます。たとえば、--configurebazel sync コマンド専用のフラグですが、--keep_goingsyncbuildtest などに適用できます。フラグは多くの場合、構成の目的で使用されます。フラグの値を変更すると、Bazel がメモリ内グラフを無効にして、分析フェーズを再開する可能性があります。

構成

ルールがアクションの生成方法に影響する、ルールの定義に含まれない情報。すべてのビルドには、ターゲット プラットフォーム、アクション環境変数、コマンドラインのビルドフラグを指定する構成が少なくとも 1 つあります。遷移によって、ホストツールやクロスコンパイルなどの追加の構成が作成される場合があります。

関連情報: 構成

構成のトリミング

ターゲットで実際に必要となる構成の一部のみを含めるプロセス。たとえば、C++ 依存関係 //:c を使用して Java バイナリ //:j をビルドする場合は、--javacopt の値を //:c の構成に含めるだけで無駄になります。--javacopt を変更すると、C++ ビルドのキャッシュ機能が不必要に破壊されるからです。

構成されたクエリ(cquery)

分析フェーズの完了後に、構成されたターゲットに対してクエリを実行するクエリツール。つまり、select()ビルドフラグ--platforms など)が結果に正確に反映されます。

関連項目: cquery のドキュメント

構成されたターゲット

構成を使用してターゲットを評価した結果。分析フェーズでは、ビルドのオプションと、ビルドが必要なターゲットを組み合わせ、これを生成します。たとえば、//:foo が同じビルドで 2 つの異なるアーキテクチャに対してビルドされている場合、<//:foo, x86><//:foo, arm> という 2 つのターゲットが構成されます。

正確性

出力が推移的入力の状態を忠実に反映している場合、ビルドは正解です。Bazel は、適切なビルドを実現するために、密閉性と再現性を維持し、ビルド分析アクション実行の決定論的試みを行います。

依存関係

2 つのターゲットの間にある有向エッジ。//:foo の属性値に //:bar への参照が含まれている場合、ターゲットの //:foo はターゲット //:barターゲットの依存関係を持ちます。//:foo のアクションが //:bar のアクションによって作成された入力アーティファクト//:barに依存している場合、//:foo//:barアクション依存関係を持ちます。

デプセット

推移的依存関係に関するデータを収集するためのデータ構造です。非常に大規模なディプセット(数十万のファイル)が発生することが多いため、デプトのマージは時間とスペースの効率を考慮して最適化されます。スペース効率の理由で他のデプトを再帰的に参照するために実装されました。ルールの実装では、ルールがビルドグラフの最上位にある場合を除き、依存関係をリストに変換してデプト処理を「フラット化」しないでください。大きなデプトをフラット化すると、大量のメモリ消費が発生します。Bazel の内部実装ではネストされたセットとも呼ばれます。

関連情報: Depset のドキュメント

ディスク キャッシュ

リモート キャッシュ機能用のローカル ディスク blob ストア。実際のリモート blob ストアと組み合わせて使用できます。

Distdir

Bazel がリポジトリ ルールを使用してインターネットから取得するファイルを含む、読み取り専用のディレクトリ。完全にオフラインで実行できるようにします。

動的実行

さまざまなヒューリスティックに基づいて、ローカル実行とリモート実行を選択し、より高速に成功したメソッドの実行結果を使用する実行戦略。一部のアクションは、ローカルで高速に(リンクなど)実行され、他はリモートで高速(並列化可能なコンパイルなど)で行われます。動的実行戦略により、可能な限り最適な増分ビルド時間と増分ビルド時間を実現できます。

実行フェーズ

ビルドの 3 番目のフェーズ。分析フェーズ中に作成されたアクション グラフアクションを実行します。これらのアクションは実行可能ファイル(コンパイラ、スクリプト)を呼び出して、アーティファクトの読み取りと書き込みを行います。スポーン戦略では、ローカル、リモート、動的、サンドボックス化、Docker などの、アクションの実行方法を制御します。

実行ルート

ローカルアクションサンドボックス化されていないビルドで実行される、ワークスペース出力ベースディレクトリ内のディレクトリ。ディレクトリの内容は、ほとんどがワークスペースからの入力アーティファクトのシンボリック リンクです。実行ルートには、他の入力として外部リポジトリへのシンボリック リンクと、出力を保存する bazel-out ディレクトリも含まれています。読み込みフェーズで、ビルドが依存するパッケージの一時的な終了を表すディレクトリのシンボリック フォレストを作成することによって準備します。コマンドラインで bazel info execution_root を使用してアクセスできます。

File

アーティファクトをご覧ください。

密閉性

ビルドとテスト オペレーションに外部の影響がない場合、ビルドは密閉的であり、結果が決定論的で正しいことを確認するのに役立ちます。たとえば、密閉型のビルドは通常、ネットワークに対するアクションへのアクセスを禁止し、宣言された入力へのアクセスを制限し、固定のタイムスタンプとタイムゾーンを使用して、環境変数へのアクセスを制限します。また、乱数ジェネレータの場合は固定シードを使用します。

増分ビルド

増分ビルドは、以前のビルドの結果を再利用して、ビルド時間とリソース使用量を削減します。依存関係の確認とキャッシュは、このタイプのビルドに対して正しい結果を生成することを目的としています。増分ビルドは、クリーンビルドの逆です。

ラベル

ターゲットの識別子。//path/to/package:target などの完全修飾ラベルは、// がワークスペースのルート ディレクトリをマークし、path/to/package がターゲットを宣言する BUILD ファイルを含むディレクトリ、:target が前述の BUILD ファイルで宣言されたターゲットの名前として構成されます。また、接頭辞 @my_repository//<..> を付けて、ターゲットが my_repository という名前の外部リポジトリで宣言されていることを示すこともできます。

読み込みフェーズ

ビルドの最初のフェーズで、Bazel が WORKSPACEBUILD.bzl ファイルを解析し、パッケージを作成します。このフェーズでは、マクロと特定の機能(glob() など)が評価されます。ビルドの第 2 フェーズ(分析フェーズ)とインターリーブされ、ターゲット グラフを作成します。

マクロ

複数のルール ターゲット宣言を単一の Starlark 関数で作成するメカニズム。BUILD ファイルで共通のルール宣言パターンを再利用できます。読み込みフェーズで、基になるルール ターゲットの宣言に拡張されます。

関連情報: マクロのドキュメント

ニーモニック

ルールの作成者が選択した、人が読める形式の短い文字列。ルール内のアクションのアクションをすばやく理解します。スポーン戦略の識別子としてニーモニックを使用できます。アクション ニーモニックの例としては、Java ルールの Javac、C++ ルールの CppCompile、Android ルールの AndroidManifestMerger などが挙げられます。

ネイティブ ルール

Bazel に組み込まれて Java で実装されたルール。このようなルールは、ネイティブ モジュール内の関数として .bzl ファイルに表示されます(例: native.cc_librarynative.java_library)。ユーザー定義ルール(非ネイティブ)は Starlark を使用して作成されます。

出力ベース

Bazel 出力ファイルを保存するワークスペース固有のディレクトリ。出力をワークスペースのソースツリーから分離するために使用されます。出力ユーザーのルートにあります。

出力グループ

Bazel がターゲットのビルドを完了したときにビルドされるファイルのグループ。ルールにより、通常の出力が「デフォルト出力グループ」に配置されます(例: cc_library ターゲットの java_library.a.so.jar ファイル)。デフォルトの出力グループは、コマンドラインでターゲットがリクエストされたときにアーティファクトがビルドされる出力グループです。ルールでは、BUILD ファイルfilegroup ルール)またはコマンドライン(--output_groups フラグ)で明示的に指定できる、より多くの名前付き出力グループを定義できます。

出力ユーザーのルート

Bazel の出力を保存するユーザー固有のディレクトリ。ディレクトリ名は、ユーザーのシステム ユーザー名から取得されます。複数のユーザーがシステム上で同じプロジェクトを同時にビルドしている場合に、出力ファイルの競合を防止します。個々のワークスペースのビルド出力に対応するサブディレクトリ(出力ベースとも呼ばれます)が含まれます。

パッケージ

BUILD ファイルによって定義されたターゲットのセット。パッケージ名は、ワークスペースのルートからの BUILD ファイルのパスです。パッケージには、サブパッケージ、または BUILD ファイルを含むサブディレクトリを含めることができるため、パッケージ階層を形成できます。

パッケージ グループ

パッケージのセットを表すターゲット。多くの場合、visibility 属性値で使用されます。

プラットフォーム

ビルドに含まれる「マシンタイプ」。これには、Bazel が動作しているマシン(「ホスト」プラットフォーム)、実行マシンのマシン(「exec」プラットフォーム)、マシン ターゲット(「ターゲット プラットフォーム」)が含まれます。

プロバイダ

依存関係の関係に沿ってルール ターゲット間で渡す情報単位を記述するスキーマ。通常、コンパイラ オプション、推移的ソースファイルまたは出力ファイル、ビルド メタデータなどの情報が含まれます。累積的な推移的データを効率的に保存するために depsets と組み合わせて使用することがよくあります。組み込みプロバイダの例は DefaultInfo です。

関連情報: プロバイダのドキュメント

クエリ(コンセプト)

ビルドグラフを分析して、ターゲット プロパティと依存関係の構造を理解するプロセス。Bazel は、querycqueryaquery の 3 つのクエリ バリアントをサポートしています。

クエリ(コマンド)

ビルドの読み込み後ターゲット グラフで動作するクエリツール。比較的高速ですが、select()ビルドフラグアーティファクト、ビルド アクションの影響を分析することはできません。

関連項目: クエリのハウツークエリ リファレンス

リポジトリのキャッシュ

Bazel がダウンロードし、ワークスペース間で共有できるファイルの共有可能なアドレス指定キャッシュ。初回ダウンロード後にオフライン ビルドを有効にします。http_archive などのリポジトリ ルールと repository_ctx.download などのリポジトリ ルール API によってダウンロードされたファイルをキャッシュに保存するために一般的に使用されます。ファイルは、ダウンロードに SHA-256 チェックサムが指定されている場合にのみキャッシュに保存されます。

再現性

ビルドまたはテストへの一連の入力が、時間、メソッド、環境に関係なく、常に毎回同じ出力を生成するビルドまたはテストのプロパティ。これは、出力が正しいこと、または目的の出力を意味するとは限りません。

ルール

cc_library などの BUILD ファイルでルール ターゲットを定義するスキーマ。BUILD ファイルの作成者の観点からは、ルールは一連の属性とブラック ボックス ロジックで構成されます。このロジックは、出力アーティファクトを生成し、他のルール ターゲットに情報を渡す方法をルール ターゲットに指示します。.bzl 作成者の観点から見ると、ルールは新しいプログラミング言語と環境をサポートするために Bazel を拡張する主要な方法です。

ルールはインスタンス化され、読み込みフェーズでルール ターゲットを生成します。分析フェーズルールでは、ターゲットは、プロバイダの形式でダウンストリームの依存関係に情報を伝達し、その出力アーティファクトの生成方法を説明するアクションを登録します。これらのアクションは実行フェーズで実行されます。

関連情報: ルールに関するドキュメント

ルールのターゲット

ルールのインスタンスであるターゲット。ターゲットはファイル ターゲットであり、パッケージ グループとは対照的です。ルールと混同しないでください。

ランファイル

実行可能ターゲットの実行時の依存関係。実行可能ファイルはテストルールの実行可能ファイルで、実行ファイルはテストの実行時のデータ依存関係です。(Bazel テスト中に)実行可能ファイルを呼び出す前に、Bazel はソース ディレクトリ構造に従ってテスト実行ファイルとともにランファイルのツリーを準備します。

関連項目: ランファイルのドキュメント

サンドボックス化

実行中のアクションを制限付き一時実行ルート内で分離する手法です。宣言されていない入力を読み取りたり、宣言されていない出力を書き込んだりしないようにします。サンドボックス化により密閉性が大幅に向上しますが、通常はパフォーマンス コストがかかり、オペレーティング システムのサポートが必要になります。パフォーマンス コストはプラットフォームによって異なります。Linux ではそれほど重要ではありませんが、macOS ではサンドボックスを使用できなくなる可能性があります。

スカイフレーム

Skyframe は、Bazel のコアかつ機能的なコア評価フレームワークです。

スタンピング

Bazel で構築されたアーティファクトに追加情報を埋め込む機能。たとえば、ソース管理、ビルド時間、リリースビルドのその他のワークスペースや環境関連の情報に使用できます。--workspace_status_command フラグと、スタンプ属性をサポートするルールによって有効にします。

スターラーク

ルールマクロを記述するための拡張言語。構成とパフォーマンスの向上を目的として、Python の一部のサブセット(構文的および文法的)があります。拡張子は .bzl を使用します。BUILD ファイルは、さらに制限されたバージョンの Starlark(def 関数の定義がないなど)(旧 Skylark)を使用します。

関連項目: Starlark 言語のドキュメント

起動フラグ

bazelコマンドの間に指定されたフラグのセット(bazel --host_jvm_debug ビルドなど)。これらのフラグは Bazel サーバーの構成を変更するため、起動フラグを変更するとサーバーの再起動が発生します。起動フラグはコマンドに固有のものではありません。

ターゲット

BUILD ファイルで定義され、ラベルで識別されるオブジェクト。ターゲットは、エンドユーザーから見たワークスペースのビルド可能な単位を表します。

ルールをインスタンス化して宣言されたターゲットは、ルールのターゲットと呼ばれます。ルールに応じて、実行可能(cc_binary など)またはテスト可能(cc_test など)である場合があります。ルールのターゲットは通常、属性deps など)によって他のターゲットに依存します。これらの依存関係はターゲット グラフの基礎となります。

ルール ターゲット以外にも、ファイル ターゲットとパッケージ グループ ターゲットがあります。ファイル ターゲットは、BUILD ファイル内で参照されるアーティファクトに対応しています。特別な場合として、パッケージの BUILD ファイルは、常にそのパッケージのソースファイル ターゲットとみなされます。

ターゲットは読み込みフェーズで検出されます。分析フェーズでは、ターゲットはビルド構成に関連付けられ、構成されたターゲットを形成します。

ターゲット グラフ

ターゲットとその依存関係のメモリ内グラフ。読み込みフェーズで生成され、分析フェーズへの入力として使用されます。

ターゲット パターン

コマンドラインでターゲットのグループを指定する方法。よく使用されるパターンは、:all(すべてのルール ターゲット)、:*(すべてのルール + ファイル ターゲット)、...(現在のパッケージ、すべてのサブパッケージを再帰的)です。組み合わせて使用できます。たとえば、//...:* は、ワークスペースのルートからすべてのパッケージ内のすべてのルールとファイル ターゲットが再帰的に発生することを意味します。

テスト

テストルールからインスタンス化されたルールターゲット。テスト実行ファイルが含まれます。実行可能ファイルの完了からの戻り値が 0 の場合は、テストが成功したことを示します。Bazel とテストの正確なコントラクト(テスト環境変数やテスト結果収集メソッドなど)は、Test Encyclopedia に記載されています。

ツールチェーン

言語の出力を作成するためのツールのセット。通常、ツールチェーンにはコンパイラ、リンカー、インタープリタ、リンターが含まれます。ツールチェーンはプラットフォームによって異なる場合もあります。同じ言語を使用している場合でも、Windows バリアントでは Unix コンパイラ ツールチェーンのコンポーネントが異なる場合があります。プラットフォームに適したツールチェーンの選択は、ツールチェーン解決と呼ばれます。

最上位のターゲット

ビルドのターゲットは、Bazel コマンドラインで要求された場合、最上位になります。たとえば、//:foo//:bar に依存し、bazel build //:foo が呼び出された場合、このビルドでは、//:foo はトップレベルであり、//:bar はトップレベルではありませんが、両方のターゲットをビルドする必要があります。トップレベル ターゲットと非トップレベル ターゲットの重要な違いは、Bazel コマンドライン(または .bazelrc 経由)で設定されたコマンドフラグによってトップレベル ターゲットの構成が設定される一方、非トップレベル ターゲットの場合は遷移によって変更される場合がある点です。

移行

ある値から別の値への構成状態のマッピング。 同じルールからインスタンス化されても、ビルドグラフターゲットが異なる構成を持つことができます。遷移の一般的な用途は、分割遷移です。ターゲット グラフの特定の部分が、フォークごとに異なる構成でフォークされます。たとえば、1 つのビルドで分割遷移を使用して、ARM と x86 用にコンパイルされたネイティブ バイナリを含む Android APK をビルドできます。

関連情報: ユーザー定義の移行

ツリー アーティファクト

ファイルのコレクションを表すアーティファクト。これらのファイル自体はアーティファクトではないため、ファイルに対するアクションでは、そのツリー アーティファクトを入力または出力として登録する必要があります。

公開設定

ビルドシステムで不要な依存関係を防ぐための 2 つのメカニズムの 1 つは、ターゲットを他のターゲットに依存可能にするかどうかを制御するターゲットの可視性と、BUILD または .bzl ファイルが特定の .bzl データを読み込むことができるかどうかを制御する可視性です。コンテキストがない場合、通常は可視性はターゲットの公開設定を指します。

関連情報: 公開設定に関するドキュメント

ワークスペース

ビルドするソフトウェアの WORKSPACE ファイルとソースコードを含むディレクトリ。// で始まるラベルは、ワークスペース ディレクトリからの相対パスです。

WORKSPACE ファイル

ディレクトリを「ワークスペース」として定義します。このファイルは空にすることもできますが、通常は、ネットワークまたはローカル ファイル システムから追加の依存関係を取得するための外部リポジトリ宣言が含まれています。