对编译语言进行 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 源文件。

适用于 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 代码的 Code scanning，因为 ARC 运行器仅使用 Linux，且 Swift 需要 macOS 运行器。但是，你可以混合使用 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 == 'c-cpp' || matrix.language == 'csharp'
  name: Autobuild
  uses: github/codeql-action/autobuild@v2
- if: matrix.language == 'java-kotlin'
  name: Build Java
  run: |
    make bootstrap
    make release

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

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

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

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

本文内容