database init

Synopsis

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

Description

[Plomberie] Crée une base de données CodeQL vide.

Crée une structure squelette pour une base de données CodeQL qui n’a pas encore de jeu de données QL brut, mais qui est prête pour exécuter les étapes de l’extracteur. Une fois cette commande terminée, exécute une ou plusieurs commandes codeql database trace-command suivies de codeql database finalize pour préparer la base de données à être interrogée.

(Une partie de ce qu’elle fait consiste à résoudre l’emplacement du pack de langages approprié et à le stocker dans les métadonnées de la base de données, afin de ne pas avoir à le refaire à chaque commande d’extraction. Il n’est pas valide de toute façon de changer d’extracteurs au milieu d’une opération d’extraction.)

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

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

[Obligatoire] 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.

--[no-]overwrite

[Avancé] Si la base de données existe déjà, elle la supprime et poursuit avec cette commande au lieu d’échouer. Si le répertoire existe, mais qu’il ne ressemble pas à une base de données, une erreur est levée.

--[no-]force-overwrite

[Avancé] Si la base de données existe déjà, la supprimer même si elle ne ressemble pas à une base de données et poursuivre 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 de 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 C#, Java, JavaScript/TypeScript, Python et Ruby.

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.

--[no-]allow-missing-source-root

[Avancé] Continue même si la racine source spécifiée n’existe pas.

--[no-]begin-tracing

[Avancé] Crée des scripts qui peuvent être utilisés pour configurer le « traçage de build indirect », qui permet une intégration aux workflows de build existants lorsqu’une commande de build explicite n’est pas disponible. Pour savoir quand et comment utiliser cette fonctionnalité, reportez-vous à notre documentation sur Préparation de votre code pour l’analyse CodeQL.

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 configuration du suivi Windows

--trace-process-name=<process-name>

[Windows uniquement] Lors de l’initialisation du traçage, injectez le traceur dans un processus parent de l’interface CLI de CodeQL dont le nom correspond à cet argument. Si plusieurs processus parents ont ce nom, le processus le plus bas de l’arborescence de processus est sélectionné. Cette option remplace --trace-process-level, donc si les deux sont passées, seule cette option sera utilisée.

--trace-process-level=<process-level>

[Windows uniquement] Lors de l’initialisation du traçage, injecte le traceur au nombre spécifié de parents au-dessus du processus actuel, avec 0 correspondant au processus qui appelle l’interface CLI de CodeQL. Le comportement par défaut de l’interface CLI si aucun argument n’est passé consiste à injecter dans le parent du processus appelant, avec certains cas spéciaux pour GitHub Actions et Azure Pipelines.

Options pour configurer le traçage de build indirect

--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 pour contrôler le comportement des extracteurs : à appliquer uniquement à l’environnement de traçage indirect

-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 transmises à codeql database init ou codeql database begin-tracing, les options seront uniquement appliquées à 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 transmises à codeql database init ou codeql database begin-tracing, les options seront uniquement appliquées à 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.