ルールのデプロイ

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。
問題を報告する ソースを表示

このページは、他のユーザーによるルールの利用を計画しているルール作成者を対象としています。

ホスティングと命名規則

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

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

わかりやすい GitHub リポジトリの説明と README.md タイトルを使用してください。例:

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

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

リポジトリのコンテンツ

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

たとえば、（make-believe）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 ファイルでプラットフォーム固有のロジックを実行する（たとえば、select を使用する）必要があります。カスタム制約では、Bazel エコシステム全体で話される言語を定義します。

Runfiles ライブラリ

ルールでランファイルにアクセスするための標準ライブラリを提供する場合、//<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 属性で参照されているすべてのターゲットを分析する必要はありません。ツールチェーンを登録するためにリポジトリで複雑な計算を行う必要がある場合は、<LANG>_toolchain ターゲットを含むリポジトリから 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 自体に対するアクセス権を取得するプロセスは、はるかに複雑です。

ただし、README.md のように、ルールを WORKSPACE ファイルにコピー&ペーストする必要があると、1 回限りのインストール プロセスが複雑になります。

以前は、Bazel リポジトリ（//tools/build_rules または //tools/build_defs）にすべてのルールが存在していましたが、まだいくつかのルールがありますが、残りのルールの移動を進めています。