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

Aktionen

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Modul mit Funktionen zum Erstellen von Aktionen. Greifen Sie über ctx.actions auf dieses Modul zu.

Mitglieder

args

Args actions.args()

Gibt ein Args-Objekt zurück, mit dem speichereffiziente Befehlszeilen erstellt werden können.

Verzeichnis deklarieren

File actions.declare_directory(filename, *, sibling=None)

Gibt an, dass die Regel oder der Aspekt ein Verzeichnis mit dem angegebenen Namen im aktuellen Paket erstellt. Sie müssen eine Aktion erstellen, mit der das Verzeichnis generiert wird. Auf den Inhalt des Verzeichnisses kann nicht direkt von Starlark aus zugegriffen werden, er kann aber in einem Aktionsbefehl mit Args.add_all() maximiert werden.

Parameter

Parameter Beschreibung
filename erforderlich
Wenn kein Pfad angegeben ist, der Pfad des neuen Verzeichnisses, relativ zum aktuellen Paket. Andernfalls ein Basisname für eine Datei ('sibling' definiert ein Verzeichnis).
sibling File; or None; default = None
Eine Datei, die sich im selben Verzeichnis wie das neu deklarierte Verzeichnis befindet Die Datei muss sich im aktuellen Paket befinden.

Datei deklarieren

File actions.declare_file(filename, *, sibling=None)

Gibt an, dass die Regel oder der Aspekt eine Datei mit dem angegebenen Dateinamen erstellt. Wenn sibling nicht angegeben ist, bezieht sich der Dateiname auf das Paketverzeichnis. Andernfalls befindet sich die Datei im selben Verzeichnis wie sibling. Dateien können nicht außerhalb des aktuellen Pakets erstellt werden.

Denken Sie daran, dass Sie nicht nur eine Datei deklarieren, sondern auch eine Aktion erstellen müssen, mit der die Datei ausgegeben wird. Zum Erstellen dieser Aktion muss das zurückgegebene File-Objekt an die Konstruktionsfunktion der Aktion übergeben werden.

Beachten Sie, dass vorgegebene Ausgabedateien nicht mit dieser Funktion deklariert werden müssen und auch nicht deklariert werden können. Sie können stattdessen die File-Objekte von ctx.outputs abrufen. Beispiel für die Verwendung

Parameter

Parameter Beschreibung
filename erforderlich
Wenn kein gleichgeordneter Pfad angegeben ist, ist der Pfad zur neuen Datei in Bezug zum aktuellen Paket. Andernfalls ein Basisname für eine Datei ('sibling' bestimmt ein Verzeichnis).
sibling File; or None; default = None
Eine Datei, die sich im selben Verzeichnis wie die neu erstellte Datei befindet Die Datei muss sich im aktuellen Paket befinden.

File actions.declare_symlink(filename, *, sibling=None)

Experimentell: Dieser Parameter ist experimentell und kann sich jederzeit ändern. Verlassen Sie sich nicht darauf. Es kann zu Testzwecken aktiviert werden, indem --experimental_allow_unresolved_symlinks festgelegt wird

Gibt an, dass die Regel oder der Aspekt einen Symlink mit dem angegebenen Namen im aktuellen Paket erstellt. Sie müssen eine Aktion erstellen, mit der dieser Symlink generiert wird. Bazel dereferenziert dieses Symlink niemals und überträgt es wortwörtlich in Sandboxes oder Remote-Executors.

Parameter

Parameter Beschreibung
filename erforderlich
Wenn kein Pfad angegeben ist, der Pfad des neuen Symlinks relativ zum aktuellen Paket. Andernfalls ein Basisname für eine Datei ('sibling' definiert ein Verzeichnis).
sibling File; or None; default = None
Eine Datei im selben Verzeichnis wie die neu deklarierte Symlink-Datei

nichts

None actions.do_nothing(mnemonic, inputs=[])

Erstellt eine leere Aktion, die weder einen Befehl ausführt noch eine Ausgabe erzeugt, aber zum Einfügen von 'zusätzlichen Aktionen' nützlich ist.

Parameter

Parameter Beschreibung
mnemonic erforderlich
Eine aus einem Wort bestehende Beschreibung der Aktion, z. B. „CPPCompile“ oder „GoLink“.
inputs sequence of Files; or depset; default = []
Liste der Eingabedateien der Aktion.

Vorlage maximieren

None actions.expand_template(template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)

