database create

Synopsis

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

Description

Crée une base de données CodeQL pour une arborescence source qui peut être analysée à l’aide de l’un des produits CodeQL.

Options

Options principales

<database>

[Obligatoire] Chemin vers la base de données CodeQL à créer. Ce répertoire est créé et ne doit pas déjà exister (mais son parent oui).

Si l’option --db-cluster est donnée, il ne s’agit pas de la base de données elle-même, mais d’un répertoire qui contiendra les bases de données pour plusieurs langages générées à partir de la même racine source.

Il est important que ce répertoire ne se trouve pas à un emplacement avec lequel le processus de génération interférera. Par exemple, le répertoire target d’un projet Maven ne serait pas un choix approprié.

--[no-]overwrite

[Avancé] Si la base de données existe déjà, elle la supprime et poursuit avec cette commande au lieu d’échouer. Cette option doit être utilisée avec prudence, car elle peut supprimer de manière récursive l’intégralité du répertoire de la base de données.

--codescanning-config=<file>

[Avancé] Lit un fichier de configuration d’Analyse du code spécifiant les options de création des bases de données CodeQL et les requêtes à exécuter dans les étapes ultérieures. Pour plus d’informations sur le format de ce fichier de configuration, reportez-vous à Personnalisation de votre configuration avancée pour l’analyse du code. Pour exécuter des requêtes à partir de ce fichier à une étape ultérieure, appelez codeql database analyze sans aucune autre requête spécifiée.

--[no-]db-cluster

Au lieu de créer une base de données unique, créez un « cluster » de bases de données pour différents langages, chacun d’eux étant un sous-répertoire du répertoire donné sur la ligne de commande.

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

Langage utilisé pour analyser la nouvelle base de données.

Utilise codeql resolve languages pour obtenir la liste des extracteurs de langages enfichables trouvés sur le chemin de recherche.

Lorsque l’option --db-cluster est donnée, elle peut apparaître plusieurs fois, ou la valeur peut être une liste de langages séparés par des virgules.

Si cette option est omise et que la racine source en cours d’analyse est une extraction d’un dépôt GitHub, l’interface CLI de CodeQL effectue un appel à l’API GitHub pour tenter de déterminer automatiquement les langages à analyser. Notez que pour pouvoir effectuer cette opération, un jeton PAT GitHub doit être fourni dans la variable d’environnement GITHUB_TOKEN ou via une entrée standard en utilisant l’option --github-auth-stdin.

--build-mode=<mode>

Mode de génération qui sera utilisé pour créer la base de données.

Choisissez votre mode de génération en fonction de la langue que vous analysez :

none : la base de données est créée sans générer la racine source. Disponible pour JavaScript/TypeScript, Python et Ruby. Disponible également en version bêta pour Java.

autobuild : la base de données est créée en tentant de générer automatiquement la racine source. Disponible pour C/C++, C#, Go, Java/Kotlin et Swift.

manual : la base de données est créée en créant la racine source à l’aide d’une commande de build spécifiée manuellement. Disponible pour C/C++, C#, Go, Java/Kotlin et Swift.

Lors de la création d’une base de données avec --command, il n’est pas nécessaire de spécifier « --build-mode manual ».

Disponible depuis v2.16.4.

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

[Par défaut : .] Répertoire du code source racine. Dans de nombreux cas, il s’agit de la racine de l’extraction. Les fichiers qu’il contient sont considérés comme les fichiers sources principaux de cette base de données. Dans certains formats de sortie, les fichiers sont référencés par leur chemin relatif à partir de ce répertoire.

-j, --threads=<num>

Utilise le nombre de threads spécifié pour l’opération d’importation et le passe en tant qu’indicateur à toute commande de build appelée.

La valeur par défaut est de 1. Vous pouvez passer 0 pour utiliser un thread par cœur sur la machine ou -N pour laisser N cœurs inutilisés (sauf si au moins un thread est toujours utilisé).

-M, --ram=<MB>

