对编译语言进行 CodeQL 代码扫描

关于 CodeQL 分析工作流程和编译语言

Code scanning 的工作原理是针对一个或多个数据库运行查询。每个数据库都包含仓库中所有代码的单一语言表示形式。对于编译语言 C/C++、C#、 Go、 Java 以及 Swift，填充此数据库的过程涉及生成代码和提取数据。

CodeQL 分析存储库中生成的 C/C++、C#、 Go、 Java 以及 Swift 源文件。

如果启用默认设置，autobuild 操作将用于生成代码，作为自动配置的 CodeQL 分析工作流程的一部分。如果启用高级设置，则基本 CodeQL 分析工作流程将使用 autobuild。或者，可以禁用 autobuild 并改为指定显式生成命令，以仅分析这些自定义命令生成的文件。

对于 CodeQL code scanning，可以使用默认设置来分析代码并自动配置 code scanning，也可以使用高级设置来生成你可以编辑的工作流文件。有关高级设置的详细信息，请参阅“配置代码扫描的高级设置”。

有关最新版本的 CodeQL 中支持的语言、库和框架的信息，请参阅 CodeQL 文档中的“支持的语言和框架”。有关运行最新版本 CodeQL 的系统要求信息，请参阅 CodeQL 文档中的“系统要求”。

如果你的工作流使用 language 矩阵，autobuild 会尝试生成矩阵中列出的每种编译语言。如果不使用矩阵，则 autobuild 会尝试生成在存储库中具有最多源文件的受支持编译语言。除 Go 以外，除非您提供明确的构建命令，否则您仓库中其他编译语言的分析将失败。

关于用于 CodeQL 的 `autobuild`

CodeQL 分析存储库中生成的 C/C++、C#、 Go、 Java 以及 Swift 源文件。

如果启用默认设置，autobuild 操作将用于生成代码，作为自动配置的 CodeQL 分析工作流程的一部分。如果启用高级设置，则基本 CodeQL 分析工作流程将使用 autobuild。或者，可以禁用 autobuild 并改为指定显式生成命令，以仅分析这些自定义命令生成的文件。

适用于 C/C++ 的autobuild
适用于 C# 的 autobuild
Go 的 autobuild
适用于 Java 和 Kotlin 的 autobuild
适用于 Swift 的 autobuild

注意：如果使用 GitHub Actions 的自承载运行器，则可能需要安装其他软件才能使用 autobuild 进程。此外，如果您的仓库需要特定版本的构建工具，您可能需要手动安装它。 GitHub 托管运行器始终运行 autobuild 所需的软件。

适用于 C/C++ 的 `autobuild`

支持的系统类型	系统名称
操作系统	Windows、macOS 和 Linux
构建系统	Windows：MSbuild 和生成脚本 Linux 和 macOS：Autoconf、Make、CMake、qmake、Meson、Waf、SCons、Linux Kbuild 和生成脚本

autobuild 步骤的行为因运行提取的操作系统而异。在 Windows 上，autobuild 步骤尝试使用以下方法自动检测适合 C/C++ 的生成方法：

对离根最近的解决方案 (.sln) 或项目 (.vcxproj) 文件调用 MSBuild.exe。如果 autobuild 在顶层目录下的相同（最短）深度检测到多个解决方案或项目文件，它将尝试生成所有这些文件。
调用看起来像生成脚本的脚本：build.bat、build.cmd 和 build.exe（按此顺序）。

在 Linux 和 macOS 上，autobuild 步骤检查存储库中存在的文件，以确定使用的生成系统：

在根目录中查找构建系统。
如果未找到，则搜索子目录以查找含有 C/C++ 构建系统的唯一目录。
运行适当的命令来配置系统。

对于自托管运行器，可能需要安装 gcc 编译器，并且特定项目可能还需要访问 clang 或 mscv 可执行的文件。还需要安装项目所依赖的生成系统（例如 msbuild、make、cmake、bazel）和实用工具（例如 python、perl、lex 和 yacc）。

