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