このページでは、Bazel の 2 つの可視性システム(ターゲット可視性と読み込み可視性)について説明します。
どちらの公開設定も、他のデベロッパーがライブラリのパブリック API とその実装の詳細を区別し、ワークスペースの増大に応じて構造を適用するのに役立ちます。また、公開 API の非推奨化時に公開設定を使用して、既存のユーザーを許可し、新しいユーザーを拒否することもできます。
ターゲットの公開設定
ターゲットの公開設定では、ターゲットに依存するユーザー(deps
などの属性内でターゲットのラベルを使用するユーザー)を制御します。
ターゲット A
がターゲット B
にある場合は、それらが同じパッケージ内にある場合、または A
が B
のパッケージに公開設定を付与します。したがって、パッケージはアクセスを許可するかどうかを決定するための粒度単位です。B
が A
に依存しているが、A
が B
に表示されない場合、B
のビルドの試行はすべて分析中に失敗します。
パッケージに公開設定を付与しても、サブパッケージに公開設定が付与されるわけではありません。パッケージとサブパッケージの詳細については、コンセプトと用語をご覧ください。
プロトタイピングでは、フラグ --check_visibility=false
を設定することで、ターゲットの公開設定の適用を無効にできます。送信されたコードで本番環境で使用する場合、これは行わないでください。
公開設定を制御する主な方法は、ルール ターゲットの visibility
属性を使用することです。このセクションでは、この属性の形式と、ターゲットの公開設定を決定する方法について説明します。
公開設定の仕様
すべてのルール ターゲットには、ラベルのリストを受け取る visibility
属性があります。各ラベルの形式は次のいずれかです。最後の形式を除き、これらは実際のターゲットに一致しない構文プレースホルダにすぎません。
"//visibility:public"
: すべてのパッケージへのアクセス権を付与します。(他の仕様と組み合わせることはできません)。"//visibility:private"
: 追加のアクセス権は付与されません。このパッケージ内のターゲットのみがこのタゲを使用できます。(他の仕様と組み合わせることはできません)。"//foo/bar:__pkg__"
://foo/bar
へのアクセス権を付与します(サブパッケージは除く)。"//foo/bar:__subpackages__"
://foo/bar
とその直接サブパッケージと間接サブパッケージへのアクセス権を付与します。"//some_pkg:my_package_group"
: 指定されたpackage_group
に含まれるすべてのパッケージへのアクセスを許可します。- パッケージ グループでは、パッケージの指定に異なる構文が使用されます。パッケージ グループ内では、フォーム
"//foo/bar:__pkg__"
と"//foo/bar:__subpackages__"
がそれぞれ"//foo/bar"
と"//foo/bar/..."
に置き換えられます。同様に、"//visibility:public"
と"//visibility:private"
は単なる"public"
と"private"
です。
- パッケージ グループでは、パッケージの指定に異なる構文が使用されます。パッケージ グループ内では、フォーム
たとえば、//some/package:mytarget
の visibility
が [":__subpackages__", "//tests:__pkg__"]
に設定されている場合、//some/package/...
ソースツリーの一部である任意のターゲットと、//tests/BUILD
で定義されたターゲットで使用できますが、//tests/integration/BUILD
で定義されたターゲットでは使用できません。
ベスト プラクティス: 複数のターゲットを同じパッケージセットに表示するには、各ターゲットの visibility
属性でリストを繰り返すのではなく、package_group
を使用します。これにより、可読性が向上し、リストの同期がずれるのを防ぐことができます。
ルールのターゲットの公開設定
ルール ターゲットの公開設定は次のとおりです。
visibility
属性の値(設定されている場合)。それ以外の場合は、ターゲットの
BUILD
ファイル内のpackage
ステートメントのdefault_visibility
引数の値(そのような宣言が存在する場合)。存在しない場合は、//visibility:private
。
ベスト プラクティス: default_visibility
を公開に設定しないでください。プロトタイピングや小規模なコードベースでは便利ですが、コードベースのサイズが大きくなるにつれて、誤って公開ターゲットを作成するリスクが高まります。パッケージの公開インターフェースの一部であるターゲットを明示的に指定することをおすすめします。
例
ファイル //frobber/bin/BUILD
:
# This target is visible to everyone
cc_binary(
name = "executable",
visibility = ["//visibility:public"],
deps = [":library"],
)
# This target is visible only to targets declared in the same package
cc_library(
name = "library",
# No visibility -- defaults to private since no
# package(default_visibility = ...) was used.
)
# This target is visible to targets in package //object and //noun
cc_library(
name = "subject",
visibility = [
"//noun:__pkg__",
"//object:__pkg__",
],
)
# See package group "//frobber:friends" (below) for who can
# access this target.
cc_library(
name = "thingy",
visibility = ["//frobber:friends"],
)
ファイル //frobber/BUILD
:
# This is the package group declaration to which target
# //frobber/bin:thingy refers.
#
# Our friends are packages //frobber, //fribber and any
# subpackage of //fribber.
package_group(
name = "friends",
packages = [
"//fribber/...",
"//frobber",
],
)
生成されたファイル ターゲットの公開設定
生成されたファイル ターゲットの可視性は、生成元のルール ターゲットと同じです。
ソースファイル ターゲットの公開設定
ソースファイル ターゲットの公開設定を明示的に設定するには、exports_files
を呼び出します。visibility
引数が exports_files
に渡されていない場合、公開設定が一般公開になります。exports_files
を使用して、生成されたファイルの公開設定をオーバーライドすることはできません。
exports_files
の呼び出しに表示されないソースファイル ターゲットの可視性は、フラグ --incompatible_no_implicit_file_export
の値によって異なります。
フラグが設定されている場合、公開設定は非公開になります。
それ以外の場合は、従来の動作が適用されます。公開設定は
BUILD
ファイルのdefault_visibility
と同じになります。デフォルトの公開設定が指定されていない場合は、非公開になります。
以前の動作に依存しないでください。ソースファイル ターゲットで非公開以外の公開設定が必要な場合は、必ず exports_files
宣言を記述します。
ベスト プラクティス: 可能であれば、ソースファイルではなくルール ターゲットを公開します。たとえば、.java
ファイルで exports_files
を呼び出すのではなく、非公開以外の java_library
ターゲットでファイルをラップします。通常、ルール ターゲットは、同じパッケージにあるソースファイルのみを直接参照する必要があります。
例
ファイル //frobber/data/BUILD
:
exports_files(["readme.txt"])
ファイル //frobber/bin/BUILD
:
cc_binary(
name = "my-program",
data = ["//frobber/data:readme.txt"],
)
構成設定の公開設定
これまで、Bazel は、select()
のキーで参照されている config_setting
ターゲットに対して可視性を適用していませんでした。この従来の動作を削除するためのフラグが 2 つあります。
--incompatible_enforce_config_setting_visibility
は、これらのターゲットの公開設定チェックを有効にします。また、移行を支援するために、visibility
を指定しなかったconfig_setting
は、(パッケージレベルのdefault_visibility
に関係なく)公開と見なされます。--incompatible_config_setting_private_default_visibility
を使用すると、visibility
を指定しなかったconfig_setting
は、他のルール ターゲットと同様に、パッケージのdefault_visibility
を尊重し、非公開の公開設定にフォールバックします。--incompatible_enforce_config_setting_visibility
が設定されていない場合、これは no-op です。
以前の動作に依存しないでください。現在のパッケージの外部で使用することを目的とした config_setting
には、パッケージで適切な default_visibility
がまだ指定されていない場合は、明示的な visibility
が必要です。
パッケージ グループ ターゲットの公開設定
package_group
ターゲットには visibility
属性がありません。常に一般公開されます。
暗黙的な依存関係の可視性
一部のルールには暗黙的な依存関係があります。これは、BUILD
ファイルに明記されていないものの、そのルールのすべてのインスタンスに固有の依存関係です。たとえば、cc_library
ルールでは、各ルール ターゲットから C++ コンパイラを表す実行可能ターゲットへの暗黙的な依存関係が作成される場合があります。
このような暗黙的な依存関係の公開設定は、ルール(またはアスペクト)が定義されている .bzl
ファイルを含むパッケージに対してチェックされます。この例では、C++ コンパイラは、cc_library
ルールの定義と同じパッケージ内にある限り、非公開にできます。代わりに、暗黙的な依存関係が定義から見えない場合、cc_library
ターゲットに関してチェックされます。
この動作を変更するには、--incompatible_visibility_private_attributes_at_definition
を無効にします。無効にすると、暗黙的な依存関係は他の依存関係と同様に扱われます。つまり、依存するターゲット(C++ コンパイラなど)は、ルールのすべてのインスタンスに可視である必要があります。通常、これはターゲットを一般公開する必要があることを意味します。
ルールの使用を特定のパッケージに制限する場合は、代わりに読み込みの可視性を使用します。
負荷の可視性
読み込みの公開設定は、.bzl
ファイルを現在のパッケージ外の他の BUILD
ファイルまたは .bzl
ファイルから読み込めるかどうかを制御します。
ターゲットの公開設定がターゲットによってカプセル化されたソースコードを保護するのと同様に、読み込みの可視性は、.bzl
ファイルによってカプセル化されたビルドロジックを保護します。たとえば、BUILD
ファイルの作成者は、繰り返し発生するターゲット定義を .bzl
ファイルのマクロに分割できます。読み込みの可視性を保護しないと、同じワークスペース内の他の共同編集者によってマクロが再利用され、マクロを変更すると他のチームのビルドが破損する可能性があります。
.bzl
ファイルには、対応するソースファイル ターゲットが存在する場合と存在しない場合もあります。同じ場合でも、読み込みの公開設定とターゲットの公開設定が一致するとは限りません。つまり、同じ BUILD
ファイルで .bzl
ファイルを読み込めるものの、filegroup
の srcs
にリストされない場合があります。その逆も同様です。これにより、ドキュメントの生成やテストなど、.bzl
ファイルをソースコードとして使用するルールで問題が発生することがあります。
プロトタイプ作成の場合は、--check_bzl_visibility=false
を設定することで、読み込みの可視性の適用を無効にできます。--check_visibility=false
と同様に、送信されたコードに対してはこの操作を行わないでください。
負荷の可視性は、Bazel 6.0 以降で利用できます。
読み込みの公開設定を宣言する
.bzl
ファイルの読み込みの公開設定を設定するには、ファイル内から visibility()
関数を呼び出します。visibility()
の引数は、package_group
の packages
属性と同様に、パッケージ仕様のリストです。ただし、visibility()
は負のパッケージ仕様を受け入れません。
visibility()
の呼び出しは、ファイルごとに 1 回だけ、最上位レベル(関数内ではない)で行う必要があります。理想的には、load()
ステートメントの直後に行います。
ターゲットの公開設定とは異なり、デフォルトの読み込みの公開設定は常に公開されます。visibility()
を呼び出さないファイルは、ワークスペースのどこからでも常に読み込むことができます。パッケージ外での使用を特に想定していない新しい .bzl
ファイルの先頭に、visibility("private")
を追加することをおすすめします。
例
# //mylib/internal_defs.bzl
# Available to subpackages and to mylib's tests.
visibility(["//mylib/...", "//tests/mylib/..."])
def helper(...):
...
# //mylib/rules.bzl
load(":internal_defs.bzl", "helper")
# Set visibility explicitly, even though public is the default.
# Note the [] can be omitted when there's only one entry.
visibility("public")
myrule = rule(
...
)
# //someclient/BUILD
load("//mylib:rules.bzl", "myrule") # ok
load("//mylib:internal_defs.bzl", "helper") # error
...
読み込みの可視化に関するおすすめの方法
このセクションでは、負荷可視性宣言を管理するためのヒントについて説明します。
因数分解の公開設定
複数の .bzl
ファイルに同じ公開設定を適用する場合は、パッケージ仕様を共通のリストにまとめると便利です。例:
# //mylib/internal_defs.bzl
visibility("private")
clients = [
"//foo",
"//bar/baz/...",
...
]
# //mylib/feature_A.bzl
load(":internal_defs.bzl", "clients")
visibility(clients)
...
# //mylib/feature_B.bzl
load(":internal_defs.bzl", "clients")
visibility(clients)
...
これにより、さまざまな .bzl
ファイルの可視性が誤ってずれるのを防ぐことができます。また、clients
リストが大きい場合にも読みやすくなります。
可視性の合成
場合によっては、複数の小さな許可リストで構成される許可リストに対して .bzl
ファイルを表示する必要があります。これは、package_group
が includes
属性を介して他の package_group
を組み込む方法に似ています。
広く使用されているマクロを非推奨にするとします。既存のユーザーと自分のチームが所有するパッケージにのみ公開する必要があります。次のように記述します。
# //mylib/macros.bzl
load(":internal_defs.bzl", "our_packages")
load("//some_big_client:defs.bzl", "their_remaining_uses")
# List concatenation. Duplicates are fine.
visibility(our_packages + their_remaining_uses)
パッケージ グループによる重複排除
ターゲットの公開設定とは異なり、package_group
で負荷の可視性を定義することはできません。ターゲットの公開設定と読み込みの公開設定の両方で同じ許可リストを再利用する場合は、パッケージ仕様のリストを .bzl ファイルに移動することをおすすめします。このファイルでは、両方の宣言でリストを参照できます。上記の公開設定の分類の例を基に、次のように記述できます。
# //mylib/BUILD
load(":internal_defs", "clients")
package_group(
name = "my_pkg_grp",
packages = clients,
)
これは、リストにネガティブ パッケージ仕様が含まれていない場合にのみ機能します。
個々の記号を保護する
名前がアンダースコアで始まる Starlark シンボルは、別のファイルから読み込むことはできません。これにより、非公開のシンボルを簡単に作成できますが、これらのシンボルを限定された信頼できるファイルセットと共有することはできません。一方、読み込みの公開設定では、他のパッケージが .bzl file
を参照できるかどうかを制御できますが、アンダースコアが付いていないシンボルが読み込まれないようにすることはできません。
幸い、この 2 つの機能を組み合わせてきめ細かい制御を行うことができます。
# //mylib/internal_defs.bzl
# Can't be public, because internal_helper shouldn't be exposed to the world.
visibility("private")
# Can't be underscore-prefixed, because this is
# needed by other .bzl files in mylib.
def internal_helper(...):
...
def public_util(...):
...
# //mylib/defs.bzl
load(":internal_defs", "internal_helper", _public_util="public_util")
visibility("public")
# internal_helper, as a loaded symbol, is available for use in this file but
# can't be imported by clients who load this file.
...
# Re-export public_util from this file by assigning it to a global variable.
# We needed to import it under a different name ("_public_util") in order for
# this assignment to be legal.
public_util = _public_util
bzl-visibility Buildifier lint
Buildifier lint があり、ユーザーが internal
または private
という名前のディレクトリからファイルを読み込む場合、そのユーザーのファイルがそのディレクトリの親の下にない場合に警告が表示されます。この lint は読み込みの可視性機能より前から存在しており、.bzl
ファイルで可視性を宣言するワークスペースでは不要です。