これまでのセクションでは、パッケージ、ターゲット、ラベル、ビルド依存関係グラフを抽象的に説明しました。このセクションでは、パッケージを定義するために使用される具体的な構文について説明します。
定義上、すべてのパッケージには短いプログラムである 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_*
など)。これらの関数の一部は Build Encyclopedia に記載されていますが、誰でも新しいルールを作成できます。
*_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
ルールは、指定されたプログラミング言語で個別にコンパイルされたモジュールを指定します。ライブラリは他のライブラリに依存でき、バイナリとテストは想定される個別のコンパイル動作でライブラリに依存できます。
ラベル | 依存関係 |