このページでは、Bazel に精通していることを前提としています。また、Bazel の機能を最大限に活用できるように、プロジェクトを構成する際のガイドラインとアドバイスも提供します。
全体的な目標は次のとおりです。
- きめ細かな依存関係を使用して並列処理とインクリメンタリティを実現する
- 依存関係をうまくカプセル化するため。
- コードを適切に構造化し、テストできるようにする。
- 理解しやすく維持しやすいビルド構成を作成するため。
このガイドラインは必須ではなく、すべてのプロジェクトが遵守できるプロジェクトはほとんどありません。lint のマニュアル ページでは、「厳格なチェックでエラーを発生させない実際のプログラムを作成したときに、最初に特別な報酬が提示されます」と記載されています。しかし、これらの原則をできるだけ多く取り入れることで、プロジェクトが読みやすくなり、エラーが発生しやすくなり、ビルドも迅速になります。
このページでは、この RFC に記載されている要件レベルを使用します。
ビルドとテストの実行
プロジェクトは、安定版ブランチで常に bazel build //... と bazel test //... を正常に実行できる必要があります。必要であるが特定の状況ではビルドされないターゲット（特定のビルドフラグを要求する、特定のプラットフォーム上にビルドしない、ライセンス契約が必要であるなど）には、できるだけ具体的にタグ（「requires-osx」など）を付ける必要があります。このタグ付けにより、ターゲットを「手動」タグよりも細かいレベルでフィルタでき、BUILD ファイルを調べることでターゲットの制限を把握できます。
サードパーティの依存関係
サードパーティの依存関係を宣言できます。
WORKSPACEファイルで、それらをリモート リポジトリとして宣言します。- または、ワークスペース ディレクトリの下にある
third_party/というディレクトリに配置します。
バイナリによって異なる
可能な限りすべてをソースからビルドする必要があります。つまり、一般的には、ライブラリ some-library.so に依存せずに、BUILD ファイルを作成し、そのソースから some-library.so をビルドし、そのターゲットに依存します。
常にソースからビルドすると、互換性のないフラグや別のアーキテクチャでビルドされたライブラリがビルドで使用されなくなります。また、ソースでのみ機能するカバレッジ、静的分析、動的分析などの機能もあります。
バージョニング
可能な限り、すべてのコードをヘッドで構築することをおすすめします。バージョンを使用する必要がある場合は、ターゲット名にバージョンを含めないでください（例: //guava-20.0 ではありません）。この名前にライブラリの更新が容易になります。ただし、更新する必要があるターゲットは 1 つのみです。//guavaまた、ダイヤモンド依存関係の問題に対する復元性も向上します。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 ファイルをそのサブディレクトリに追加する必要があることを示します。この構造が長いほど、円形の依存関係が誤って作成され、ターゲットのスコープがクリープし、リバース依存関係の数が増える必要があります。