Erstellt eine Vorlage-Erweiterungsaktion. Wenn die Aktion ausgeführt wird, wird eine Datei basierend auf einer Vorlage erstellt. Teile der Vorlage werden mithilfe des substitutions-Wörterbuchs in der angegebenen Reihenfolge ersetzt. Wenn ein Schlüssel des Wörterbuchs in der Vorlage oder als Ergebnis einer vorherigen Ersetzung angezeigt wird, wird er durch den zugehörigen Wert ersetzt. Für die Schlüssel gibt es keine spezielle Syntax. Sie können beispielsweise geschweifte Klammern verwenden, um Konflikte zu vermeiden (z. B. {KEY}). Beispiel für Verwendung.

Parameter

Parameter Beschreibung
template erforderlich
Die Vorlagendatei, eine UTF-8-codierte Textdatei.
output erforderlich
Die Ausgabedatei ist eine UTF-8-codierte Textdatei.
substitutions default = {}
Ersetzungen, wenn Sie die Vorlage maximieren.
is_executable default = False
Gibt an, ob die Ausgabedatei ausführbar sein soll.
computed_substitutions TemplateDict; default = unbound
Experimentell. Dieser Parameter ist experimentell und kann sich jederzeit ändern. Verlassen Sie sich nicht darauf. Sie kann auf experimenteller Basis aktiviert werden, indem Sie --+experimental_lazy_template_expansion
Experimentell: Ersetzungen beim Maximieren der Vorlage festlegen.

run

None actions.run(outputs, inputs=[], unused_inputs_list=None, executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None)

Erstellt eine Aktion, die eine ausführbare Datei ausführt. Beispiel für die Verwendung

Parameter

Parameter Beschreibung
outputs sequence of Files; erforderlich
Liste der Ausgabedateien der Aktion.
inputs sequence of Files; or depset; default = []
Liste oder Zusammenstellung der Eingabedateien der Aktion.
unused_inputs_list File; or None; default = None
Datei mit einer Liste der Eingaben, die von der Aktion nicht verwendet werden

Der Inhalt dieser Datei (in der Regel eine der Ausgaben der Aktion) entspricht der Liste der Eingabedateien, die während der gesamten Aktionsausführung nicht verwendet wurden. Änderungen an diesen Dateien dürfen die Ergebnisse der Aktion in keiner Weise beeinflussen.

executable File; or string; or FilesToRunProvider; erforderlich
Die ausführbare Datei, die von der Aktion aufgerufen werden soll.
tools sequence; or depset; default = unbound
Liste aller Tools, die von der Aktion benötigt werden, oder deren Festlegung Tools sind Eingaben mit zusätzlichen Runfiles, die automatisch für die Aktion zur Verfügung gestellt werden. Wenn eine Liste zur Verfügung gestellt wird, kann es eine heterogene Sammlung von Dateien, FilesToRunProvider-Instanzen oder Dateidepups sein. Bei Dateien, die sich direkt in der Liste befinden und aus ctx.executable stammen, werden die Ausführungsdateien automatisch hinzugefügt. Wenn eine Spezifikation bereitgestellt wird, darf sie nur Dateien enthalten. In beiden Fällen wird für Dateien innerhalb von desets kein Querverweis mit ctx.executable für Runfiles festgelegt.
arguments sequence; default = []
Befehlszeilenargumente der Aktion. Muss eine Liste von Strings oder actions.args()-Objekten sein.
mnemonic string; or None; default = None
Eine aus einem Wort bestehende Beschreibung der Aktion, z. B. „CppCompile“ oder „GoLink“.
progress_message string; or None; default = None
Fortschrittsmeldung, die dem Nutzer während des Builds angezeigt wird, z. B. "foo.cc wird erstellt, um foo.o" zu erstellen. Die Nachricht kann %{label}-, %{input}- oder %{output}-Muster enthalten, die jeweils durch den Labelstring, die erste Eingabe oder den Pfad der Ausgabe ersetzt werden. Ich bevorzuge Muster anstelle von statischen Strings, da erstere effizienter sind.
use_default_shell_env default = False
Gibt an, ob die Aktion die integrierte Shell-Umgebung verwenden soll oder nicht.
env dict; or None; default = None
Legt das Wörterbuch der Umgebungsvariablen fest.
execution_requirements dict; or None; default = None
Informationen zur Planung der Aktion Unter Tags finden Sie nützliche Schlüssel.
input_manifests sequence; or None; default = None
(Experimentell) legt die Metadaten der eingegebenen Runfiles fest. Sie werden in der Regel durch "resolve_command" generiert.
exec_group string; or None; default = None
Führt die Aktion auf der angegebenen Ausführungsplattform der Ausführungsgruppe aus. Wenn keine vorhanden, wird die standardmäßige Ausführungsplattform des Ziels verwendet.
shadowed_action Action; default = None
Führt die Aktion anhand der Eingaben und der Umgebung der verdeckten Aktionen aus, die der Eingabeliste und Umgebung der Aktion hinzugefügt wurden. In der Aktionsumgebung können die Umgebungsvariablen der verdeckten Aktionen überschrieben werden. Wenn nichts angegeben, werden nur die Eingaben und die Umgebung der Aktion verwendet.
resource_set callable; or None; default = None
Eine Callback-Funktion, die ein Wörterbuch für Ressourcensätze zurückgibt, mit dem die Ressourcennutzung bei der Ausführung geschätzt wird, wenn diese Aktion lokal ausgeführt wird.

