BUILD ファイル

問題を報告 ソースを表示 Nightly · 7.4 .

前のセクションでは、パッケージ、ターゲット、ラベル、ビルド依存関係グラフを抽象的に説明しました。このセクションでは、パッケージの定義に使用される具体的な構文について説明します。

定義上、すべてのパッケージには、短いプログラムである BUILD ファイルが含まれています。

BUILD ファイルは、命令型言語 Starlark を使用して評価されます。

これらは、ステートメントの連続したリストとして解釈されます。

一般的に、順序は重要です。たとえば、変数は使用前に定義する必要があります。ただし、ほとんどの BUILD ファイルはビルドルールの宣言のみで構成されており、これらのステートメントの相対順序は重要ではありません。重要なのは、パッケージの評価が完了するまでに、どのルールが宣言され、どのような値が設定されたかです。

cc_library などのビルドルール関数を実行すると、グラフに新しいターゲットが作成されます。このターゲットは、後でラベルを使用して参照できます。

シンプルな BUILD ファイルでは、動作を変更せずにルール宣言の順序を自由に並べ替えることができます。

コードとデータを明確に分離するために、BUILD ファイルには関数定義、for ステートメント、if ステートメントを含めることはできません（ただし、リスト コンプリメンテーションと if 式は許可されます）。関数は代わりに .bzl ファイルで宣言できます。また、BUILD ファイルでは *args 引数と **kwargs 引数を使用できません。代わりに、すべての引数を明示的にリストします。

重要な点として、Starlark のプログラムは任意の I/O を実行できません。この不変量により、BUILD ファイルの解釈は、既知の入力セットにのみ依存する完全な状態になります。これは、ビルドの再現性を保証するために不可欠です。詳細については、気密性をご覧ください。

BUILD ファイルは ASCII 文字のみを使用して書き込む必要がありますが、技術的には Latin-1 文字セットを使用して解釈されます。

BUILD ファイルは、基盤となるコードの依存関係が変更されるたびに更新する必要があるため、通常、チームの複数のユーザーが管理します。BUILD ファイルの作成者は、各ビルド ターゲットの役割（一般公開を目的としているかどうか）とパッケージ自体の役割を記述するために、自由にコメントする必要があります。

拡張機能の読み込み

Bazel 拡張機能は、末尾が .bzl のファイルです。拡張機能からシンボルをインポートするには、load ステートメントを使用します。

load("//foo/bar:file.bzl", "some_library")

このコードは、ファイル foo/bar/file.bzl を読み込み、some_library シンボルを環境に追加します。これを使用して、新しいルール、関数、定数（文字列やリストなど）を読み込むことができます。load の呼び出しに追加の引数を使用すると、複数のシンボルをインポートできます。引数は文字列リテラル（変数なし）にする必要があります。また、load ステートメントはトップレベルに配置する必要があります。関数本体に配置することはできません。

load の最初の引数は、.bzl ファイルを識別するラベルです。相対ラベルの場合は、現在の bzl ファイルを含むパッケージ（ディレクトリではない）に対して解決されます。load ステートメントの相対ラベルには、先頭に : を使用する必要があります。

load はエイリアスもサポートしているため、インポートされたシンボルに異なる名前を割り当てることができます。

load("//foo/bar:file.bzl", library_alias = "some_library")

1 つの load ステートメント内で複数のエイリアスを定義できます。また、引数リストにはエイリアスと通常のシンボル名の両方を指定できます。次の例は完全に合法です（引用符を使用するタイミングに注意してください）。

load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")

.bzl ファイルでは、_ で始まるシンボルはエクスポートされず、別のファイルから読み込むこともできません。

読み込みの公開設定を使用して、.bzl ファイルを読み込むユーザーを制限できます。

ビルドルールのタイプ

ほとんどのビルドルールは、言語ごとにグループ化されたファミリーで提供されます。たとえば、cc_binary、cc_library、cc_test は、それぞれ C++ バイナリ、ライブラリ、テストのビルドルールです。他の言語では、同じ命名規則が使用されますが、接頭辞が異なります（Java の場合は java_* など）。これらの関数の一部はビルド百科事典に記載されていますが、誰でも新しいルールを作成できます。

  • *_binary ルールは、特定の言語で実行可能プログラムをビルドします。ビルド後、実行可能ファイルは、ビルドツールのバイナリ出力ツリー内のルールのラベルに対応する名前に配置されます。たとえば、//my:program は $(BINDIR)/my/program に表示されます。

    一部の言語では、このようなルールによって、ルールに属する data 属性または依存関係の推移閉包内の任意のルールで指定されているすべてのファイルを含む runfiles ディレクトリも作成されます。このファイルセットは、本番環境へのデプロイを容易にするために 1 か所にまとめられます。

  • *_test ルールは、自動テストに使用される *_binary ルールの特殊化です。テストは、成功時にゼロを返す単純なプログラムです。

    バイナリと同様に、テストにもランファイル ツリーがあり、その下のファイルは、テストが実行時に正当に開くことができる唯一のファイルです。たとえば、プログラム cc_test(name='x', data=['//foo:bar']) は実行中に $TEST_SRCDIR/workspace/foo/bar を開いて読み取る場合があります。（各プログラミング言語には $TEST_SRCDIR の値にアクセスするための独自のユーティリティ関数がありますが、これらはすべて環境変数を直接使用する場合と同じです）。このルールを遵守しないと、リモート テストホストでテストを実行したときにテストが失敗します。

  • *_library ルールは、指定されたプログラミング言語で別々にコンパイルされたモジュールを指定します。ライブラリは他のライブラリに依存できます。また、バイナリとテストはライブラリに依存できます。この場合、分離コンパイル動作が想定されます。

ラベル 依存関係