适用于 C# 的 `autobuild`

支持的系统类型	系统名称
操作系统	Windows、macOS 和 Linux
构建系统	.NET 和 MSbuild，以及构建脚本

autobuild 进程尝试使用以下方法自动检测适合 C# 的构建方法：

对离根最近的解决方案 (.sln) 或项目 (.csproj) 文件调用 dotnet build。
对离根最近的解决方案或项目文件调用 MSbuild (Linux) 或 MSBuild.exe (Windows)。如果 autobuild 在顶层目录下的相同（最短）深度检测到多个解决方案或项目文件，它将尝试生成所有这些文件。
调用看起来像生成脚本的脚本：build 和 build.sh（对于 Linux，按此顺序）或 build.bat、build.cmd 和 build.exe（对于 Windows，按此顺序）。

对于自托管运行器上的 .NET Core 应用程序开发，需要 .NET SDK（适用于 dotnet）。

对于 .NET Framework 应用程序开发，在 Windows 上需要 Microsoft 生成工具（适用于 msbuild）和 Nuget CLI（适用于 nuget）。在 Linux 和 macOS 上，需要 Mono 运行时（来运行 mono、msbuild 或 nuget）。

适用于 Go 的 `autobuild`

支持的系统类型	系统名称
操作系统	Windows、macOS 和 Linux
构建系统	Go 模块、`dep` 和 Glide，以及生成脚本，包括 Makefiles 和 Ninja 脚本

autobuild 过程尝试在提取所有 .go 文件之前自动检测安装 Go 存储库所需的依赖项的合适方法：

调用 make、ninja、./build 或 ./build.sh（按该顺序），直到其中一个命令成功，后续 go list ./... 也成功，这表示已安装所需的依赖项。
如果这些命令都没有成功，请查找 go.mod、Gopkg.toml 或 glide.yaml，并分别运行 go get（除非正在使用供应商）、dep ensure -v 或 glide install 以尝试安装依赖项。
最后，如果未找到这些依赖项管理器的配置文件，请重新排列适合添加到 GOPATH 的存储库目录结构，并使用 go get 安装依赖项。提取完成后，目录结构恢复为正常。
提取存储库中的所有 Go 代码，类似于运行 go build ./...。

注意： 如果使用默认设置，将查找 go.mod 文件以自动安装兼容版本的 Go 语言。

适用于 Java 和 Kotlin 的 `autobuild`

支持的系统类型	系统名称
操作系统	Windows、macOS 和 Linux（无限制）
构建系统	Gradle、Maven 和 Ant

autobuild 进程尝试通过应用此策略来确定 Java 代码库的生成系统：

在根目录中搜索构建文件。先后检查 Gradle、Maven 和 Ant 构建文件。
运行找到的第一个构建文件。如果 Gradle 和 Maven 文件都存在，则使用 Gradle 文件。
否则，在根目录的直接子目录中搜索构建文件。如果只有一个子目录包含构建文件，则运行该子目录中标识的第一个文件（使用与 1 相同的首选项）。如果多个子目录包含构建文件，则报告错误。

如果使用的是自托管运行器，则应提供所需的 Java 版本：

如果运行器用于分析需要单一版本 Java 的存储库，则需要安装相应的 JDK 版本，并需要将其放在 PATH 变量中（以便找到 java 和 javac）。
如果运行器用于分析需要多个版本 Java 的存储库，则需要安装相应的 JDK 版本，并且可以通过 toolchains.xml 文件指定。这是 Apache Maven 通常使用的配置文件，该文件允许指定工具的位置、工具的版本以及使用这些工具所需的任何其他配置。有关详细信息，请参阅 Apache Maven 文档中的“工具链使用指南”。

以下可执行文件可能是一系列 Java 项目所必需的，并且应该存在于 PATH 变量中，但并非在所有情况下都是必需的：

