database trace-command

Übersicht

codeql database trace-command [--threads=<num>] [--ram=<MB>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database> <command>...

codeql database trace-command [--threads=<num>] [--ram=<MB>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database> <command>...

Beschreibung

[Plumbing] Führt einen einzelnen Befehl als Teil eines überwachten Builds aus.

Dadurch wird eine einzelne angegebene Befehlszeile mit Ablaufverfolgung ausgeführt, wodurch möglicherweise eine Extraktion ausgeführt, aber die resultierende CodeQL-Datenbank nicht finalisiert wird.

Optionen

Primäre Optionen

<database>

[Obligatorisch] Pfad zur CodeQL-Datenbank, die sich im Aufbau befindet. Dieser muss für die Extraktion mit codeql database init vorbereitet sein.

Wenn die Option --db-cluster angegeben ist, handelt es sich nicht um eine Datenbank als solches, sondern um ein Verzeichnis, das Datenbanken enthält. Es werden dann alle diese Datenbanken zusammen verarbeitet.

<command>...

Der auszuführende Befehl. Es sind ein einzelnes oder mehrere Argumente möglich, die zum Erstellen des Prozesses verwendet werden. Es wird empfohlen, das Argument „--“ vor dem Auflisten der Argumente des Befehls zu übergeben, um Verwechslungen zwischen den Argumenten und unseren zu vermeiden.

Es wird erwartet, dass der Befehl mit dem Statuscode 0 beendet wird. Jeder andere Exitcode wird als Fehler interpretiert.

Der Befehl kann ausgelassen werden, wenn --index-traceless-dbs angegeben wird.

-j, --threads=<num>

Dient zum Festlegen der Anzahl von Threads, die der Extraktor verwenden soll. Diese Option wird als Vorschlag an den Extraktor übergeben. Wenn die Umgebungsvariable „CODEQL_THREADS“ festgelegt wird, hat der Wert der Umgebungsvariablen Vorrang vor dieser Option.

Du kannst 0 übergeben, um jeweils einen Thread pro Kern auf dem Computer zu verwenden, oder -N, um N Kerne ungenutzt zu lassen. (Es wird allerdings immer noch mindestens ein Thread verwendet.)

-M, --ram=<MB>

Dient zum Festlegen der Arbeitsspeichermenge, die der Extraktor verwenden soll. Diese Option wird als Vorschlag an den Extraktor übergeben. Wenn die Umgebungsvariable „CODEQL_RAM“ festgelegt wird, hat der Wert der Umgebungsvariablen Vorrang vor dieser Option.

--[no-]db-cluster

Gibt an, dass es sich bei dem in der Befehlszeile angegebenen Verzeichnis nicht um eine Datenbank als solches handelt, sondern um ein Verzeichnis, das eine oder mehrere Datenbanken enthält, die sich im Aufbau befinden. Diese Datenbanken werden zusammen verarbeitet.

--no-tracing

[Erweitert] Verfolgt den angegebenen Befehl nicht, sondern lässt alle erforderlichen Daten direkt durch ihn erzeugen.

--extra-tracing-config=<tracing-config.lua>

[Erweitert] Der Pfad zu einer Konfigurationsdatei für die Ablaufverfolgung. Er kann verwendet werden, um das Verhalten der Buildablaufverfolgung zu ändern. Er kann verwendet werden, um Compilerprozesse zu ermitteln, die als Teil des Buildbefehls ausgeführt werden, und um die Ausführung anderer Tools auszulösen. Die Extraktoren stellen standardmäßige Konfigurationsdateien für die Ablaufverfolgung bereit, die in den meisten Situationen funktionieren sollten.

--[no-]index-traceless-dbs

Führe zusätzlich zum angegebenen Befehl das Standardskript für Extraktoren aus, die nicht von der Ablaufverfolgung eines Buildprozesses abhängen. Wenn du mit --db-cluster Datenbanken für mehrere Sprachen erstellst, sollte diese Option genau einem Aufruf von codeql database trace-command zugewiesen werden.

--[no-]use-build-mode

Ermitteln Sie, was basierend auf dem Buildmodus der Datenbank ausgeführt werden soll. Diese Option kann nicht in Verbindung mit --index-traceless-dbs verwendet werden.

--working-dir=<dir>

[Erweitert] Das Verzeichnis, in dem der angegebene Befehl ausgeführt werden soll. Ohne Angabe dieses Arguments wird der Befehl in dem Wert von --source-root ausgeführt, der an codeql database create übergeben wird (sofern vorhanden). Ohne Angabe des Arguments --source-root wird der Befehl im aktuellen Arbeitsverzeichnis ausgeführt.

--no-run-unnecessary-builds

[Erweitert] Führt nur die angegebenen Buildbefehle aus, wenn eine Datenbank im Aufbau einen Extraktor verwendet, der von der Ablaufverfolgung eines Buildprozesses abhängig ist. Wenn diese Option nicht angegeben wurde, wird der Befehl auch dann ausgeführt, wenn CodeQL ihn nicht benötigt, da davon ausgegangen wird, dass du die Nebenwirkungen aus anderen Gründen benötigst.

Optionen zum Steuern des Extraktorverhaltens

-O, --extractor-option=<extractor-option-name=value>

Ermöglicht das Festlegen von Optionen für CodeQL-Extraktoren. extractor-option-name muss im Format „Extraktorname.Gruppe1.Gruppe2.Optionsname“ oder im Format „Gruppe1.Gruppe2.Optionsname“ angegeben werden. Wenn extractor_option_name mit einem Extraktornamen beginnt, muss der angegebene Extraktor die Option „Gruppe1.Gruppe2.Optionsname“ deklarieren. Andernfalls wird die Option für jeden Extraktor festgelegt, der die Option „Gruppe1.Gruppe2.Optionsname“ deklariert. value kann eine beliebige Zeichenfolge ohne Zeilenumbruch sein.

Diese Befehlszeilenoption kann wiederholt verwendet werden, um mehrere Extraktoroptionen festzulegen. Wenn du mehrere Werte für die gleiche Extraktoroption angibst, hängt das Verhalten von dem Typ ab, den die Extraktoroption erwartet. Bei Zeichenfolgenoptionen wird der zuletzt angegebene Wert verwendet. Bei Arrayoptionen werden alle angegebenen Werte der Reihe nach verwendet. Mit dieser Befehlszeilenoption angegebene Extraktoroptionen werden nach Extraktoroptionen verarbeitet, die über --extractor-options-file angegeben wurden.

Bei Übergabe an codeql database init oder codeql database begin-tracing werden die Optionen nur auf die indirekte Ablaufverfolgungsumgebung angewendet. Wenn dein Workflow auch Aufrufe an codeql database trace-command sendet, müssen die Optionen auch dorthin übergeben werden, falls gewünscht.

Weitere Informationen zu CodeQL-Extraktoroptionen findest du unter https://codeql.github.com/docs/codeql-cli/extractor-options. Dort erfährst du unter anderem, wie du die von den einzelnen Extraktoren deklarierten Optionen auflisten kannst.

--extractor-options-file=<extractor-options-bundle-file>

Dient zum Angeben von Paketdateien für Extraktoroptionen. Eine Paketdatei für Extraktoroptionen ist eine JSON-Datei (Erweiterung .json) oder eine YAML-Datei (Erweiterung .yaml oder .yml), die Extraktoroptionen festlegt. Die Datei muss über den Zuordnungsschlüssel „Extraktor“ der obersten Ebene und darunter über Extraktornamen als Zuordnungsschlüssel der zweiten Ebene verfügen. Weitere Zuordnungsebenen stellen geschachtelte Extraktorgruppen dar, und Zeichenfolgen- und Arrayoptionen sind Zuordnungseinträge mit Zeichenfolgen- und Arraywerten.

Paketdateien für Extraktoroptionen werden in der angegebenen Reihenfolge gelesen. Wenn verschiedene Paketdateien für Extraktoroptionen die gleiche Extraktoroption angeben, hängt das Verhalten von dem Typ ab, den die Extraktoroption erwartet. Bei Zeichenfolgenoptionen wird der zuletzt angegebene Wert verwendet. Bei Arrayoptionen werden alle angegebenen Werte der Reihe nach verwendet. Mit dieser Befehlszeilenoption angegebene Extraktoroptionen werden vor Extraktoroptionen verarbeitet, die über --extractor-option angegeben wurden.

Bei Übergabe an codeql database init oder codeql database begin-tracing werden die Optionen nur auf die indirekte Ablaufverfolgungsumgebung angewendet. Wenn dein Workflow auch Aufrufe an codeql database trace-command sendet, müssen die Optionen auch dorthin übergeben werden, falls gewünscht.

Weitere Informationen zu CodeQL-Extraktoroptionen finden Sie unter https://codeql.github.com/docs/codeql-cli/extractor-options. Dort erfahren Sie unter anderem, wie du die von den einzelnen Extraktoren deklarierten Optionen auflisten kannst.

Allgemeine Optionen

-h, --help

Zeigt diesen Hilfetext an.

-J=<opt>

[Erweitert] Dient zum Angeben einer Option für die JVM-Instanz, die den Befehl ausführt.

(Beachte, dass Optionen, die Leerzeichen enthalten, nicht ordnungsgemäß verarbeitet werden.)

-v, --verbose

Ermöglicht die inkrementelle Erhöhung der Anzahl ausgegebener Statusmeldungen.

-q, --quiet

Ermöglicht die inkrementelle Verringerung der Anzahl ausgegebener Statusmeldungen.

--verbosity=<level>

[Erweitert] Dient zum expliziten Festlegen des Ausführlichkeitsgrads auf „errors“, „warnings“, „progress“, „progress+“, „progress++“ oder „progress+++“. Überschreibt -v und -q:

--logdir=<dir>

[Erweitert] Ermöglicht das Schreiben detaillierter Protokolle in eine oder mehrere Dateien im angegebenen Verzeichnis mit generierten Namen, die Zeitstempel und den Namen des ausgeführten Unterbefehls enthalten.

(Um eine Protokolldatei mit einem Namen zu schreiben, über den du die volle Kontrolle hast, gib stattdessen --log-to-stderr an, und leite stderr wie gewünscht um.)

--common-caches=<dir>

[Erweitert] Steuert den Speicherort zwischengespeicherter Daten auf dem Datenträger, der zwischen mehreren Ausführungsvorgängen der CLI beibehalten wird, z. B. heruntergeladene QL-Pakete und kompilierte Abfragepläne. Wenn dies nicht explizit festgelegt ist, wird dieses Verzeichnis standardmäßig auf ein Verzeichnis mit dem Namen .codeql festgelegt, das sich im Startverzeichnis des Benutzer. Es wird erstellt, wenn es noch nicht vorhanden ist.

Verfügbar seit v2.15.2.