Utilise la quantité de mémoire spécifiée pour l’opération d’importation et la passe en tant qu’indicateur à toute commande de build appelée.

-c, --command=<command>

Pour les langages compilés, commandes de build qui entraîneront l’appel du compilateur sur le code source à analyser. Ces commandes seront exécutées dans un environnement d’instrumentation qui permet l’analyse du code généré et (dans certains cas) des bibliothèques standard.

Si aucune commande de build n’est spécifiée, la commande tente de déterminer automatiquement comment générer l’arborescence source, en fonction de l’heuristique du pack de langage sélectionné.

Notez que certaines combinaisons de plusieurs langages nécessitent la spécification d’une commande de build explicite.

--no-cleanup

[Avancé] Supprime tout le nettoyage de la base de données après la finalisation. Utile à des fins de débogage.

--no-pre-finalize

[Avancé] Ignore tout script de pré-finalisation spécifié par l’extracteur CodeQL actif.

--[no-]skip-empty

[Avancé] Génère un avertissement au lieu d’échouer si une base de données est vide parce qu’aucun code source n’a été vu pendant la génération. La base de données vide reste non finalisée.

--[no-]linkage-aware-import

[Avancé] Contrôle si l’importation de jeu de données codeql prend en compte les liaisons (par défaut) ou non. Sur les projets dans lesquels cette partie de la création de base de données consomme trop de mémoire, la désactivation de cette option peut les aider à progresser au détriment de la complétion de la base de données.

Disponible depuis v2.15.3.

Options de calcul de la ligne de base

--[no-]calculate-baseline

[Avancé] Calcule les informations de ligne de base sur le code en cours d’analyse et les ajoute à la base de données. Par défaut, cette option est activée, sauf si la racine source est la racine d’un système de fichiers. Cet indicateur peut être utilisé pour désactiver ou forcer l’activation du comportement, même à la racine du système de fichiers.

--[no-]sublanguage-file-coverage

[GitHub.com et GitHub Enterprise Server v3.12.0+ uniquement] Utilisez les informations de couverture des fichiers de sous-langage. Cela permet de calculer, d’afficher et d’exporter des informations de couverture de fichiers distinctes pour les langages qui partagent un extracteur CodeQL comme C et C++, Java et Kotlin, et JavaScript et TypeScript.

Disponible depuis v2.15.2.

Options de sélection de l’extracteur

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

Liste des répertoires sous lesquels les packs d’extracteur peuvent être trouvés. Les répertoires peuvent être les packs d’extracteur eux-mêmes ou les répertoires qui contiennent les extracteurs en tant que sous-répertoires immédiats.

Si le chemin contient plusieurs arborescences de répertoires, leur ordre définit la priorité entre elles : si le langage cible est mis en correspondance dans plusieurs arborescences de répertoires, celle donnée en premier gagne.

Les extracteurs en bundle avec la chaîne d’outils CodeQL elle-même sont toujours trouvés, mais si vous devez utiliser des extracteurs distribués séparément, vous devez donner cette option (ou, mieux encore, configurer --search-path dans un fichier de configuration par utilisateur).

(Remarque : Sur Windows, le séparateur de chemin est ;.)

Options pour configurer l’appel de l’API GitHub visant à détecter automatiquement les langages.

-a, --github-auth-stdin

Accepte un jeton GitHub Apps ou un jeton d’accès personnel via une entrée standard.

Cela remplace la variable d’environnement GITHUB_TOKEN.

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

URL de l’instance GitHub à utiliser. Si elle est omise, l’interface CLI tente de la détecter automatiquement à partir du chemin d’extraction et, si cela n’est pas possible, la valeur par défaut est https://github.com/

Options pour configurer le gestionnaire de package.

--registries-auth-stdin

Permet de vous authentifier auprès des registres de conteneurs GitHub Enterprise Server en passant une liste de paires <registry_url>=<token> séparées par des virgules.

Par exemple, vous pouvez passer https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 pour vous authentifier auprès de deux instances GitHub Enterprise Server.

