このページは、Bazel に精通していることを前提としており、Bazel の機能を最大限に活用するためにプロジェクトを構成する際のガイドラインとアドバイスを提供します。
全体的な目標は次のとおりです。
- きめ細かい依存関係を使用して、並列処理と増分処理を可能にします。
- 依存関係を適切にカプセル化するため。
- コードを構造化してテスト可能にするため。
- 理解と保守が容易なビルド構成を作成する。
これらのガイドラインは要件ではありません。すべてのガイドラインに準拠できるプロジェクトはほとんどありません。lint の man ページには、「厳密なチェックでエラーが発生しない実際のプログラムを作成した最初のユーザーには、特別な報酬が贈られます」と記載されています。ただし、これらの原則をできるだけ多く取り入れることで、プロジェクトの可読性が向上し、エラーが発生しにくくなり、構築が高速化されます。
このページでは、この RFC で説明されている要件レベルを使用します。
ビルドとテストの実行
プロジェクトは、安定版ブランチで常に bazel build //... と bazel test //... を正常に実行できる必要があります。必要なターゲットが特定の状況下でビルドされない場合（特定のビルドフラグが必要、特定のプラットフォームでビルドされない、ライセンス契約が必要など）、できるだけ具体的にタグ付けする必要があります（例: 「requires-osx」）。このタグ付けにより、「manual」タグよりも細かいレベルでターゲットをフィルタリングできます。また、BUILD ファイルを検査するユーザーは、ターゲットの制限を把握できます。
サードパーティの依存関係
サードパーティの依存関係を宣言できます。
MODULE.bazelファイルでリモート リポジトリとして宣言します。- または、ワークスペース ディレクトリの下にある
third_party/というディレクトリに配置します。
バイナリに依存する
可能な限り、すべてをソースからビルドする必要があります。一般的に、これはライブラリ some-library.so に依存するのではなく、BUILD ファイルを作成してそのソースから some-library.so をビルドし、そのターゲットに依存することを意味します。
常にソースからビルドすることで、ビルドが互換性のないフラグや異なるアーキテクチャでビルドされたライブラリを使用しないようにします。カバレッジ、静的分析、動的分析など、ソースでのみ機能する機能もあります。
バージョニング
可能な限り、すべてのコードをヘッドからビルドすることを推奨します。バージョンを使用する必要がある場合は、ターゲット名にバージョンを含めないようにします（例: //guava-20.0 ではなく //guava）。この命名規則を使用すると、ライブラリの更新が容易になります（更新が必要なターゲットは 1 つだけになります）。また、ダイヤモンド依存関係の問題にも対応しやすくなります。1 つのライブラリが guava-19.0 に依存し、もう 1 つのライブラリが guava-20.0 に依存している場合、2 つの異なるバージョンに依存しようとするライブラリが生成される可能性があります。両方のターゲットを 1 つの guava ライブラリにポイントする誤解を招くエイリアスを作成した場合、BUILD ファイルは誤解を招くものになります。
.bazelrc ファイルを使用する
プロジェクト固有のオプションについては、workspace/.bazelrc の構成ファイル（bazelrc 形式を参照）を使用します。
プロジェクトのユーザーごとのオプションをサポートしたいが、ソース管理にチェックインしたくない場合は、次の行を追加します。
try-import %workspace%/user.bazelrc
（または任意のファイル名）を workspace/.bazelrc に追加し、user.bazelrc を .gitignore に追加します。
オープンソースの bazelrc-preset.bzl {: .external} は、Bazel のバージョンに一致するカスタム bazelrc ファイルを生成し、推奨フラグのプリセットを提供します。
パッケージ
ビルド可能なファイルを含むすべてのディレクトリはパッケージである必要があります。BUILD ファイルがサブディレクトリ（srcs = ["a/b/C.java"] など）内のファイルを参照している場合は、そのサブディレクトリに BUILD ファイルを追加する必要があります。この構造が存在する期間が長くなるほど、循環依存関係が誤って作成される可能性が高くなり、ターゲットのスコープが拡大し、更新する必要がある逆依存関係の数が増加します。