このページでは、Starlark の基本的なスタイル ガイドラインについて説明します。また、マクロとルールについても説明します。
Starlark は、ソフトウェアのビルド方法を定義する言語であるため、プログラミング言語であり構成言語でもあります。
Starlark を使用して、BUILD
ファイル、マクロ、ビルドルールを記述します。マクロとルールは基本的にメタ言語であり、BUILD
ファイルの作成方法を定義します。BUILD
ファイルはシンプルで反復的なファイルです。
すべてのソフトウェアは、書き込まれるよりも多くの回数で読み取られます。これは Starlark の場合に特に当てはまります。エンジニアは BUILD
ファイルを読み取って、ターゲットの依存関係とビルドの詳細を把握します。このような読み取りは、多くの場合、合格のとき、急いで行われた場合、または他のタスクの実行と並行して行われます。そのため、ユーザーが BUILD
ファイルをすばやく解析して理解できるようにするには、シンプルさと読みやすさが非常に重要です。
ユーザーが BUILD
ファイルを開いたときに、そのファイル内のターゲットのリストをすばやく確認したり、その C++ ライブラリのソースのリストを表示したり、その Java バイナリから依存関係を削除したりできます。抽象化レイヤを追加するたびに、ユーザーがこれらのタスクを行うことが困難になります。
BUILD
ファイルは、さまざまなツールによって分析、更新されます。抽象化を使用している場合、ツールで BUILD
ファイルを編集できないことがあります。BUILD
ファイルをシンプルに保つことで、より優れたツールを利用できます。コードベースの増大に伴い、ライブラリの更新やクリーンアップのために、多くの BUILD
ファイルに変更を加える頻度が高くなります。
一般的なアドバイス
- Buildifier をフォーマッタとリンターとして使用します。
- テスト ガイドラインに従ってください。
スタイル
Python スタイル
不明な点がある場合は、可能な限り PEP 8 スタイルガイドに従ってください。特に、Python の規則に合わせて、インデントに 2 つではなく 4 つのスペースを使用します。
Starlark は Python ではないため、Python スタイルのいくつかの側面は適用されません。たとえば PEP 8 では、Starlark の演算子ではない is
を使用してシングルトンと比較することが推奨されています。
docstring
docstring を使用して、ファイルと関数をドキュメント化します。各 .bzl
ファイルの上部にドキュメント コメントを使用し、公開関数ごとにドキュメント コメントを使用します。
ルールとアスペクトを文書化する
ルールとアスペクト、その属性、プロバイダとそのフィールドは、doc
引数を使用してドキュメント化する必要があります。
命名規則
- 変数名と関数名は小文字で、単語はアンダースコア(
[a-z][a-z0-9_]*
)で区切ります(cc_library
など)。 - 最上位の非公開値は 1 つのアンダースコアで始まります。Bazel では、他のファイルからプライベート値を使用できないようにします。ローカル変数では、アンダースコア接頭辞を使用しないでください。
行の長さ
BUILD
ファイルと同様に、ラベルは長くなる可能性があるため、厳密な行の長さの制限はありません。可能であれば、1 行あたり 79 文字以内に収めるようにしてください(Python のスタイルガイド PEP 8 に沿って)。このガイドラインは厳格に適用すべきではありません。エディタでは 80 列を超える列を表示する必要があります。また、変更を自動化すると頻繁に行が長くなるため、すでに読み取り可能な時間分割行を人間が費やすべきではありません。
キーワード引数
キーワード引数では、等号の前後のスペースが推奨されます。
def fct(name, srcs):
filtered_srcs = my_filter(source = srcs)
native.cc_library(
name = name,
srcs = filtered_srcs,
testonly = True,
)
ブール値
ブール値(ルールでブール値属性を使用する場合など)には、1
と 0
ではなく、True
と False
の値を優先します。
出力はデバッグ専用
本番環境コードで print()
関数を使用しないでください。この関数はデバッグ専用であり、.bzl
ファイルの直接ユーザーと間接ユーザーにすべてスパムを送信します。唯一の例外は、print()
がデフォルトで無効になっており、ソースの編集によってのみ有効にできる場合に、print()
を使用するコードを送信できることです。たとえば、print()
のすべての使用が if DEBUG:
でガードされ、DEBUG
が False
にハードコードされている場合などです。これらの記述が、読みやすさへの影響を正当化するほど有用かどうかに注意してください。
マクロ
マクロは、読み込みフェーズ中に 1 つ以上のルールをインスタンス化する関数です。一般的に、可能な限りマクロではなくルールを使用します。ユーザーに表示されるビルドグラフは、ビルド時に Bazel が使用するビルドグラフとは異なります。Bazel がビルドグラフ分析を行う前に、マクロが展開されます。
そのため、問題が発生した場合、ユーザーはマクロの実装を理解してビルドの問題をトラブルシューティングする必要があります。また、bazel
query
の結果はマクロの展開によって表示されるため、解釈が難しくなることがあります。最後に、アスペクトはマクロを認識しないため、アスペクトに依存するツール(IDE など)が失敗する可能性があります。
マクロを安全に使用するのは、Bazel CLI またはビルドファイルで直接参照する追加のターゲットを定義することです。この場合、それらのターゲットのエンドユーザーのみが認識する必要があり、マクロによって発生するビルドの問題は、その使用からそれほど離れていません。
生成されたターゲットを定義するマクロ(CLI で参照されることも、そのマクロによってインスタンス化されないターゲットによって依存されることもないマクロの実装の詳細)の場合は、次のベスト プラクティスに従ってください。
- マクロは
name
引数を取り、その名前のターゲットを定義する必要があります。そのターゲットがそのマクロのメイン ターゲットになります。 - 生成されたターゲット(マクロで定義された他のすべてのターゲット)は、次の条件を満たしている必要があります。
- 名前の先頭には
<name>
または_<name>
が付加されます。たとえば、name = '%s_bar' % (name)
を使用します。 - 公開設定が制限されている(
//visibility:private
)、 - ワイルドカード ターゲット(
:all
、...
、:*
など)での拡張を避けるために、manual
タグを用意します。
- 名前の先頭には
name
は、マクロで定義されたターゲットの名前を導出する場合にのみ使用し、それ以外には使用しないでください。たとえば、マクロ自体によって生成されていない依存関係や入力ファイルを名前を使用して導出しないでください。- マクロ内で作成されたすべてのターゲットは、なんらかの方法でメイン ターゲットに結合する必要があります。
- マクロ内のパラメータ名は一貫させます。パラメータを属性値としてメイン ターゲットに渡す場合は、名前を同じにします。マクロ パラメータが共通ルール属性(
deps
など)と同じ目的を果たす場合は、属性と同じように名前を付けます(下記を参照)。 - マクロを呼び出すときは、キーワード引数のみを使用します。これはルールに準拠しており、読みやすさが大幅に向上します。
エンジニアは、関連するルールの Starlark API が特定のユースケースに不十分な場合、ルールが Bazel 内でネイティブ コードで定義されているか Starlark で定義されているかにかかわらず、マクロを記述することがよくあります。この問題が発生した場合は、API を拡張して目標を達成できるかどうか、ルールの作成者に確認してください。
一般的なルールとして、マクロがルールに似ているほど効果的です。
マクロもご覧ください。
ルール
- ルール、アスペクト、およびその属性では、小文字の名前(「スネークケース」)を使用する必要があります。
- ルール名は、依存関係(またはリーフルールの場合はユーザー)の観点から、ルールによって生成されるアーティファクトの主な種類を表す名詞です。これはファイルの接尾辞である必要はありません。たとえば、Python 拡張機能として使用されるはずの C++ アーティファクトを生成するルールは、
py_extension
と呼ばれます。ほとんどの言語では、一般的なルールは次のとおりです。*_library
- コンパイル単位または「モジュール」。*_binary
- 実行可能ファイルまたはデプロイ ユニットを生成するターゲット。*_test
- テスト ターゲット。これには複数のテストを含めることができます。*_test
ターゲット内のすべてのテストは、同じテーマのバリエーションであると想定してください(1 つのライブラリをテストする場合など)。*_import
:.jar
やコンパイル中に使用される.dll
など、コンパイル済みのアーティファクトをカプセル化するターゲット。
- 属性の名前と型に一貫性を持たせます。一般に適用される属性には次のようなものがあります。
srcs
:label_list
。ファイル(通常は人間が作成したソースファイル)を許可します。deps
:label_list
。通常、ファイル: コンパイル依存関係を許可しません。data
:label_list
。許可されるファイル: データファイル(テストデータなど)。runtime_deps
:label_list
: コンパイルに不要なランタイム依存関係。
- 動作がわかりにくい属性(特別な置換を含む文字列テンプレートや、特定の要件で呼び出されるツールなど)については、属性の宣言(
attr.label_list()
など)にdoc
キーワード引数を使用してドキュメントを提供します。 - ルールの実装関数は、ほとんどの場合、プライベート関数(先頭にアンダースコアが付いた名前)にする必要があります。
myrule
の実装関数に_myrule_impl
という名前を付けるのが一般的なスタイルです。 - 明確に定義されたプロバイダ インターフェースを使用して、ルール間で情報を渡します。プロバイダ フィールドを宣言して文書化します。
- 拡張性を念頭に置いてルールを設計してください。他のルールによって、ルールとのやり取り、プロバイダへのアクセス、作成したアクションの再利用が必要になる場合があることを考慮してください。
- ルールのパフォーマンス ガイドラインに従います。