Cela remplace les variables d’environnement CODEQL_REGISTRIES_AUTH et GITHUB_TOKEN. Si vous avez seulement besoin de vous authentifier auprès du registre de conteneurs github.com, vous pouvez vous authentifier en utilisant l’option plus simple --github-auth-stdin.

Options de nettoyage de jeu de données de bas niveau

--max-disk-cache=<MB>

Définit la quantité maximale d’espace que le cache de disque peut utiliser pour les résultats de requête intermédiaires.

Si cette taille n’est pas configurée explicitement, l’évaluateur essaie d’utiliser une quantité « raisonnable » d’espace de cache en fonction de la taille du jeu de données et de la complexité des requêtes. La définition explicite d’une limite supérieure à cette utilisation par défaut permet une mise en cache supplémentaire qui peut accélérer les requêtes ultérieures.

--min-disk-free=<MB>

[Avancé] Définit la quantité cible d’espace disponible sur le système de fichiers.

Si --max-disk-cache n’est pas donné, l’évaluateur s’efforce de limiter l’utilisation du cache de disque si l’espace disponible sur le système de fichiers passe en dessous de cette valeur.

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

[Avancé] Définit la fraction cible d’espace disponible sur le système de fichiers.

Si --max-disk-cache n’est pas donné, l’évaluateur s’efforce de limiter l’utilisation du cache de disque si l’espace disponible sur le système de fichiers passe en dessous de ce pourcentage.

-m, --mode=<mode>

Sélectionnez le degré de réduction du cache. Les options sont les suivantes :

clear:  Supprime l’intégralité du cache, en le réduisant à l’état d’un jeu de données qui vient d’être extrait

trim (par défaut)  : Supprime tout, sauf les prédicats explicitement « mis en cache ».

fit : S’assure simplement que les limites de taille définies pour le cache de disque sont respectées, en supprimant autant d’intermédiaires que nécessaire.

--cleanup-upgrade-backups

Supprime tous les répertoires de sauvegarde résultant des mises à niveau des bases de données.

Options de suivi

--no-tracing

[Avancé] Ne trace pas la commande spécifiée, mais l’utilise pour produire directement toutes les données nécessaires.

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

[Avancé] Chemin du fichier de configuration d’un traceur. Il peut être utilisé pour modifier le comportement du traceur de build. Il peut être utilisé pour sélectionner les processus du compilateur qui s’exécutent dans le cadre de la commande de build et déclencher l’exécution d’autres outils. Les extracteurs fournissent des fichiers de configuration de traceur par défaut qui devraient fonctionner dans la plupart des cas.

Options de personnalisation des commandes de build

--working-dir=<dir>

[Avancé] Répertoire dans lequel la commande spécifiée doit être exécutée. Si cet argument n’est pas fourni, la commande est exécutée dans la valeur de --source-root passée à codeql database create, le cas échéant. Si aucun argument --source-root n’est fourni, la commande est exécutée dans le répertoire de travail actif.

--no-run-unnecessary-builds

[Avancé] Exécute la ou les commandes de build spécifiées seulement si une base de données en cours de construction utilise un extracteur qui dépend du traçage d’un processus de build. Si cette option n’est pas donnée, la commande est exécutée même si CodeQL n’en a pas besoin, en supposant que vous ayez besoin de ses effets secondaires pour d’autres raisons.

Options pour contrôler le comportement des extracteurs

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

Définit les options pour les extracteurs CodeQL. extractor-option-name doit être de la forme extracteur_nom.groupe1.groupe2.option_nom ou groupe1.groupe2.option_nom. Si extractor_option_name commence par un nom d’extracteur, l’extracteur indiqué doit déclarer l’option groupe1.groupe2.option_nom. Sinon, tout extracteur qui déclare l’option groupe1.groupe2.option_nom aura l’option définie. value peut être n’importe quelle chaîne qui ne contient pas de nouvelle ligne.

