関数

7.3 · 7.2 · 7.1 · 7.0 · 6.5

目次

パッケージ

package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)

この関数は、パッケージ内のすべてのルールに適用されるメタデータを宣言します。パッケージ(BUILD ファイル)内で最大 1 回使用されます。

リポジトリ全体のすべてのルールに適用されるメタデータを宣言するカウンターパートの場合は、リポジトリのルートにある REPO.bazel ファイルrepo() 関数を使用します。repo() 関数は、package() とまったく同じ引数を取ります。

package() 関数は、ファイルの先頭にあるすべての load() ステートメントの直後、ルールの前に呼び出す必要があります。

引数

属性 説明
default_applicable_licenses

default_package_metadata のエイリアス。

default_visibility

ラベルのリスト。デフォルトは [] です。

このパッケージのルールのデフォルトの公開設定。

このパッケージ内のすべてのルールには、この属性で指定された公開設定が適用されます。ただし、ルールの visibility 属性で指定されている場合は除きます。この属性の構文の詳細については、visibility のドキュメントをご覧ください。 パッケージのデフォルトの公開設定は、デフォルトで公開されている exports_files には適用されません。

default_deprecation

文字列。デフォルトは ""

このパッケージ内のすべてのルールにデフォルトの deprecation メッセージを設定します。

default_package_metadata

ラベルのリスト。デフォルトは [] です。

パッケージ内の他のすべてのターゲットに適用されるメタデータ ターゲットのデフォルト リストを設定します。これらは通常、OSS パッケージとライセンスの申告に関連するターゲットです。 例については、rules_license をご覧ください。

default_testonly

ブール値。特に記載のない限り、デフォルトは False です。

このパッケージ内のすべてのルールのデフォルトの testonly プロパティを設定します。

javatests の下のパッケージでは、デフォルト値は True です。

features

リスト文字列。デフォルトは [] です。

この BUILD ファイルのセマンティクスに影響するさまざまなフラグを設定します。

この機能は主に、ビルドシステムの担当者が、なんらかの特別な処理が必要なパッケージにタグを付けるために使用します。ビルドシステムを担当するユーザーから明示的にリクエストされない限り、この方法は使用しないでください。

以下の宣言では、このパッケージ内のルールがパッケージ グループ //foo:target のメンバーにのみ公開されることを宣言しています。ルールに個々の公開設定を宣言した場合は、この指定よりも優先されます。
package(default_visibility = ["//foo:target"])

package_group

package_group(name, packages, includes)

この関数は、パッケージのセットを定義し、そのセットにラベルを関連付けます。ラベルは visibility 属性で参照できます。

パッケージ グループは主に公開設定の制御に使用されます。一般公開されているターゲットは、ソースツリー内のすべてのパッケージから参照できます。非公開で公開されるターゲットは、独自のパッケージ(サブパッケージではない)内でのみ参照できます。これらの極端な例の間には、ターゲットが独自のパッケージと、1 つ以上のパッケージ グループで記述されたパッケージへのアクセスを許可する場合があります。可視性システムの詳細については、可視性属性をご覧ください。

特定のパッケージがグループに属すると見なされるのは、そのパッケージが packages 属性と一致する場合、または includes 属性で指定されている他のパッケージ グループのいずれかにすでに含まれている場合です。

パッケージ グループは技術的にはターゲットですが、ルールによって作成されず、それ自体に可視性保護はありません。

引数

属性 説明
name

名前(必須)

このターゲットの一意の名前。

packages

文字列のリスト。デフォルトは [] です。

0 個以上のパッケージ仕様のリスト。

