查询编译

此内容描述了 CodeQL CLI 的最新版本。有关此版本的更多信息，请参阅 https://github.com/github/codeql-cli-binaries/releases。

要在早期版本中查看此命令可用选项的详细信息，请在终端中使用 --help 选项运行该命令。

概要

Shell

codeql query compile [--check-only] [--keep-going] [--threads=<num>] [--ram=<MB>] <options>... -- <file>...

codeql query compile [--check-only] [--keep-going] [--threads=<num>] [--ram=<MB>] <options>... -- <file>...

描述

编译或检查 QL 代码。

编译一个或多个查询。通常，此命令的主要结果是查询的编译版本被写入编译缓存，稍后执行查询时会在其中找到它。其他输出选项主要用于调试。

选项

主要选项

`<file>...`

[必填] 要编译的查询。每个参数都是以下之一：

要编译的 .ql 文件。
一个将被递归搜索以查找 .ql 文件的目录。
一个定义特定查询集的 .qls 文件。
已安装 QL 包之一导出的“众所周知” .qls 文件的基名。

`-n, --check-only`

仅检查 QL 是否有效并打印任何错误；不实际优化和存储查询计划。这可能比完整的编译速度快得多。

`--[no-]precompile`

【高级】将每个已编译的查询作为二进制 .qlx 文件保存在 .ql 源文件旁边。

这仅在准备用于分发的查询包时才使用（在这种情况下，它会被 codeql pack publish 自动使用）。一旦 .qlx 文件存在，以后执行查询的命令可能会忽略对 QL 源代码的更改，而倾向于使用预编译版本。

一些很少使用的编译选项与该选项不兼容，会导致运行时错误。

自 v2.12.0 版本起可用。

`--[no-]dump-dil`

【高级】在编译时将优化的 DIL 中间表示打印到标准输出。

当选择 JSON 输出时，DIL 将表示为单行字符串数组，并进行一些包装以标识正在编译哪个查询。

`-k, --[no-]keep-going`

即使发现错误，也要继续编译。

`--[no-]dump-ra`

【高级】在编译时将优化的 RA 查询计划打印到标准输出。

当选择 JSON 输出时，RA 将表示为单行字符串数组，并进行一些包装以标识正在编译哪个查询。

`--format=<fmt>`

选择输出格式，text（默认）或 json。

`-j, --threads=<num>`

使用这么多线程来编译查询。

默认为 1。您可以传递 0 来为机器上的每个核心使用一个线程，或者传递 -N 来保留 N 个核心未使用（但仍然至少使用一个线程）。

`-M, --ram=<MB>`

设置编译器允许使用的 RAM 总量。

QL 变体和编译器控制选项

`--warnings=<mode>`

如何处理 QL 编译器的警告。其中之一：

hide：抑制警告。

show（默认）：打印警告，但继续编译。

error：将警告视为错误。

`--no-debug-info`

不要在 RA 中为调试发出源位置信息。

`--[no-]fast-compilation`

【已弃用】【高级】省略特别慢的优化步骤。

`--no-release-compatibility`

【高级】使用最新的编译器功能，但会降低可移植性。

有时，新的 QL 语言功能和评估器优化将在 QL 评估器中得到支持，时间比它们在 QL 编译器中默认启用早几个版本。这有助于确保您在使用最新 CodeQL 版本开发查询时所体验到的性能可以与可能仍在用于代码扫描或 CI 集成的稍旧版本相匹配。

如果您不关心您的查询是否与其他（较早或较晚的）CodeQL 版本兼容，您可以通过使用此标志尽早启用编译器中的最新改进，有时可以获得少量额外的性能提升。

在没有最新改进可启用的版本中，此选项会静默地不做任何操作。因此，在您的全局 CodeQL 配置文件中设置它一次就足够安全了。

自 v2.11.1 版本起可用。

`--[no-]local-checking`

仅对使用的 QL 源代码部分执行初始检查。

`--no-metadata-verification`

不检查 QLDoc 注释中嵌入的查询元数据是否有效。

`--compilation-cache-size=<MB>`

【高级】覆盖编译缓存目录的默认最大大小。

`--fail-on-ambiguous-relation-name`

【高级】如果在编译期间生成了不明确的关系名称，则编译失败。

设置编译环境的选项

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

可以找到 QL 包的目录列表。每个目录都可以是 QL 包（或包含根目录中 .codeqlmanifest.json 文件的包捆绑包），也可以是多个此类目录的直接父目录。

如果路径包含多个目录，则它们的顺序定义它们之间的优先级：当必须解析的包名称在多个目录树中匹配时，首先给出的目录优先。

指向开源 CodeQL 存储库的签出应该在查询其中一个语言时有效。

如果您已将 CodeQL 存储库签出为解压缩的 CodeQL 工具链的同级目录，则无需提供此选项；此类同级目录将始终搜索无法找到的 QL 包。（如果此默认值无效，强烈建议在每个用户的配置文件中设置 --search-path 一次。）

（注意：在 Windows 上，路径分隔符是 ;）。

`--additional-packs=<dir>[:<dir>...]`

如果给出了此目录列表，则会在 --search-path 中的包之前搜索这些目录中的包。这些之间的顺序无关紧要；如果通过此列表在两个不同位置找到包名称，则为错误。

如果您暂时正在开发也出现在默认路径中的新版本包，这将很有用。另一方面，*不建议*在配置文件中覆盖此选项；某些内部操作会动态添加此选项，覆盖任何已配置的值。

（注意：在 Windows 上，路径分隔符是 ;）。

`--library-path=<dir>[:<dir>...]`

【高级】一个可选的目录列表，将添加到 QL 库的原始导入搜索路径中。如果您使用的是未打包为 QL 包的 QL 库，则应仅使用此选项。

（注意：在 Windows 上，路径分隔符是 ;）。

`--dbscheme=<file>`

【高级】明确定义应针对其编译 dbscheme 查询。只有绝对确信自己在做什么的调用者才应提供此选项。

`--compilation-cache=<dir>`

【高级】指定要用作编译缓存的附加目录。

`--no-default-compilation-cache`

【高级】不要使用标准位置中的编译缓存，例如包含查询的 QL 包或 CodeQL 工具链目录中。

配置 CodeQL 包管理器的选项

`--registries-auth-stdin`

通过传递逗号分隔的 <registry_url>=<token> 对列表来向 GitHub Enterprise Server 容器注册表进行身份验证。

例如，您可以传递 https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 来向两个 GitHub Enterprise Server 实例进行身份验证。

这会覆盖 CODEQL_REGISTRIES_AUTH 和 GITHUB_TOKEN 环境变量。如果您只需要向 github.com 容器注册表进行身份验证，则可以使用更简单的 --github-auth-stdin 选项进行身份验证。

`--github-auth-stdin`

通过通过标准输入传递 github.com GitHub Apps 令牌或个人访问令牌来向 github.com 容器注册表进行身份验证。

要向 GitHub Enterprise Server 容器注册表进行身份验证，请传递 --registries-auth-stdin 或使用 CODEQL_REGISTRIES_AUTH 环境变量。

这会覆盖 GITHUB_TOKEN 环境变量。

谁可以使用此功能？

本文内容