BazelCon 2024 登録の受け付けを開始しました。

このページは Cloud Translation API によって翻訳されました。

ルールのデプロイ

問題を報告するソースを表示 Nightly · 8.0 . 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

このページは、ルールを他のユーザーに公開する予定のルール作成者を対象としています。

ホスティングと命名のルール

新しいルールは、組織の独自の GitHub リポジトリに配置する必要があります。ルールが bazelbuild 組織に属していると思われる場合は、bazel-dev メーリングリストにお問い合わせください。

Bazel ルールのリポジトリ名は、$ORGANIZATION/rules_$NAME の形式で標準化されています。GitHub の例をご覧ください。一貫性を保つため、Bazel ルールを公開する際も同じ形式にする必要があります。

説明的な GitHub リポジトリの説明と README.md タイトルを使用してください。例:

リポジトリ名: bazelbuild/rules_go
リポジトリの説明: Bazel の Go ルール
リポジトリタグ: golang、bazel
README.md ヘッダー: Bazel の Go ルール（Bazel に慣れていないユーザーを適切な場所に誘導する https://bazel.build へのリンクに注意してください）

ルールは、言語（Scala など）またはプラットフォーム（Android など）でグループ化できます。

リポジトリのコンテンツ

すべてのルールリポジトリには、ユーザーが新しいルールをすばやく理解できるように、特定のレイアウトが必要です。

たとえば、（架空の）mockascript 言語の新しいルールを記述する場合、ルールリポジトリの構造は次のようになります。

/
  LICENSE
  README
  WORKSPACE
  mockascript/
    constraints/
      BUILD
    runfiles/
      BUILD
      runfiles.mocs
    BUILD
    defs.bzl
  tests/
    BUILD
    some_test.sh
    another_test.py
  examples/
    BUILD
    bin.mocs
    lib.mocs
    test.mocs

Workspace

プロジェクトの WORKSPACE で、ユーザーがルールの参照に使用する名前を定義する必要があります。ルールが bazelbuild 組織に属している場合は、rules_<lang>（rules_mockascript など）を使用する必要があります。それ以外の場合は、リポジトリに <org>_rules_<lang>（build_stack_rules_proto など）という名前を付ける必要があります。ルールが bazelbuild 組織のルールの規則に従う必要があると思われる場合は、bazel-dev メーリングリストにお問い合わせください。

以降のセクションでは、リポジトリが bazelbuild 組織に属しているとします。

workspace(name = "rules_mockascript")

README

最上位には、ユーザーがルールを使用する際に WORKSPACE ファイルにコピーして貼り付ける必要があるものが（少なくとも）含まれている README が必要です。通常、これは GitHub リリースを指す http_archive と、ルールに必要なツールをダウンロードして構成するマクロ呼び出しになります。たとえば、Go ルールの場合、次のように表示されます。

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_go",
    urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
    sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()

ルールが別のリポジトリのルールに依存している場合は、ルールのドキュメントでそのことを指定します（たとえば、Sass ルールに依存する Skydoc ルールをご覧ください）。また、すべての依存関係をダウンロードする WORKSPACE マクロを指定します（上記の rules_go をご覧ください）。

ルール

多くの場合、リポジトリから複数のルールが提供されます。言語で名前を付けたディレクトリを作成し、エントリポイント（すべてのルールをエクスポートする defs.bzl ファイル）を指定します（ディレクトリがパッケージになるように BUILD ファイルも含めます）。rules_mockascript の場合、mockascript という名前のディレクトリと、その中に BUILD ファイルと defs.bzl ファイルが存在します。

/
  mockascript/
    BUILD
    defs.bzl

制約

ルールでツールチェーンルールを定義する場合は、カスタムの constraint_setting や constraint_value を定義する必要があります。これらを //<LANG>/constraints パッケージに格納します。ディレクトリ構造は次のようになります。

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

ベストプラクティスについては、github.com/bazelbuild/platforms をご覧ください。また、すでに存在する制約を確認して、言語に依存しない制約がある場合は、そこに貢献することを検討してください。カスタム制約を導入する際は、ルールのすべてのユーザーが、BUILD ファイルでプラットフォーム固有のロジックを実行するために（選択を使用するなど）使用することを考慮してください。カスタム制約を使用すると、Bazel エコシステム全体が使用する言語を定義できます。