Die Funktion akzeptiert zwei Positionsargumente: einen String, der einen Betriebssystemnamen darstellt (z.B. "osx") und eine Ganzzahl, die die Anzahl der Eingaben für die Aktion darstellt. Das zurückgegebene Wörterbuch kann die folgenden Einträge enthalten, die jeweils eine Gleitkommazahl oder eine Ganzzahl sein können:

  • "cpu": Anzahl der CPUs; Standard 1
  • &memory; Arbeitsspeicher: in MB; Standard: 250
  • "local_test": Anzahl lokaler Tests; Standard 1

Wenn dieser Parameter auf None gesetzt oder --experimental_action_resource_set auf „false“ gesetzt ist, werden die Standardwerte verwendet.

Der Callback muss auf oberster Ebene erfolgen (Lambda- und verschachtelte Funktionen sind nicht zulässig).

Shell ausführen

None actions.run_shell(outputs, inputs=[], tools=unbound, arguments=[], mnemonic=None, command, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None)

Erstellt eine Aktion, die einen Shell-Befehl ausführt. Beispiel für die Verwendung

Parameter

Parameter Beschreibung
outputs sequence of Files; erforderlich
Liste der Ausgabedateien der Aktion.
inputs sequence of Files; or depset; default = []
Liste oder Zusammenstellung der Eingabedateien der Aktion.
tools sequence of Files; or depset; default = unbound
Liste aller Tools, die von der Aktion benötigt werden, oder deren Festlegung Tools sind Eingaben mit zusätzlichen Runfiles, die automatisch für die Aktion zur Verfügung gestellt werden. Die Liste kann Files- oder FilesToRunProvider-Instanzen enthalten.
arguments sequence; default = []
Befehlszeilenargumente der Aktion. Muss eine Liste von Strings oder actions.args()-Objekten sein.

Bazel übergibt die Elemente in diesem Attribut als Argumente an den Befehl. Der Befehl kann auf diese Argumente zugreifen, indem er Shell-Variablen ersetzt, z. B. $1, $2 usw. Beachten Sie, dass Args-Objekte vor der Indexierung vereinfacht werden. Wenn also ein Args-Objekt mit unbekannter Größe vorhanden ist, befinden sich alle nachfolgenden Strings in unvorhersehbaren Indexen. Es kann nützlich sein, $@ zum Abrufen aller Argumente in Verbindung mit Args-Objekten von unbestimmter Größe zu verwenden.

Wenn command eine Liste von Strings ist, darf dieser Parameter nicht verwendet werden.

mnemonic string; or None; default = None
Eine aus einem Wort bestehende Beschreibung der Aktion, z. B. „CppCompile“ oder „GoLink“.
command string; or sequence of strings; erforderlich
Shell-Befehl zur Ausführung. Dies kann entweder ein String (bevorzugt) oder eine Folge von Strings (eingestellt) sein.

Wenn command ein String ist, wird er so ausgeführt, als wäre sh -c <command> "" <arguments> – das heißt, die Elemente in arguments werden dem Befehl als $1, $2 (oder %1, %2 bei Verwendung eines Windows-Batch) usw. zur Verfügung gestellt. Wenn arguments actions.args()-Objekte enthält, wird der Inhalt nacheinander an die Befehlszeile angehängt, sodass $i auf einzelne Strings innerhalb eines Args-Objekts verweisen kann. Wenn ein Args-Objekt mit unbekannter Größe als Teil von arguments übergeben wird, haben die Strings einen unbekannten Index. In diesem Fall kann die Shell-Ersetzung von $@ (alle Argumente abrufen) hilfreich sein.