mvn (Apache Maven)
gradle (Gradle)
ant (Apache Ant)

还需要安装项目所依赖的生成系统（例如 make、cmake、bazel）和实用工具（例如 python、perl、lex 和 yacc）。

适用于 Swift 的 `autobuild`

支持的系统类型	系统名称
操作系统	macOS
构建系统	Xcode

autobuild 进程尝试从 Xcode 项目或工作区生成最大目标。

注意：

用于 Swift 的 CodeQL 分析目前为 beta 版。在 Beta 版中，Swift 代码的分析以及随附文档不会像其他语言那样全面。尚不支持 Swift 5.8。
分析有时可能会冻结，导致作业超时。若要限制停滞或超时作业所使用的操作分钟数，建议将超时设置为正常生成时间的四倍。

Swift 代码扫描默认使用 macOS 运行器。由于 GitHub 托管的 macOS 运行器比 Linux 和 Windows 运行器更昂贵，因此建议仅生成要分析的代码。有关 GitHub 托管的运行器定价的详细信息，请参阅“关于 GitHub Actions 的计费”。

作为 Actions Runner Controller (ARC) 一部分的运行器不支持对 Swift 代码进行代码扫描，但你可以混合使用 ARC 运行器和自托管的 macOS 运行器。有关详细信息，请参阅“关于 Actions Runner Controller”。

在 CodeQL 分析工作流程中自定义 Swift 编译

xcodebuild 和 swift build 都支持 Swift 内部版本。我们建议在生成期间仅锁定一个体系结构。例如，对于 xcodebuild，则为 ARCH=arm64，或对于 swift build，则为 --arch arm64。

可以将 archive 和 test 选项传递给 xcodebuild。但是，建议使用标准 xcodebuild 命令，因为它应该是最快的命令，并且应该是 CodeQL 成功扫描所需的全部命令。

对于 Swift 分析，在生成 CodeQL 数据库之前，必须始终显式安装通过 CocoaPod 或 Carthage 管理的依赖项。

添加编译语言的构建步骤

如果 autobuild 失败，或者你想要分析与 autobuild 进程生成的源文件不同的一组源文件，则需要从工作流中删除 autobuild 步骤，并手动添加生成步骤。对于 C/C++、C#、Go、 Kotlin、Java、Swift 项目 CodeQL 将分析由指定的生成步骤生成的任何源代码。有关如何编辑工作流文件的信息，请参阅“自定义代码扫描的高级设置”。

删除 autobuild 步骤后，取消注释 run 步骤并添加适合存储库的生成命令。工作流 run 步骤会使用操作系统的 shell 来运行命令行程序。可以修改这些命令并添加更多命令以自定义生成过程。

- run: |
    make bootstrap
    make release

要详细了解 run 密钥，请参阅“GitHub Actions 的工作流语法”。

如果存储库包含多个编译语言，可以指定特定于语言的生成命令。例如，如果存储库包含 C/C++、C# 和 Java，而 autobuild 正确生成了 C/C++ 和 C#，但未能生成 Java，那么在 init 步骤之后，可以在工作流中使用以下配置。这指定了 Java 的生成步骤，同时仍然为 C/C++ 和 C# 使用 autobuild：

- if: matrix.language == 'cpp' || matrix.language == 'csharp'
  name: Autobuild
  uses: github/codeql-action/autobuild@v2

- if: matrix.language == 'java'
  name: Build Java
  run: |
    make bootstrap
    make release

有关 if 条件的详细信息，请参阅“GitHub Actions 的工作流语法”。

有关为什么 autobuild 不能生成代码的更多提示和技巧，请参阅“编译的语言的自动生成失败”。

如果您为编译语言添加了手动构建步骤，但 code scanning 仍然无法处理您的仓库，请联系 GitHub 支持。

对编译语言进行 CodeQL 代码扫描

本文内容