Runfiles ライブラリ

ルールで runfile にアクセスするための標準ライブラリを提供する場合は、//<LANG>/runfiles（//<LANG>/runfiles:runfiles の省略形）にあるライブラリターゲットの形式にする必要があります。データ依存関係にアクセスする必要があるユーザーターゲットは、通常、このターゲットを deps 属性に追加します。

リポジトリルール

依存関係

ルールに外部依存関係がある可能性があります。ルールへの依存関係を簡素化するには、これらの外部依存関係の依存関係を宣言する WORKSPACE マクロを指定してください。テストの依存関係は宣言せず、ルールの動作に必要な依存関係のみを宣言します。開発依存関係を WORKSPACE ファイルに配置します。

<LANG>/repositories.bzl という名前のファイルを作成し、rules_<LANG>_dependencies という名前の単一のエントリポイントマクロを指定します。ディレクトリは次のようになります。

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl
    repositories.bzl

ツールチェーンの登録

ルールでツールチェーンを登録することもできます。これらのツールチェーンを登録する別の WORKSPACE マクロを指定してください。これにより、ユーザーは以前のマクロを省略し、依存関係を手動で制御しながら、ツールチェーンを登録できます。

そのため、rules_<LANG>_toolchains という名前の WORKSPACE マクロを <LANG>/repositories.bzl ファイルに追加します。

分析フェーズでツールチェーンを解決するには、Bazel は登録されているすべての toolchain ターゲットを分析する必要があります。Bazel は、toolchain.toolchain 属性で参照されるすべてのターゲットを分析する必要がなくなります。ツールチェーンを登録するためにリポジトリで複雑な計算を行う必要がある場合は、toolchain ターゲットを含むリポジトリと <LANG>_toolchain ターゲットを含むリポジトリを分割することを検討してください。前者は常にフェッチされ、後者はユーザーが実際に <LANG> コードをビルドする必要がある場合にのみフェッチされます。

リリーススニペット

リリースのお知らせで、ユーザーが WORKSPACE ファイルにコピーして貼り付けることができるスニペットを提供します。このスニペットは通常、次のようになります。

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_<LANG>",
    urls = ["<url_to_the_release.zip"],
    sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()

テスト

ルールが想定どおりに機能することを確認するテストが必要です。これは、ルールが対象とする言語の標準の場所、または最上位の tests/ ディレクトリに配置できます。

例（省略可）

ルールの基本的な使用方法を示す examples/ ディレクトリがあると、ユーザーにとって便利です。

テスト

スタートガイドのドキュメントに記載されている手順に沿って Travis を設定します。次の内容の .travis.yml ファイルをリポジトリに追加します。

dist: xenial  # Ubuntu 16.04

# On trusty (or later) images, the Bazel apt repository can be used.
addons:
  apt:
    sources:
    - sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
      key_url: 'https://bazel.build/bazel-release.pub.gpg'
    packages:
    - bazel

script:
  - bazel build //...
  - bazel test //...

リポジトリが bazelbuild 組織にある場合は、ci.bazel.build に追加するようリクエストできます。

ドキュメント

ドキュメントを自動生成できるようにルールにコメントを付ける方法については、Stardoc のドキュメントをご覧ください。

よくある質問

メインの Bazel GitHub リポジトリにルールを追加できないのはなぜですか？

ルールと Bazel リリースを可能な限り分離したいと考えています。個々のルールの所有者が明確になり、Bazel デベロッパーの負荷が軽減されます。ユーザーにとって、分離によりルールの変更、アップグレード、ダウングレード、置換が容易になります。ルールへのコントリビューションは、ルールに応じて、対応する GitHub リポジトリへの完全な送信アクセス権など、Bazel へのコントリビューションよりも軽量な場合があります。Bazel 自体への送信アクセス権を取得するプロセスは、はるかに複雑です。

デメリットは、ユーザーにとって 1 回限りのインストールプロセスが複雑になることです。上記の README.md セクションに記載されているように、ルールを WORKSPACE ファイルにコピーして貼り付ける必要があります。

以前は、すべてのルールが Bazel リポジトリ（//tools/build_rules または //tools/build_defs の下）にありました。現在もいくつかのルールが残っていますが、残りのルールを移行する作業を進めています。