.bzl スタイルガイド

<ph type="x-smartling-placeholder"></ph> 問題を報告するソースを表示夜間 · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

このページでは、Starlark の基本的なスタイルガイドラインについて説明します。また、詳細を確認できます。

Starlark は、ソフトウェアの構築方法を定義する言語であり、したがって、構成言語を使用します。

Starlark を使用して、BUILD ファイル、マクロ、ビルドルールを記述します。マクロとルールは基本的にメタ言語であり、BUILD ファイルの作成方法を定義します。 BUILD ファイルは、シンプルで反復的なものであることが意図されています。

すべてのソフトウェアは、書き込みよりも頻繁に読み取られます。これは特に Starlark。エンジニアは、BUILD ファイルを読み取って、依存関係を把握します。ビルドの詳細を確認できます。多くの場合、こうした読み取りは、急いでいることも、他の作業を並行して行うこともあります。その結果シンプルさと読みやすさが非常に重要です。 BUILD ファイルをすばやく理解できます。

ユーザーが BUILD ファイルを開いたときに、ファイルその C++ ライブラリのソースのリストを確認すること。削除するか、 Java バイナリから依存関係を作成します。抽象化レイヤを追加するたびに、ユーザーが行う操作が難しくなります

BUILD ファイルもさまざまなツールで分析、更新されます。ツールによる禁止抽象化を使用している場合、BUILD ファイルを編集できるようになります。BUILD を引き続きご利用くださいファイルをシンプルにすることで、より優れたツールを利用できます。コードベースが大きくなるにつれてそのため、多数の BUILD ファイルに変更を加える頻度がますます高まっています。ライブラリの更新やクリーンアップを行います

一般的なアドバイス

Buildifier を使用する（フォーマッタやリンターとして指定）
テストガイドラインに従ってください。

スタイル

Python スタイル

疑わしい場合は、可能であれば PEP 8 スタイルガイドを参照してください。特に、末尾にスペースを設けるためにインデントに 2 つではなく 4 つのスペースを使用する Python の規則に従います。

以降 Starlark は Python ではありません。 Python スタイルの一部の側面は適用されません。たとえば PEP 8 では、シングルトンとの比較は is で実行します。これは次の言語の演算子ではありませんスターラーク。

docstring

docstring を使用してファイルや関数をドキュメント化します。各 .bzl ファイルの先頭に docstring があり、各公開ファイルには docstring を使用します。使用します。

ルールとアスペクトを文書化する

ルールとアスペクト、その属性、プロバイダと 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 はデバッグにのみ使用する

本番環境のコードでは print() 関数を使用しないでください。Chronicle SOAR はデバッグを行い、.bzl ファイルの直接的および間接的なすべてのユーザーにスパム行為を働きます。「唯一の例外として、print() が無効になっている場合は、それを使用したコードを送信できます。これはソースを編集することによってのみ有効にできます。たとえば、 print() の使用は if DEBUG: によって保護されています。DEBUG は False。これらの記述が、正当化するのに十分有用であるかどうかに留意してください。理解しやすくなっています。

マクロ

マクロは読み込み時に 1 つ以上のルールをインスタンス化する関数であるあります一般的に、可能な限りマクロではなくルールを使用します。ビルドユーザーが見るグラフが、期間中に Bazel で使用したグラフと異なっている build - Bazel によるビルドグラフ分析の前に、マクロが展開されます。

そのため、何か問題が起きたときには、マクロの実装方法を確認して、ビルドの問題のトラブルシューティングを行います。また、bazel query の結果はターゲットに表示されるため、解釈が難しくなる場合があります。マクロ展開によって生じる問題です最後に、アスペクトはマクロを認識しないため、一部の要素（IDE など）によっては失敗する可能性があります。

