BazelCon 2022 findet vom 16. bis 17. November in New York und online statt.
Jetzt anmelden

Regeln bereitstellen

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Diese Seite richtet sich an Regelautoren, die ihre Regeln für andere Nutzer verfügbar machen möchten.

Hosting- und Benennungsregeln

Neue Regeln sollten in einem eigenen GitHub-Repository Ihrer Organisation bereitgestellt werden. Wenden Sie sich an die Mailingliste für bazel-dev, wenn Sie glauben, dass Ihre Regeln in die bazelbuild-Organisation gehören.

Repository-Namen für Bazel-Regeln sind im folgenden Format standardisiert: $ORGANIZATION/rules_$NAME. Beispiele auf GitHub Verwenden Sie dieses Format bei der Veröffentlichung Ihrer Bazel-Regeln.

Verwenden Sie eine beschreibende GitHub-Repository-Beschreibung und den README.md-Titel. Beispiel:

  • Repository-Name: bazelbuild/rules_go
  • Repository-Beschreibung: Go rules for Bazel
  • Repository-Tags: golang, bazel
  • README.md-Header: Go-Regeln für Bazel (beachten Sie den Link zu https://bazel.build, der Nutzer führt, die mit den Regeln nicht vertraut sind) Bazel an die richtige Stelle)

Regeln können entweder nach Sprache (z. B. Scala) oder Plattform (z. B. Android) gruppiert werden.

Repository-Inhalt

Jedes Regel-Repository sollte ein bestimmtes Layout haben, damit Nutzer neue Regeln schnell verstehen können.

Wenn Sie beispielsweise neue Regeln für die (mockascript) Sprache erstellen, hat das Regel-Repository die folgende Struktur:

/
  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

Arbeitsbereich

Geben Sie in der WORKSPACE des Projekts den Namen an, den die Nutzer zum Verweisen auf die Regeln verwenden sollen. Wenn Ihre Regeln zur Organisation bazelbuild gehören, müssen Sie rules_<lang> verwenden, z. B. rules_mockascript. Andernfalls sollten Sie Ihr Repository <org>_rules_<lang> nennen (z. B. build_stack_rules_proto). Wenden Sie sich an die bazel-dev-Mailingliste, wenn Sie der Meinung sind, dass Ihre Regeln der Konvention für Regeln der bazelbuild-Organisation entsprechen sollen.

In den folgenden Abschnitten wird davon ausgegangen, dass das Repository zur Organisation bazelbuild gehört.

workspace(name = "rules_mockascript")

README

Auf oberster Ebene sollte ein README enthalten sein, der (mindestens) enthält, was Nutzer kopieren und in ihre WORKSPACE-Datei einfügen müssen, um Ihre Regel zu verwenden. Im Allgemeinen ist dies eine http_archive, die auf Ihren GitHub-Release verweist und ein Makroaufruf, der alle von Ihrer Regel benötigten Tools herunter- bzw. konfiguriert. Für die Go-Regeln sieht das so aus:

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()

Wenn Ihre Regeln von den Regeln eines anderen Repositorys abhängig sind, geben Sie dies in der Regeldokumentation an (z. B. die Skydoc-Regeln, die von den Sass-Regeln abhängen). Ein WORKSPACE-Makro, das alle Abhängigkeiten herunterlädt (siehe rules_go oben).

Regeln

Häufig werden von Ihrem Repository mehrere Regeln bereitgestellt. Erstellen Sie ein Verzeichnis mit dem Namen der Sprache und stellen Sie einen Einstiegspunkt bereit: Die Datei defs.bzl exportiert alle Regeln (einschließlich der Datei BUILD, damit das Verzeichnis ein Paket ist). Für rules_mockascript bedeutet dies, dass es ein Verzeichnis mit dem Namen mockascript sowie eine BUILD-Datei und eine defs.bzl-Datei gibt:

/
  mockascript/
    BUILD
    defs.bzl

Einschränkungen

Wenn Ihre Regel Toolchain-Regeln definiert, müssen Sie möglicherweise benutzerdefinierte constraint_settings und/oder constraint_values definieren. Füge diese in ein //<LANG>/constraints-Paket ein. Die Verzeichnisstruktur sieht so aus:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

Unter github.com/bazelbuild/platforms finden Sie die Best Practices und erfahren, welche Einschränkungen bereits gelten. Gegebenenfalls sollten Sie auch Einschränkungen beachten. Achten Sie darauf, benutzerdefinierte Einschränkungen einzuführen, die von allen Nutzern Ihrer Regeln verwendet werden, um plattformspezifische Logik in ihren BUILD-Dateien auszuführen (z. B. Auswählen). Mit benutzerdefinierten Einschränkungen definieren Sie eine Sprache, die das gesamte Bazel-System spricht.

Runfiles-Bibliothek

Wenn Ihre Regel eine Standardbibliothek für den Zugriff auf Runfiles bereitstellt, sollte sie das Format eines Bibliotheksziels haben, das sich unter //<LANG>/runfiles befindet (Abkürzung für //<LANG>/runfiles:runfiles). Nutzerziele, die auf ihre Datenabhängigkeiten zugreifen müssen, fügen dieses Ziel normalerweise dem Attribut deps hinzu.

Repository-Regeln

Abhängigkeiten

Ihre Regeln können externe Abhängigkeiten haben. Geben Sie zur Vereinfachung der Regeln ein WORKSPACE-Makro an, das Abhängigkeiten von diesen externen Abhängigkeiten deklariert. Deklarieren Sie dort keine Abhängigkeiten von Tests, sondern nur Abhängigkeiten, die für Regeln notwendig sind. Fügen Sie Entwicklungsabhängigkeiten in die Datei WORKSPACE ein.

Erstellen Sie eine Datei mit dem Namen <LANG>/repositories.bzl und stellen Sie ein einzelnes Makro für den Einstiegspunkt mit dem Namen rules_<LANG>_dependencies bereit. Unser Verzeichnis sieht so aus:

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

Toolchains registrieren

Ihre Regeln können auch Toolchains registrieren. Geben Sie ein separates WORKSPACE-Makro an, mit dem diese Toolchains registriert werden. Auf diese Weise können Nutzer entscheiden, das vorherige Makro manuell zu entfernen und die Abhängigkeiten manuell zu steuern, ohne Toolchains zu registrieren.

Fügen Sie daher der Datei <LANG>/repositories.bzl ein WORKSPACE-Makro mit dem Namen rules_<LANG>_toolchains hinzu.

Zur Lösung von Toolchains in der Analysephase muss Bazel alle registrierten toolchain-Ziele analysieren. Bazel muss nicht alle Ziele analysieren, auf die im Attribut toolchain.toolchain verwiesen wird. Wenn Sie zum Registrieren von Toolchains komplexe Berechnungen im Repository ausführen möchten, können Sie das Repository mit toolchain-Zielen aus dem Repository mit <LANG>_toolchain-Zielen aufteilen. Former wird immer abgerufen, der letztere nur, wenn der Nutzer tatsächlich <LANG>-Code erstellen muss.

Release-Snippet

In deiner Release-Ankündigung findest du ein Snippet, das deine Nutzer kopieren und in ihre WORKSPACE-Datei einfügen können. Dieses Snippet sieht im Allgemeinen so aus:

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

Mithilfe von Tests lässt sich prüfen, ob die Regeln wie erwartet funktionieren. Dies kann entweder am Standardspeicherort für die Sprache sein, für die die Regeln gelten, oder in einem tests/-Verzeichnis auf oberster Ebene.

Beispiele (optional)

Es ist nützlich, dass Nutzer ein examples/-Verzeichnis haben, in dem sie einige grundlegende Möglichkeiten der Verwendung der Regeln sehen.

Test

Richten Sie Travis gemäß der Beschreibung in seinen Startleitfadenen ein. Fügen Sie dann Ihrem Repository eine .travis.yml-Datei mit folgendem Inhalt hinzu:

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 //...

Wenn sich Ihr Repository in der Organisation bazelbuild befindet, können Sie es anfordern, es zu ci.bazel.build hinzuzufügen.

Dokumentation

In der Stardoc-Dokumentation wird beschrieben, wie Sie Ihre Regeln kommentieren, damit die Dokumentation automatisch generiert werden kann.

FAQ

Warum können wir unsere Regel nicht dem GitHub-Haupt-Repository hinzufügen?

Wir möchten Regeln von Bazel-Releases so weit wie möglich entkoppeln. Es ist klarer, wer einzelne Regeln besitzt, wodurch die Belastung der Bazel-Entwickler verringert wird. Für unsere Nutzer werden sie durch das Entkoppeln leichter geändert, aktualisiert, herabgestuft und ersetzt. Das Hinzufügen von Regeln zu einer einfacheren Gewichtung als das Posten in Bazel (abhängig von den Regeln) einschließlich des vollständigen Übermittlungszugriffs auf das entsprechende GitHub-Repository. Der Zugriff auf die Übermittlung an Bazel selbst erfordert wesentlich mehr Aufwand.

Der Nachteil ist ein komplizierter einmaliger Installationsprozess für unsere Nutzer: Sie müssen eine Regel kopieren und in ihre WORKSPACE-Datei einfügen, wie im Abschnitt README.md oben gezeigt.

Früher waren alle Regeln im Bazel-Repository vorhanden (unter //tools/build_rules oder //tools/build_defs). Wir haben dort noch ein paar Regeln, aber wir arbeiten daran, die restlichen Regeln zu entfernen.