数据库跟踪命令

概要

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

描述

[管道] 在跟踪构建过程中运行单个命令。

这会在跟踪程序下运行单个给定的命令行，从而可能执行一些提取操作，但不会完成生成的 CodeQL 数据库。

选项

主要选项

<database>

[必填] 正在构建的 CodeQL 数据库的路径。这必须已使用 codeql database init 准备好进行提取。

如果给出了 --db-cluster 选项，则这不是数据库本身，而是一个包含数据库的目录，并且所有这些数据库将一起处理。

<command>...

要运行的命令。这可能包含一个或多个参数，这些参数用于创建进程。建议在列出命令的参数之前传递“--”参数，以避免其参数与我们的参数混淆。

预期命令以状态代码 0 退出。任何其他退出代码都解释为失败。

当给出 --index-traceless-dbs 时，可以省略命令。

-j, --threads=<num>

要求提取器使用这么多线程。此选项作为建议传递给提取器。如果设置了 CODEQL_THREADS 环境变量，则环境变量值优先于此选项。

您可以传递 0 以在机器上每个核心使用一个线程，或 -N 以保留N 个核心未使用（但仍至少使用一个线程）。

-M, --ram=<MB>

要求提取器使用这么多内存。此选项作为建议传递给提取器。如果设置了 CODEQL_RAM 环境变量，则环境变量值优先于此选项。

--[no-]db-cluster

指示命令行上给出的目录本身不是数据库，而是一个包含一个或多个正在构建的数据库的目录。这些数据库将一起处理。

--no-tracing

[高级] 不要跟踪指定的命令，而是依靠它直接生成所有必要的数据。

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

[高级] 跟踪器配置文件的路径。它可用于修改构建跟踪器的行为。它可用于挑选出作为构建命令一部分运行的编译器进程，并触发其他工具的执行。提取器将提供默认的跟踪器配置文件，这些文件应该适用于大多数情况。

--[no-]index-traceless-dbs

除了指定的命令之外，还为不依赖于跟踪构建过程的提取器运行主脚本。如果您使用 --db-cluster 为多种语言构建数据库，则应将此选项提供给 codeql database trace-command 的一个调用。

--[no-]use-build-mode

根据数据库的构建模式确定要运行的内容。此选项不能与 --index-traceless-dbs 结合使用。

--working-dir=<dir>

[高级] 应在其中执行指定命令的目录。如果未提供此参数，则命令将在传递给 codeql database create 的 --source-root 的值中执行（如果存在）。如果未提供 --source-root 参数，则命令将在当前工作目录中执行。

--no-run-unnecessary-builds

[高级] 仅当正在构建的数据库使用依赖于跟踪构建过程的提取器时，才运行指定的构建命令。如果未给出此选项，则即使 CodeQL 不需要它，也会执行该命令，假设您出于其他原因需要它的副作用。

控制提取器行为的选项

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

设置 CodeQL 提取器的选项。extractor-option-name 应采用 extractor_name.group1.group2.option_name 或 group1.group2.option_name 的形式。如果 extractor_option_name 以提取器名称开头，则指示的提取器必须声明选项 group1.group2.option_name。否则，任何声明选项 group1.group2.option_name 的提取器都将设置该选项。value 可以是任何不包含换行符的字符串。

您可以重复使用此命令行选项来设置多个提取器选项。如果您为同一个提取器选项提供多个值，则行为取决于提取器选项期望的类型。字符串选项将使用提供的最后一个值。数组选项将按顺序使用提供的所有值。使用此命令行选项指定的提取器选项在通过 --extractor-options-file 给出的提取器选项之后处理。

当传递给 codeql database init 或 codeql database begin-tracing 时，这些选项将仅应用于间接跟踪环境。如果您的工作流也对 codeql database trace-command 进行调用，则如果需要，也需要在那里传递这些选项。

有关 CodeQL 提取器选项的更多信息（包括如何列出每个提取器声明的选项），请参阅 https://codeql.github.com/docs/codeql-cli/extractor-options。

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

指定提取器选项包文件。提取器选项包文件是一个 JSON 文件（扩展名为 .json）或 YAML 文件（扩展名为 .yaml 或 .yml），用于设置提取器选项。该文件必须具有顶级映射键“extractor”，并在其下使用提取器名称作为二级映射键。更高级别的映射表示嵌套的提取器组，字符串和数组选项是具有字符串和数组值的映射条目。

提取器选项包文件按指定的顺序读取。如果不同的提取器选项包文件指定了相同的提取器选项，则行为取决于提取器选项期望的类型。字符串选项将使用提供的最后一个值。数组选项将按顺序使用所有提供的值。使用此命令行选项指定的提取器选项将在通过 --extractor-option 给出的提取器选项之前进行处理。

当传递给 codeql database init 或 codeql database begin-tracing 时，这些选项将仅应用于间接跟踪环境。如果您的工作流也对 codeql database trace-command 进行调用，则如果需要，也需要在那里传递这些选项。

有关 CodeQL 提取器选项的更多信息（包括如何列出每个提取器声明的选项），请参阅 https://codeql.github.com/docs/codeql-cli/extractor-options。

常用选项

-h, --help

显示此帮助文本。

-J=<opt>

[高级] 向运行命令的 JVM 提供选项。

（请注意，包含空格的选项将无法正确处理。）

-v, --verbose

逐步增加打印的进度消息数量。

-q, --quiet

逐步减少打印的进度消息数量。

--verbosity=<level>

[高级] 显式将详细程度级别设置为 errors、warnings、progress、progress+、progress++、progress+++ 之一。覆盖 -v 和 -q。

--logdir=<dir>

[高级] 将详细日志写入给定目录中的一个或多个文件中，生成的名称包括时间戳和正在运行的子命令的名称。

（要写入一个名称完全受您控制的日志文件，请改为提供 --log-to-stderr 并根据需要重定向 stderr。）

--common-caches=<dir>

[高级] 控制磁盘上缓存数据的存储位置，这些数据将在 CLI 的多次运行之间持久化，例如下载的 QL 包和编译的查询计划。如果未显式设置，则默认为用户主目录中名为 .codeql 的目录；如果该目录不存在，则会创建它。

自 v2.15.2 起可用。