マクロを安全に使用すると、追加のターゲットを Bazel CLI または BUILD ファイルで直接参照できます。この場合、そのターゲットのエンドユーザーが、それらについて知っておくべきことと、ビルドの問題がある場合マクロによって導入されるものも、その用途にはあまりかけられません。

生成されたターゲット（マクロの実装の詳細）を定義するマクロの場合 CLI で参照されることが想定されていないものや、ターゲットによって依存されることは想定されていないもの。インスタンス化されていない場合）、次のベストプラクティスに従ってください。

マクロは name 引数を受け取り、その名前でターゲットを定義する必要があります。このターゲットが、そのマクロのメインターゲットになります。
生成されたターゲット（マクロで定義された他のすべてのターゲット）は、次の条件を満たしている必要があります。
- 名前の先頭には <name> または _<name> が付加されます。たとえば、 name = '%s_bar' % (name)。
- 公開が制限されている（//visibility:private）
- ワイルドカードのターゲットで展開されないように manual タグを含める（:all、 ...、:* など）。
name は、マクロで指定し、その他のアクションは行いません。たとえば、この名前を使用してマクロ自体では生成されない依存関係または入力ファイル。
マクロで作成したターゲットはすべて、なんらかの方法で主なターゲットの 1 つです
マクロ内のパラメータ名は一貫したものにしてください。パラメータが属性値としてメインのターゲットに指定する場合は、名前を変更しないでください。マクロが共通のルール属性と同じ目的を果たします。 deps は、属性と同様の名前を付けます（下記参照）。
マクロを呼び出すときは、キーワード引数のみを使用します。これは以下と一致しています。読みやすさが大幅に向上します。

エンジニアがマクロを記述するのは、関連するルールの Starlark API がルールが特定のユースケースに適しているかどうかに関係なく、ネイティブコードまたは Starlark の Bazel で定義されています。問題がある場合ルールの作成者に API を拡張して目的を達成できるかどうかをあります。

経験則では、ルールに近いマクロが多いほど、より良い結果が得られます。

マクロもご覧ください。

ルール

ルール、アスペクト、およびその属性は、小文字の名前（「snake」）を使用する必要があります。あります）。
ルール名は、ルールによって生成されるという観点から（リーフルールの場合は、できます。これは、必ずしもファイルの接尾辞ではありません。たとえば、 Python 拡張機能が呼び出される場合に使用するための C++ アーティファクトを生成する py_extension。ほとんどの言語の一般的なルールは次のとおりです。
- *_library - コンパイル単位または「モジュール」。
- *_binary - 実行可能ファイルまたはデプロイユニットを生成するターゲット。
- *_test - テストターゲット。これには複数のテストを含めることができます。すべてを表示 *_test ターゲット内のテストを、同じテーマのバリエーションとして使用することはできません。単一のライブラリをテストする場合です。
- *_import: .jar、またはコンパイル中に使用される .dll。
属性には一貫した名前と型を使用します。一般的に当てはまる属性には以下が含まれます。
- srcs: label_list、ファイルを許可: 通常はソースファイル記述します。
- deps: label_list（通常はファイルを許可しない）: コンパイル確認します。
- data: label_list。ファイル（テストデータなどのデータファイル）を許可します。
- runtime_deps: label_list: 不要なランタイム依存関係渡します。
動作が自明でない属性（文字列テンプレートなど）特殊な置換、または特定の API 呼び出しで呼び出されるツールを doc キーワード引数を使用してドキュメントを（attr.label_list() など）。
ルールの適用関数は、ほぼ常に非公開の関数にする（先頭にアンダースコアが付いた名前）。一般的なスタイルは、 myrule の実装関数（名前は _myrule_impl）
明確に定義されたルールを使用して、ルール間で情報の受け渡しを provider インターフェース。プロバイダを宣言してドキュメント化する表示されます。
拡張性を念頭に置いてルールを設計してください。他のルールによってプロバイダへのアクセス、ルールの再利用など、できます。
ルールのパフォーマンスガイドラインに従います。