database trace-command

Synopsis

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

Description

[Plomberie] Exécute une seule commande dans le cadre d’une build tracée.

Cette commande exécute une seule ligne de commande donnée sous un traceur, donc effectue éventuellement une extraction, mais ne finalise pas la base de données CodeQL résultante.

Options

Options principales

<database>

[Obligatoire] Chemin de la base de données CodeQL en cours de construction. Doit avoir été préparé pour l’extraction avec codeql database init.

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 contient des bases de données, et toutes ces bases de données sont traitées ensemble.

<command>...

Commande à exécuter. Peut se composer d’un ou plusieurs arguments qui sont utilisés pour créer le processus. Il est recommandé de passer l’argument « -- » avant de lister les arguments de la commande afin d’éviter toute confusion entre ses arguments et les nôtres.

La commande doit quitter avec un code d’état de 0. Tout autre code de sortie est interprété comme un échec.

La commande peut être omise quand --index-traceless-dbs est fourni.

-j, --threads=<num>

Demande à l’extracteur d’utiliser le nombre de threads spécifié. Cette option est passée à l’extracteur en tant que suggestion. Si la variable d’environnement CODEQL_THREADS est définie, la valeur de la variable d’environnement est prioritaire sur cette option.

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>

Demande à l’extracteur d’utiliser la quantité de mémoire spécifiée. Cette option est passée à l’extracteur en tant que suggestion. Si la variable d’environnement CODEQL_RAM est définie, la valeur de la variable d’environnement est prioritaire sur cette option.

--[no-]db-cluster

Indique que le répertoire donné sur la ligne de commande n’est pas la base de données elle-même, mais un répertoire qui contient une ou plusieurs bases de données en cours de construction. Ces bases de données sont traitées ensemble.

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

--[no-]index-traceless-dbs

En plus de la commande spécifiée, exécutez le script principal pour les extracteurs qui ne dépendent pas du traçage d’un processus de build. Si vous construisez des bases de données pour plusieurs langages avec --db-cluster, cette option doit être fournie à exactement un appel de codeql database trace-command.

--[no-]use-build-mode

Déterminez ce qu’il faut exécuter en fonction du mode de génération de la base de données. Cette option ne peut pas être utilisée avec --index-traceless-dbs.

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