Build スタイルガイド

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

BUILD のファイル形式は、Go と同じ方法で、標準化された ツールがフォーマットのほとんどの問題に対応します。 Buildifier は、アプリケーションの 標準的なスタイルでソースコードを出力します。したがって、すべての BUILD ファイルは、 自動的にフォーマットされるため、 支援します。また、ツールが容易に理解、編集、分析し、 BUILD ファイルを生成します。

BUILD のファイル形式は buildifier の出力と一致する必要があります。

書式設定の例

# Test code implementing the Foo controller.
package(default_testonly = True)

py_test(
    name = "foo_test",
    srcs = glob(["*.py"]),
    data = [
        "//data/production/foo:startfoo",
        "//foo",
        "//third_party/java/jdk:jdk-k8",
    ],
    flaky = True,
    deps = [
        ":check_bar_lib",
        ":foo_data_check",
        ":pick_foo_port",
        "//pyglib",
        "//testing/pybase",
    ],
)

ファイル構造

おすすめの方法: 次の順序を使用します（どの要素も省略可能です）。

  • パッケージの説明（コメント）

  • すべての load() ステートメント

  • package() 関数。

  • ルールとマクロの呼び出し

Buildifier は独立したコメントとコメントを区別する 指定することもできます。特定の要素にコメントが添付されていない場合は、次のコマンドを使用します。 空の行が挿入されます。自動化する場合にはこの区別が重要 （たとえば、ルールの削除時にコメントを残す、削除する）

# Standalone comment (such as to make a section in a file)

# Comment for the cc_library below
cc_library(name = "cc")

現在のパッケージ内のターゲットへの参照

ファイルは、パッケージ ディレクトリを基準とする相対パスで参照する必要があります （.. などのアップ参照は使用しません）。生成されたファイルは 先頭に「:」が付きますソースではないことを示しますソースファイル 先頭に : を付けないでください。ルールの先頭には : を付ける必要があります。対象 x.cc がソースファイルであると仮定した場合:

cc_library(
    name = "lib",
    srcs = ["x.cc"],
    hdrs = [":gen_header"],
)

genrule(
    name = "gen_header",
    srcs = [],
    outs = ["x.h"],
    cmd = "echo 'int x();' > $@",
)

ターゲットの命名

ターゲット名はわかりやすいものにする必要があります。ターゲットに 1 つのソースファイルが含まれる場合、 ターゲットには通常、そのソースから派生した名前（例: cc_library（chat.cc）には chat、java_library （ DirectMessage.java は direct_message という名前を付けることができます）。

パッケージの同じ名前のターゲット（ で記述された機能を提供する必要があります。 ディレクトリ名を指定します。そのようなターゲットが存在しない場合は、同じ名前の あります。

同名のターゲットを参照する場合は、略称を使用する（//x） （//x:x は使用しません）。同じパッケージにいる場合は、ローカル 参照（//x ではなく :x）。

「予約済み」の使用を避ける特別な意味を持つターゲット名が含まれます。例 all、__pkg__、__subpackages__。これらの名前は特殊な名前です。 使用時に混乱や予期しない動作が発生する可能性があります。

普及しているチーム規約がない場合、これらの規約には拘束力がありません。 Google で広く使われている最適化案:

  • 通常は &quot;snake_case&quot; を使用します。 <ph type="x-smartling-placeholder">
      </ph>
    • src が 1 つの java_library の場合、これは次ではない名前を使用することを意味します。 拡張子を除いたファイル名と同じになります。
    • Java の *_binary ルールと *_test ルールの場合は、次のコマンドを使用します。 「アッパー キャメルケース」。 これにより、ターゲット名を src の 1 つに一致させることができます。対象 java_test。これにより、test_class 属性を 名前から推測されます。
  • 特定のターゲットに複数のバリアントがある場合は、 （例::foo_dev、:foo_prod、または :bar_x86、:bar_x64）
  • _test ターゲットの末尾に _test、_unittest、Test、または Tests を追加する
  • _lib や _library など、意味のない接尾辞を付けない（ _library ターゲットとそれに対応する _binary の間の競合を回避する）
  • proto 関連のターゲットの場合:
    • proto_library 個のターゲットには、_proto で終わる名前を指定してください
    • 言語固有の *_proto_library ルールは、基になるものと一致する必要があります 次のように、_proto を言語固有の接尾辞に置き換えます。 <ph type="x-smartling-placeholder">
        </ph>
      • cc_proto_library: _cc_proto
      • java_proto_library: _java_proto
      • java_lite_proto_library: _java_proto_lite