各パッケージ仕様の文字列は、次のいずれかの形式になります。

  1. リポジトリのないパッケージのフルネーム(先頭にダブルスラッシュ)。たとえば、//foo/bar は、その名前のパッケージを指定し、パッケージ グループと同じリポジトリに存在します。
  2. 上記と同じですが、末尾に /... が付きます。たとえば、 //foo/...//foo とそのすべてのサブパッケージのセットを指定します。//... には、現在のリポジトリ内のすべてのパッケージを指定します。
  3. 文字列 public または private。それぞれすべてのパッケージまたはパッケージなしを指定します。(このフォームでは、フラグ --incompatible_package_group_has_public_syntax を設定する必要があります)。

さらに、最初の 2 種類のパッケージ仕様には、否定がされることを示すために、先頭に - を付けることもできます。

パッケージ グループには、正の指定の少なくとも 1 つに一致し、負の指定のいずれにも一致しないパッケージが含まれます。たとえば、値 [//foo/..., -//foo/tests/...] には、//foo/tests のサブパッケージではない //foo のサブパッケージがすべて含まれます。(//foo 自体は含まれますが、//foo/tests 自体は含まれません)。

一般公開される以外に、現在のリポジトリの外部にあるパッケージを直接指定する方法はありません。

この属性が指定されていない場合は、空のリストを設定した場合と同じになります。これは、private のみを含むリストを設定した場合と同じです。

注: Bazel 6.0 より前では、仕様 //...public と同じ従来の動作でした。この動作は、--incompatible_fix_package_group_reporoot_syntax が有効になっている場合に修正されます。これは Bazel 6.0 以降のデフォルトです。

注: Bazel 6.0 より前では、この属性が bazel query --output=proto(または --output=xml)の一部としてシリアル化される場合、先頭のスラッシュは省略されます。たとえば、//pkg/foo/...\"pkg/foo/...\" として出力されます。この動作は、--incompatible_package_group_includes_double_slash が有効になっていると修正されます(Bazel 6.0 より後のデフォルト)。

includes

ラベルのリスト。デフォルトは [] です。

このパッケージ グループに含まれる他のパッケージ グループ。

この属性のラベルは、他のパッケージ グループを参照する必要があります。参照先のパッケージ グループ内のパッケージは、このパッケージ グループの一部になります。これは推移的です。パッケージ グループ a にパッケージ グループ b が含まれ、b にパッケージ グループ c が含まれている場合、c 内のすべてのパッケージも a のメンバーになります。

否定されたパッケージ仕様とともに使用する場合、各グループのパッケージセットが最初に個別に計算され、結果が結合されます。つまり、あるグループの仕様を否定しても、別のグループの仕様には影響しません。

次の package_group 宣言では、熱帯フルーツを含む「tropical」というパッケージ グループを指定しています。

package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)

次の宣言では、架空のアプリケーションのパッケージ グループを指定します。

package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

package_group(
    name = "model",
    packages = ["//fooapp/database"],
)

package_group(
    name = "view",
    packages = [
        "//fooapp/swingui",
        "//fooapp/webui",
    ],
)

package_group(
    name = "controller",
    packages = ["//fooapp/algorithm"],
)

exports_files

exports_files([label, ...], visibility, licenses)

exports_files() には、このパッケージに属し、他のパッケージにエクスポートされるファイルのリストを指定します。

パッケージの BUILD ファイルは、exports_files() ステートメントで明示的にエクスポートされた場合にのみ、別のパッケージに属するソースファイルを直接参照できます。詳しくは、ファイルの公開設定をご覧ください。

従来の動作として、ルールの入力として言及されているファイルも、フラグ --incompatible_no_implicit_file_export が反転するまでデフォルトの公開設定のままエクスポートされます。ただし、この動作は信頼せず、積極的に移行する必要があります。

引数

この引数は、現在のパッケージ内のファイルの名前のリストです。可視性の宣言を指定することもできます。この場合、指定したターゲットにファイルが表示されます。可視性を指定しない場合、package 関数でパッケージのデフォルトの可視性が指定されている場合でも、ファイルはすべてのパッケージに公開されます。ライセンスを指定することもできます。

