database create

Übersicht

codeql database create [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--source-root=<dir>] [--threads=<num>] [--ram=<MB>] [--command=<command>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

codeql database create [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--source-root=<dir>] [--threads=<num>] [--ram=<MB>] [--command=<command>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

Beschreibung

Erstellt eine CodeQL-Datenbank für eine Quellstruktur, die mithilfe eines der CodeQL-Produkte analysiert werden kann.

Optionen

Primäre Optionen

<database>

[Obligatorisch] Pfad zu der CodeQL-Datenbank, die erstellt werden soll. Dieses Verzeichnis wird erstellt und darf noch nicht vorhanden sein (aber das übergeordnete Verzeichnis muss vorhanden sein).

Wenn die Option --db-cluster angegeben ist, handelt es sich nicht um eine Datenbank als solches, sondern um ein Verzeichnis, das Datenbanken für mehrere Sprachen enthält, die aus demselben Quellstammverzeichnis erstellt wurden.

Es ist wichtig, dass sich dieses Verzeichnis nicht an einem Speicherort befindet, an dem der Buildprozess beeinträchtigt wird. Das Verzeichnis target eines Maven-Projekts wäre zum Beispiel keine geeignete Wahl.

--[no-]overwrite

[Erweitert] Wenn die Datenbank bereits vorhanden ist, lösche sie, und fahre mit diesem Befehl fort, bevor der Vorgang fehlschlägt. Wenn das Verzeichnis existiert, aber nicht wie eine Datenbank aussieht, wird ein Fehler ausgelöst.

--[no-]force-overwrite

[Erweitert] Wenn die Datenbank bereits vorhanden ist, müssen Sie sie löschen, auch wenn sie nicht wie eine Datenbank aussieht, und mit diesem Befehl fortfahren, bevor der Vorgang fehlschlägt. Diese Option sollte mit Vorsicht verwendet werden, da sie das gesamte Datenbankverzeichnis rekursiv löschen kann.

--codescanning-config=<file>

[Erweitert] Liest eine Konfigurationsdatei für die Codeüberprüfung, die Optionen zum Erstellen der CodeQL-Datenbanken und die in späteren Schritten auszuführenden Abfragen angibt. Weitere Informationen zum Format dieser Konfigurationsdatei finden Sie unter Anpassen des erweiterten Setups für das Codescanning. Um Abfragen aus dieser Datei in einem späteren Schritt auszuführen, rufe codeql database analyze ohne weitere Abfragen auf.

--[no-]db-cluster

Anstatt eine einzige Datenbank zu erstellen, erstelle einen „Cluster“ aus Datenbanken für verschiedene Sprachen, die jeweils ein Unterverzeichnis des in der Befehlszeile angegebenen Verzeichnisses sind.

-l, --language=<lang>[,<lang>...]

Die Sprache, die von der neuen Datenbank analysiert wird.

Verwende codeql resolve languages, um eine Liste der austauschbaren Sprachextraktoren abzurufen, die im Suchpfad gefunden wurden.

Wenn die Option --db-cluster angegeben ist, kann dies mehrmals angezeigt werden, oder der Wert kann eine durch Trennzeichen getrennte Liste von Sprachen sein.

Wenn diese Option weggelassen wird und das zu analysierende Quellstammverzeichnis ein Check-Out eines GitHub-Repositorys ist, ruft die CodeQL-CLI die GitHub-API auf, um automatisch zu ermitteln, welche Sprachen analysiert werden sollen. Beachte, dass dazu ein GitHub PAT-Token entweder in der Umgebungsvariablen GITHUB_TOKEN oder über die Standardeingabe mit der Option --github-auth-stdin bereitgestellt werden muss.

--build-mode=<mode>

Der Buildmodus, der zum Erstellen der Datenbank verwendet wird.

Wählen Sie Ihren Buildmodus basierend auf der Sprache aus, die Sie analysieren:

none: Die Datenbank wird erstellt, ohne dass dabei der Quellstamm erstellt wird. Verfügbar für C#, Java, JavaScript/TypeScript, Python und Ruby.

autobuild: Die Datenbank wird erstellt, indem versucht wird, den Quellstamm automatisch zu erstellen. Verfügbar für C/C++, C#, Go, Java/Kotlin und Swift.

manual: Die Datenbank wird erstellt, indem der Quellstamm mithilfe eines manuell angegebenen Buildbefehls erstellt wird. Verfügbar für C/C++, C#, Go, Java/Kotlin und Swift.

Beim Erstellen einer Datenbank mit --command muss nicht zusätzlich „--build-mode none“ angegeben werden.

Verfügbar seit v2.16.4.

-s, --source-root=<dir>

[Standard: .] Das Stammverzeichnis für den Quellcode. In vielen Fällen ist dies das Check-Out-Stammverzeichnis. Die darin enthaltenen Dateien gelten als primäre Quelldateien für diese Datenbank. In einigen Ausgabeformaten wird auf Dateien durch den relativen Pfad aus diesem Verzeichnis verwiesen.

-j, --threads=<num>

Dient zum Festlegen der Anzahl von Threads für den Importvorgang, und zum Übergeben der Anzahl als Hinweis an alle aufgerufenen Buildbefehle.

Der Standardwert lautet 1. 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 Menge an Arbeitsspeicher für den Importvorgang, und zum Übergeben des Werts als Hinweis an alle aufgerufenen Buildbefehle.

-c, --command=<command>

Erstelle für kompilierte Sprachen Befehle, die dazu führen, dass der Compiler im zu analysierenden Quellcode aufgerufen wird. Diese Befehle werden in einer Instrumentierungsumgebung ausgeführt, die die Analyse von generiertem Code und (in einigen Fällen) Standardbibliotheken ermöglicht.

Wenn kein Buildbefehl angegeben ist, versucht der Befehl, automatisch im ausgewählten Sprachpaket heuristisch herauszufinden, wie die Quellstruktur erstellt werden soll.

Beachte, dass für einige Kombinationen mit mehreren Sprachen ein expliziter Buildbefehl angegeben werden muss.

--no-cleanup

[Erweitert] Unterdrückt alle Datenbankbereinigungen nach der Finalisierung. Hilfreich beim Debuggen.

--no-pre-finalize

[Erweitert] Überspringt alle Vorabfinalisierungsskripts, die ggf. vom aktiven CodeQL-Extraktor angegebenen wurden.

--[no-]skip-empty

[Erweitert] Gibt eine Warnung aus, anstatt einen Fehler zu verursachen, wenn eine Datenbank leer ist, da während des Builds kein Quellcode verfügbar war. Die leere Datenbank wird nicht finalisiert.

--[no-]linkage-aware-import

[Erweitert] Steuert, ob der Import von Codeql-Datasets verknüpfungsfähig (Standard) ist oder nicht. Bei Projekten, bei denen dieser Teil der Datenbankerstellung zu viel Arbeitsspeicher verbraucht, kann die Deaktivierung dieser Option den Fortschritt auf Kosten der Vollständigkeit der Datenbank fördern.

Verfügbar seit v2.15.3.

Baselineberechnungsoptionen

--[no-]calculate-baseline

[Erweitert] Berechnet Baselineinformationen zum analysierten Code, und fügt sie der Datenbank hinzu. Standardmäßig ist dies aktiviert, es sei denn, der Quellstamm ist das Stammverzeichnis eines Dateisystems. Dieses Flag kann verwendet werden, um das Verhalten auch im Stammverzeichnis des Dateisystems zu deaktivieren oder zu erzwingen.

--[no-]sublanguage-file-coverage

[Nur GitHub.com und GitHub Enterprise Server v3.12.0+] Verwenden Sie Informationen zur Dateiabdeckung in Untersprache. Dadurch werden separate Dateiabdeckungsinformationen für Sprachen berechnet, angezeigt und exportiert, die einen CodeQL-Extraktor wie C und C++, Java und Kotlin sowie JavaScript und TypeScript gemeinsam nutzen.

Verfügbar seit v2.15.2.

Optionen zur Extraktorauswahl

--search-path=<dir>[:<dir>...]

Eine Liste der Verzeichnisse, in denen Extraktorpakete gefunden werden können. Bei den Verzeichnissen handelt es sich entweder um die Extraktorpakete selbst oder um Verzeichnisse, die Extraktoren als unmittelbare Unterverzeichnisse enthalten.

Enthält der Pfad mehrere Verzeichnisstrukturen, bestimmt ihre Reihenfolge den Vorrang zwischen ihnen: Wenn die Zielsprache in mehr als einer der Verzeichnisstrukturen vorkommt, gilt die zuerst angegebene.

Die Extraktoren, die mit der CodeQL-Toolkette selbst gebündelt sind, werden immer gefunden. Wenn du jedoch separat verteilte Extraktoren verwenden musst, musst du diese Option angeben (oder, noch besser, --search-path in einer Konfigurationsdatei pro Benutzer*in einrichten).

(Hinweis: Unter Windows wird ; als Pfadtrennzeichen verwendet.)

Optionen zum Konfigurieren des Aufrufs der GitHub-API zur automatischen Spracherkennung.

-a, --github-auth-stdin

Akzeptiert ein GitHub Apps-Token oder ein persönliches Zugriffstoken über die Standardeingabe.

Dadurch wird die GITHUB_TOKEN-Umgebungsvariable überschrieben.

-g, --github-url=<url>

URL der zu verwendenden GitHub-Instanz. Wenn nicht angegeben, versucht die CLI, diese automatisch über den Check-Out-Pfad zu ermitteln. Wenn dies nicht möglich ist, wird diese standardmäßig auf https://github.com/ gesetzt.

Optionen zum Konfigurieren des Paket-Managers.

--registries-auth-stdin

Führt eine Authentifizierung bei GitHub Enterprise Server-Containerregistrierungen durch, indem eine durch Trennzeichen getrennte Liste von <registry_url>=<token>-Paaren übergeben wird.

Du kannst https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 übergeben, um dich bei zwei GitHub Enterprise Server-Instanzen zu authentifizieren.

Dadurch werden die Umgebungsvariablen CODEQL_REGISTRIES_AUTH und GITHUB_TOKEN überschrieben. Wenn du dich nur bei der Containerregistrierung von github.com authentifizieren musst, kannst du dich stattdessen mit der einfacheren Option --github-auth-stdin authentifizieren.

Optionen für die Bereinigung von Datasets auf niedriger Ebene

--max-disk-cache=<MB>

Dient zum Festlegen des maximalen Speicherplatzes, der vom Datenträgercache für Zwischenergebnisse von Abfragen beansprucht werden darf.

Wird diese Größe nicht explizit konfiguriert, versucht der Auswerter, basierend auf der Größe des Datasets und der Komplexität der Abfragen eine angemessene Menge an Cachespeicherplatz zu verwenden. Durch explizites Festlegen eines höheren Grenzwerts (im Vergleich zur Standardnutzung) können mehr Daten zwischengespeichert werden, was spätere Abfragen beschleunigen kann.

--min-disk-free=<MB>

[Erweitert] Dient zum Festlegen der Zielmenge des freien Speicherplatzes im Dateisystem.

Ohne Angabe von --max-disk-cache versucht der Auswerter nach Möglichkeit, die Nutzung des Datenträgercaches einzuschränken, wenn der freie Speicherplatz im Dateisystem diesen Wert unterschreitet.

--min-disk-free-pct=<pct>

[Erweitert] Dient zum Festlegen des Zielanteils des freien Speicherplatzes im Dateisystem.

Ohne Angabe von --max-disk-cache versucht der Auswerter nach Möglichkeit, die Nutzung des Datenträgercaches einzuschränken, wenn der freie Speicherplatz im Dateisystem diesen Prozentsatz unterschreitet.

--cache-cleanup=<mode>

Wähle aus, wie aggressiv der Cache gekürzt werden soll. Verfügbare Optionen:

clear: Entfernt den gesamten Cache, um den Zustand eines frisch extrahierten Datasets zu erreichen.

trim (Standardwert) : Kürzt alles bis auf explizit zwischengespeicherte Prädikate.

fit: Stellt lediglich sicher, dass die definierten Größenlimits für den Datenträgercache eingehalten werden, und löscht so viele Zwischenelemente wie nötig.

--cleanup-upgrade-backups

Löscht alle ggf. vorhandenen Sicherungsverzeichnisse, die bei Datenbankupgrades erstellt wurden.

Ablaufverfolgungsoptionen

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

Optionen zum Anpassen von Buildbefehlen

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