公開設定

公開設定では、アクセスを許可しつつ、できる限り範囲を限定する必要があります。 依存関係の逆引きを行います。__pkg__ と __subpackages__ を次の用途で使用 あります。

パッケージ default_visibility を //visibility:public に設定しないでください。 //visibility:public は、 公開 API です。依存するように設計されたライブラリがこれに該当します。 外部プロジェクトまたはバイナリで使用でき、外部プロジェクトの ビルドプロセスです。

依存関係

依存関係は、直接的な依存関係（ （ルールにリストされているソースで必要な場合）。一時的な依存関係はリストしないでください。

パッケージ ローカルの依存関係を最初にリストし、適切な方法で参照する必要があります。 対応するデバイス 現在のパッケージ内のターゲットの参照 セクション（絶対パッケージ名ではなく）に記載する必要があります。

依存関係を単一のリストとして直接リストするのが望ましい。「共通する」ことを 変数に代入すると保守性が低下するため、 ツールがターゲットの依存関係を変更することは不可能であり、その結果、 除外します。

glob

「ターゲットなし」と表示する[] で。何も一致しない glob は使用しないでください。 空のリストよりもエラーが発生しやすく、明確ではありません。

Recursive

ソースファイルの照合に再帰 glob を使用しないでください（例: glob(["**/*.java"])）。

再帰 glob により、BUILD ファイルがスキップされるため、推論が困難になります。 BUILD ファイルを含むサブディレクトリ。

通常、再帰 glob は、ファイルごとに BUILD ファイルを使用するよりも効率が低くなります。 それらの間に依存関係グラフが定義されたディレクトリを リモートキャッシュと並列処理です

各ディレクトリで BUILD ファイルを作成し、 依存関係グラフを使用します。

非再帰

非再帰 glob は一般的に許容されます。

その他の規則

  • 定数の宣言には大文字とアンダースコアを使用します（GLOBAL_CONSTANT など）。 変数の宣言には小文字とアンダースコアを使用します（my_variable など）。

  • ラベルは 79 文字を超えても分割しないでください。 ラベルは可能な限り文字列リテラルにする必要があります。理論的根拠: 簡単に見つけて交換できますまた、読みやすさも向上します。

  • name 属性の値は、リテラルの定数文字列にする必要があります（ あります）。理由: 外部ツールは、名前属性を使用して属性を参照する 適用できます。コードを解釈することなくルールを見つける必要があります。

  • ブール値型の属性を設定する場合は、整数値ではなくブール値を使用します。 従来の理由により、ルールは引き続き必要に応じて整数をブール値に変換します。 これは推奨されません。根拠: flaky = 1 は、次のように誤って解釈される可能性があります。 「1 回再実行してこのターゲットをデフレーク」します。flaky = True さんははっきりと話しています 「このテストは不安定です」。

Python スタイルガイドとの違い

Google Kubernetes Engine や Python スタイルガイド いくつか違いがあります

  • 行の長さに厳密な制限はありません。長いコメントと長い文字列は多くの場合、 最大 79 列ですが、必須ではありません。コード内で強制適用すべきではない 事前送信スクリプトを使用できます説明: ラベルは長くして、この上限を超えることがあります。 できます。BUILD ファイルはツールで生成または編集するのが一般的ですが、 行の長さ制限には適していません

  • 暗黙的な文字列の連結はサポートされていません。+ 演算子を使用する。 理由: BUILD ファイルには、文字列リストが多数含まれています。忘れてしまいがちです まったく異なる結果になります。これが原因で多くのバグが 使用できます。こちらのディスカッションもご覧ください。

  • ルール内のキーワード引数では、= 記号の前後にスペースを使用します。説明: 名前付き引数は Python よりも使用頻度が高く、常に 使用します。スペースを使用すると読みやすくなります。この規則は以前から 既存の BUILD ファイルをすべて変更する必要はありません。

  • デフォルトでは、文字列には二重引用符を使用します。理論的根拠: これは これは Python スタイルガイドに規定されていますが、一貫性を推奨しています。そのため、 二重引用符で囲まれた文字列のみを使用することにしました。多くの言語では二重引用符を使用する 使用します。

  • 2 つのトップレベルの定義の間には 1 行の空白行を使用します。理論的根拠: BUILD ファイルの構造は、一般的な Python ファイルとは異なります。含まれているのは、 記述できます。1 行を空白にすると、BUILD ファイルが短くなります。