次の例では、test_data パッケージからテキスト ファイルである golden.txt をエクスポートします。これにより、他のパッケージがテストの data 属性などで使用できるようになります。

# from //test_data/BUILD

exports_files(["golden.txt"])

glob

glob(include, exclude=[], exclude_directories=1, allow_empty=True)

glob は、特定のパスパターンに一致するすべてのファイルを検索し、パスの新しい変更可能な並べ替え済みリストを返すヘルパー関数です。Glob は、独自のパッケージ内のファイルのみを検索し、ソースファイルのみを検索します(生成されたファイルや他のターゲットは検索しません)。

ファイルのパッケージ相対パスが include パターンのいずれかに一致し、exclude パターンのいずれにも一致しない場合、ソースファイルのラベルが結果に含まれます。

include リストと exclude リストには、現在のパッケージを基準とするパスパターンが含まれています。すべてのパターンは、1 つ以上のパスセグメントで構成できます。Unix パスと同様に、これらのセグメントは / で区切られます。セグメントには * ワイルドカードを含めることができます。これは、ディレクトリ区切り文字 / を除く、パスセグメント内の任意の部分文字列(空の部分文字列も含む)に一致します。このワイルドカードは、1 つのパスセグメント内で複数回使用できます。また、** ワイルドカードは 0 個以上の完全なパスセグメントに一致しますが、スタンドアロンのパスセグメントとして宣言する必要があります。

例:
  • foo/bar.txt は、このパッケージの foo/bar.txt ファイルと完全に一致します。
  • foo/*.txt は、ファイルが .txt で終わっている場合、foo/ ディレクトリ内のすべてのファイルに一致します(foo/ がサブパッケージでない限り)。
  • foo/a*.htm* は、foo/ ディレクトリ内の、a で始まり、任意の文字列(空)、.htm、別の任意の文字列(foo/axx.htmfoo/a.htmlfoo/axxx.html など)で終わるすべてのファイルを照合します。
  • **/a.txt は、このパッケージのすべてのサブディレクトリ内のすべての a.txt ファイルに一致します。
  • **/bar/**/*.txt は、結果パスのディレクトリの少なくとも 1 つが bar と呼ばれている場合(xxx/bar/yyy/zzz/a.txtbar/a.txt**** はゼロ セグメントにも一致します)など)、このパッケージのすべてのサブディレクトリ内のすべての .txt ファイルに一致します。bar/zzz/a.txt
  • ** は、このパッケージのすべてのサブディレクトリ内のすべてのファイルに一致します。
  • ** がセグメントとして単独で存在する必要があるため、foo**/a.txt は無効なパターンです。

exclude_directories 引数が有効(1 に設定)の場合、ディレクトリ型のファイルは結果から除外されます(デフォルトは 1)。

allow_empty 引数が False に設定されている場合、結果が空のリストになる場合は、glob 関数はエラーになります。