Vous pouvez utiliser cette option de ligne de commande à plusieurs reprises pour définir plusieurs options d’extracteur. Si vous fournissez plusieurs valeurs pour la même option d’extracteur, le comportement dépend du type attendu par l’option d’extracteur. Les options de chaîne utilisent la dernière valeur fournie. Les options de tableau utilisent toutes les valeurs fournies, dans l’ordre. Les options d’extracteur spécifiées à l’aide de cette option de ligne de commande sont traitées après les options d’extracteur fournies via --extractor-options-file.

Lorsqu’elles sont passées à codeql database init ou codeql database begin-tracing, les options sont appliquées uniquement à l’environnement de traçage indirect. Si votre workflow effectue également des appels à codeql database trace-command, les options doivent également y être passées si vous le souhaitez.

Consultez https://codeql.github.com/docs/codeql-cli/extractor-options pour plus d’informations sur les options d’extracteur CodeQL, notamment sur la façon de lister les options déclarées par chaque extracteur.

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

Spécifie les fichiers de bundle d’options d’extracteur. Un fichier bundle d’options d’extracteur est un fichier JSON (extension .json) ou un fichier YAML (extension .yaml ou .yml) qui définit les options de l’extracteur. Le fichier doit avoir la clé de mappage de niveau supérieur « extractor » et, dessous, les noms d’extracteur en tant que clés de mappage de deuxième niveau. Les autres niveaux de mappage représentent les groupes d’extracteurs imbriqués, et les options de chaîne et de tableau sont des entrées de mappage avec des valeurs de chaîne et de tableau.

Les fichiers de bundle d’options d’extracteur sont lus dans l’ordre dans lequel ils sont spécifiés. Si des fichiers de bundle d’options d’extracteur différents spécifient la même option d’extracteur, le comportement dépend du type attendu par l’option d’extracteur. Les options de chaîne utilisent la dernière valeur fournie. Les options de tableau utilisent toutes les valeurs fournies, dans l’ordre. Les options d’extracteur spécifiées à l’aide de cette option de ligne de commande sont traitées avant les options d’extracteur fournies via --extractor-option.

Lorsqu’elles sont passées à codeql database init ou codeql database begin-tracing, les options sont appliquées uniquement à l’environnement de traçage indirect. Si votre workflow effectue également des appels à codeql database trace-command, les options doivent également y être passées si vous le souhaitez.

Consultez https://codeql.github.com/docs/codeql-cli/extractor-options pour plus d’informations sur les options d’extracteur CodeQL, notamment sur la façon de lister les options déclarées par chaque extracteur.

Options courantes

-h, --help

Affiche ce texte d’aide.

-J=<opt>

[Avancé] Donne une option à l’environnement JVM exécutant la commande.

(Attention, les options contenant des espaces ne sont pas gérées correctement.)

-v, --verbose

Augmente de façon incrémentielle le nombre de messages de progression affichés.

-q, --quiet

Diminue de façon incrémentielle le nombre de messages de progression affichés.

--verbosity=<level>

[Avancé] Définit explicitement le niveau de détail sur errors, warnings, progress, progress+, progress++ ou progress+++. Remplace -v et -q.

--logdir=<dir>

[Avancé] Écrit des journaux détaillés dans un ou plusieurs fichiers du répertoire donné, avec des noms générés qui incluent des horodatages et le nom de la sous-commande en cours d’exécution.

(Pour écrire un fichier journal avec un nom sur lequel vous avez un contrôle total, donnez plutôt --log-to-stderr et redirigez stderr comme vous le souhaitez.)

--common-caches=<dir>

[Avancé] Contrôle l’emplacement des données en cache sur le disque qui persisteront entre plusieurs exécutions de l’interface CLI, telles que les packs QL téléchargés et les plans de requête compilés. S’il n’est pas défini explicitement, il s’agit par défaut d’un répertoire nommé .codeql dans le répertoire de base de l’utilisateur. S’il n’existe pas déjà, il est créé.

Disponible depuis v2.15.2.