(Eingestellt) Wenn command eine Reihe von Strings ist, ist das erste Element die ausführbare Datei und die verbleibenden Elemente sind ihre Argumente. Bei Verwendung dieses Formulars darf der Parameter arguments nicht angegeben werden. Hinweis: Dieses Formular wurde eingestellt und wird bald entfernt. Sie wurde mit „--incompatible_run_shell_command_string`“ deaktiviert. Verwenden Sie dieses Flag, um zu prüfen, ob Ihr Code kompatibel ist.

Bazel verwendet dieselbe Shell, um den Befehl wie bei Genrules auszuführen.

progress_message string; or None; default = None
Fortschrittsmeldung, die dem Nutzer während des Builds angezeigt wird, z. B. "foo.cc wird erstellt, um foo.o" zu erstellen. Die Nachricht kann %{label}-, %{input}- oder %{output}-Muster enthalten, die jeweils durch den Labelstring, die erste Eingabe oder den Pfad der Ausgabe ersetzt werden. Ich bevorzuge Muster anstelle von statischen Strings, da erstere effizienter sind.
use_default_shell_env default = False
Gibt an, ob die Aktion die integrierte Shell-Umgebung verwenden soll oder nicht.
env dict; or None; default = None
Legt das Wörterbuch der Umgebungsvariablen fest.
execution_requirements dict; or None; default = None
Informationen zur Planung der Aktion Unter Tags finden Sie nützliche Schlüssel.
input_manifests sequence; or None; default = None
(Experimentell) legt die Metadaten der eingegebenen Runfiles fest. Sie werden in der Regel durch "resolve_command" generiert.
exec_group string; or None; default = None
Führt die Aktion auf der angegebenen Ausführungsplattform der Ausführungsgruppe aus. Wenn keine vorhanden, wird die standardmäßige Ausführungsplattform des Ziels verwendet.
shadowed_action Action; default = None
Führt die Aktion mit der angegebenen erkannten Eingabe aus, die der Eingabeliste der Aktion hinzugefügt wurde. Falls nicht, werden nur die Eingaben der Aktion verwendet.
resource_set callable; or None; default = None
Eine Callback-Funktion zum Schätzen der Ressourcennutzung, wenn diese lokal ausgeführt wird. Weitere Informationen finden Sie unter ctx.actions.run().

None actions.symlink(output, target_file=None, target_path=None, is_executable=False, progress_message=None)

Erstellt eine Aktion, die einen Symlink in das Dateisystem schreibt.

Diese Funktion muss mit einem der Elemente target_file oder target_path aufgerufen werden.

Wenn target_file verwendet wird, muss output durch declare_file() oder declare_directory() deklariert werden und mit dem Typ von target_file übereinstimmen. In diesem Fall ist output ein symlink, dessen Inhalte der Pfad von target_file sind.

Wenn target_path verwendet wird, muss output mit declare_symlink() deklariert werden. In diesem Fall ist output ein symlink, dessen Inhalte target_path sind. Damit kann ein hängender symlink erstellt werden.

Parameter

Parameter Beschreibung
output erforderlich
Die Ausgabe dieser Aktion.
target_file File; or None; default = None
Die Datei, auf die der Symlink der Ausgabe verweist
target_path string; or None; default = None
(Experimentell) Der genaue Pfad, auf den der Symlink der Ausgabe verweist. Es wird keine Normalisierung oder sonstige Verarbeitung angewendet. Für den Zugriff auf diese Funktion muss --experimental_allow_unresolved_symlinks festgelegt werden.
is_executable default = False
Kann nur mit target_file und nicht mit target_path verwendet werden. Wenn „true“ festgelegt ist, wird beim Ausführen der Aktion der Pfad von target_file geprüft, um festzustellen, ob die Datei ausgeführt werden kann. Ist das nicht der Fall, wird ein Fehler gemeldet. Wenn is_executable auf „False“ gesetzt ist, heißt das nicht, dass das Ziel nicht ausführbar ist. Es bedeutet nur, dass keine Bestätigung erfolgt ist.

Diese Funktion ergibt für target_path keinen Sinn, da möglicherweise zu Beginn der Erstellung keine Symlinks vorhanden sind.

progress_message string; or None; default = None
Fortschrittsmeldung, die dem Nutzer während des Builds angezeigt wird

Vorlage – Wörter

TemplateDict actions.template_dict()

Experimentell: Diese API ist experimentell und kann sich jederzeit ändern. Verlassen Sie sich nicht darauf. Sie kann auf experimenteller Basis aktiviert werden, indem Sie --+experimental_lazy_template_expansion
Experimentell: Gibt ein TemplateDict-Objekt für die speichereffiziente Vorlagenerweiterung zurück.

write

None actions.write(output, content, is_executable=False)

Erstellt eine Dateischreibaktion. Wenn die Aktion ausgeführt wird, wird der jeweilige Inhalt in eine Datei geschrieben. Wird verwendet, um Dateien mit Informationen zu erstellen, die in der Analysephase verfügbar sind. Wenn die Datei groß ist und viele statische Inhalte hat, sollten Sie expand_template verwenden.

Parameter

Parameter Beschreibung
output erforderlich
Die Ausgabedatei.
content string; or Args; erforderlich
ist der Inhalt der Datei. Kann ein String oder ein actions.args()-Objekt sein.
is_executable default = False
Gibt an, ob die Ausgabedatei ausführbar sein soll.