重要な制限と注意事項がいくつかあります。

  1. glob() は BUILD ファイルの評価中に実行されるため、glob() はソースツリー内のファイルのみを照合し、ファイルが生成されることはありません。ソースファイルと生成されたファイルの両方を必要とするターゲットをビルドする場合は、生成されたファイルの明示的なリストを glob に追加する必要があります。:mylib:gen_java_srcs を使用したをご覧ください。

  2. ルールの名前が一致するソースファイルと同じ名前の場合、ルールはファイルを「シャドー」します。

    glob() はパスのリストを返すことを覚えておいてください。他のルールの属性(srcs = glob(["*.cc"]) など)で glob() を使用すると、一致したパスを明示的に一覧表示する場合と同じ効果が得られます。たとえば、glob()["Foo.java", "bar/Baz.java"] を生成していて、パッケージに「Foo.java」というルールがある場合(Bazel では警告されますが、許可されます)、glob() のコンシューマは、「Foo.java」ファイルではなく「Foo.java」ルール(その出力)を使用します。詳しくは、GitHub の問題 #10395 をご覧ください。

  3. Glob はサブディレクトリ内のファイルと一致する場合があります。サブディレクトリ名には ワイルドカードを使用できますただし...
  4. ラベルはパッケージ境界を越えることはできません。また、glob はサブパッケージ内のファイルと一致しません。

    たとえば、パッケージ x の glob 式 **/*.cc には、x/y がパッケージ(x/y/BUILD または package-path の他の場所)として存在する場合、x/y/z.cc は含まれません。つまり、glob 式の結果は、実際には BUILD ファイルの有無に依存します。つまり、x/y というパッケージが存在しない場合、または --deleted_packages フラグを使用して削除済みとしてマークされている場合、同じ glob 式に x/y/z.cc が含まれます。

  5. 上記の制限は、使用するワイルドカードに関係なく、すべての glob 式に適用されます。
  6. ファイル名が . で始まる非表示ファイルは、** ワイルドカードと * ワイルドカードの両方で完全に一致します。非表示のファイルを複合パターンと照合するには、パターンを . で始める必要があります。たとえば、*.*.txt.foo.txt と一致しますが、*.txt は一致しません。隠しディレクトリも同様に照合されます。隠しディレクトリには、入力として不要なファイルが含まれていることがあり、不必要にグロブされるファイルの数やメモリ消費量が増加する可能性があります。非表示のディレクトリを除外するには、それらを「除外」リスト引数に追加します。
  7. ワイルドカード「**」には特殊なケースが 1 つあります。パターン "**" は、パッケージのディレクトリ パスと一致しません。つまり、glob(["**"], exclude_directories = 0) は、現在のパッケージのディレクトリの下にあるすべてのファイルとディレクトリを推移的に照合します(ただし、サブパッケージのディレクトリに移動するわけではありません。これについては前述の注をご覧ください)。

glob パターンでは、基本的な「*」を使用するのではなく、適切な拡張子(*.html など)を指定する必要があります。より明示的な名前は、自己ドキュメント化と、バックアップ ファイルや emacs/vi/... の自動保存ファイルと誤って一致しないようにする両方の目的を果たします。

ビルドルールを記述するときに、glob の要素を列挙できます。これにより、たとえば入力ごとに個別のルールを生成できます。以下の拡張 glob の例のセクションをご覧ください。

glob の例

このディレクトリ内のすべての Java ファイルと、:gen_java_srcs ルールによって生成されたすべてのファイルからビルドされた Java ライブラリを作成します。

java_library(
    name = "mylib",
    srcs = glob(["*.java"]) + [":gen_java_srcs"],
    deps = "...",
)

genrule(
    name = "gen_java_srcs",
    outs = [
        "Foo.java",
        "Bar.java",
    ],
    ...
)

すべての txt ファイルを testdata ディレクトリ(experiment.txt を除く)に含めます。 testdata のサブディレクトリ内のファイルは含まれません。これらのファイルを含める場合は、再帰的な glob(**)を使用します。

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

再帰 glob の例

テストを、testdata ディレクトリ内のすべての TXT ファイルとそのサブディレクトリ(およびそのサブディレクトリなど)に依存させます。BUILD ファイルを含むサブディレクトリは無視されます。(上記の制限事項と注意事項を参照)。

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)

このディレクトリと、パスに test という名前のディレクトリが含まれるものを除くすべてのサブディレクトリからビルドされるライブラリを作成します。このパターンは、ビルドの増分性を低下させ、ビルド時間を長くする可能性があるため、可能な限り回避する必要があります。

java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)

拡張された Glob の例

ファイル内の行数をカウントする *_test.cc 用の個別の genrule を現在のディレクトリに作成します。

# Conveniently, the build language supports list comprehensions.
[genrule(
    name = "count_lines_" + f[:-3],  # strip ".cc"
    srcs = [f],
    outs = ["%s-linecount.txt" % f[:-3]],
    cmd = "wc -l $< >$@",
 ) for f in glob(["*_test.cc"])]

上記のビルド ファイルがパッケージ //foo にあり、そのパッケージに 3 つの一致するファイル(a_test.cc、b_test.cc、c_test.cc)が含まれている場合、bazel query '//foo:all' を実行すると、生成されたすべてのルールが一覧表示されます。

$ bazel query '//foo:all' | sort
//foo:count_lines_a_test
//foo:count_lines_b_test
//foo:count_lines_c_test

選択

select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)

select() は、ルール属性を構成可能にするヘルパー関数です。これは、ほぼすべての属性割り当ての右側を置き換えることができるため、その値はコマンドラインの Bazel フラグに依存します。 これを使用すると、たとえば、プラットフォーム固有の依存関係を定義したり、ルールが「デベロッパー」モードと「リリース」モードのどちらでビルドされているかによって異なるリソースを埋め込んだりできます。

基本的な使用方法は次のとおりです。

sh_binary(
    name = "mytarget",
    srcs = select({
        ":conditionA": ["mytarget_a.sh"],
        ":conditionB": ["mytarget_b.sh"],
        "//conditions:default": ["mytarget_default.sh"]
    })
)

これにより、通常のラベルリストの割り当てを、構成条件を一致する値にマッピングする select 呼び出しに置き換えることで、sh_binarysrcs 属性を構成可能にします。各条件は、config_setting または constraint_value を参照するラベルです。ターゲットの構成が期待される値のセットに一致する場合は「一致」します。mytarget#srcs の値は、現在の呼び出しに一致するラベルリストになります。

注:

  • どの呼び出しでも、1 つの条件のみが選択されます。
  • 複数の条件が一致し、一方が他の条件を特殊化したものである場合は、特殊化が優先されます。条件 B が条件 A と同じフラグと制約値をすべて持ち、さらにフラグまたは制約値が追加されている場合、条件 B は条件 A の特殊化と見なされます。また、以下の例 2 に示すような順序付けはスペシャライゼーション解決では設計されていません。
  • 複数の条件が一致し、そのうちの 1 つが他のすべての条件を特殊化していない場合、すべての条件が同じ値に解決されない限り、Bazel はエラーで失敗します。
  • 特別な疑似ラベル //conditions:default は、他の条件に一致しない場合、一致すると見なされます。この条件を省略した場合、エラーを回避するため、他のルールに一致する必要があります。
  • select は、より大きな属性割り当ての内部に埋め込むことができます。したがって、srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...}) srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]}) は有効な式です。
  • select はほとんどの属性で動作しますが、すべてではありません。互換性のない属性は、ドキュメントで nonconfigurable とマークされています。

    サブパッケージ

    subpackages(include, exclude=[], allow_empty=True)

    subpackages() は、ファイルとディレクトリではなくサブパッケージを一覧表示する glob() に似たヘルパー関数です。glob() と同じパスパターンを使用し、現在読み込み中の BUILD ファイルの直接の子孫であるサブパッケージに一致します。包含パターンと除外パターンの詳細な説明と例については、glob をご覧ください。

    返されるサブパッケージのリストは昇順で並べられ、exclude ではなく include の指定されたパターンに一致する、現在の読み込みパッケージを基準としたパスが含まれます。

    次の例では、パッケージ foo/BUILD の直接サブパッケージをすべて一覧表示します。

    # The following BUILD files exist:
    # foo/BUILD
    # foo/bar/baz/BUILD
    # foo/sub/BUILD
    # foo/sub/deeper/BUILD
    #
    # In foo/BUILD a call to
    subs = subpackages(include = ["**"])
    
    # results in subs == ["sub", "bar/baz"]
    #
    # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
    # 'foo'
    

    一般に、この関数を直接呼び出すのではなく、skylib の「subpackages」モジュールを使用することをおすすめします。