query compile

注意

此内容描述了 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>...]`

[Advanced] 可选的目录列表，这些目录将被添加到 QL 库的原始导入搜索路径中。仅在使用尚未打包为 QL 包的 QL 库时才应使用。

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

`--dbscheme=<file>`

[Advanced] 明确指定应针对哪个 dbscheme 查询进行编译。仅在调用者对自己的操作极其确定时才应提供此选项。

`--compilation-cache=<dir>`

[Advanced] 指定一个额外的目录，用作编译缓存。

`--no-default-compilation-cache`

[Advanced] 不使用标准位置（例如包含查询的 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 环境变量。

谁可以使用此功能？

本文内容