このページでは、Bazel に精通していることを前提としています。また、Bazel の機能を最大限に活用するためのプロジェクトの構築に関するガイドラインとアドバイスを提供します。
全体的な目標は次のとおりです。
- きめ細かい依存関係を使用して、並列処理とインクリメンタリティを実現する。
- 依存関係を適切にカプセル化しておく。
- コードを適切に構造化し、テストしやすくするため。
- 理解しやすく維持しやすいビルド構成を作成すること。
このガイドラインは要件ではありません。すべてのガイドラインを遵守できるプロジェクトもあります。lint のマニュアル ページに記載されているように、「厳密なチェックを行ってエラーを発生させない実際のプログラムを最初に作成した人に、特別な報酬が与えられます」とあります。ただし、これらの原則をできるだけ多く取り入れることで、プロジェクトが読みやすくなり、エラーが発生しにくくなり、ビルド時間を短縮できます。
このページでは、こちらの RFC で説明されている要件レベルを使用します。
ビルドとテストの実行
プロジェクトは、Stable ブランチで bazel build //... と bazel test //... を常に正常に実行できる必要があります。必要だが特定の状況でビルドしないターゲット（特定のビルドフラグが必要、特定のプラットフォームでビルドしない、使用許諾契約が必要など）には、できるだけ具体的にタグを付ける必要があります（例: 「requires-osx」）。このタグ付けを使用すると、「手動」タグよりも細かいレベルでターゲットをフィルタリングでき、BUILD ファイルを調べてターゲットの制限を把握できます。
サードパーティの依存関係
サードパーティの依存関係は宣言できます。
WORKSPACEファイルでリモート リポジトリとして宣言します。- または、ワークスペース ディレクトリの下の
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 に追加します。
パッケージ
ビルド可能なファイルを含むすべてのディレクトリがパッケージである必要があります。BUILD ファイルがサブディレクトリ（srcs = ["a/b/C.java"] など）内のファイルを参照する場合は、そのサブディレクトリに BUILD ファイルを追加する必要があるということです。この構造が長くなるほど、循環する依存関係が誤って作成される可能性が高くなり、ターゲットのスコープがクリープし、更新が必要な逆依存関係の数が増えます。