CodeQL build options and steps for compiled languages

Learn how CodeQL builds compiled languages, including available build modes and language-specific autobuild behavior for C/C++, C#, Go, Java, Kotlin, Rust, and Swift.

Autobuild steps for compiled languages

GitHub-hosted runners are always run with the software required by autobuild. If you use self-hosted runners for GitHub Actions, you may need to install additional software to use the autobuild process. Additionally, if your repository requires a specific version of a build tool, you may need to install it manually.

Building C/C++

CodeQL supports build modes none, autobuild or manual for C/C++ code.

When you enable default setup for a repository that contains C/C++ code, the build mode is set to none automatically.

No build for C/C++

CodeQL will infer C/C++ compilation units through source file extensions. For each source file found, compilation flags and include paths are inferred by inspecting the codebase without the need for a working build command.

Accuracy of no build analysis for C/C++

Creating a CodeQL C/C++ database without a build may produce less accurate results than using autobuild or manual build steps in some cases; for example, if:

• The code depends heavily on custom macros/defines not available in existing headers
• The codebase has many external dependencies

You can ensure a more accurate analysis by taking the following steps:

• Place custom macros and defines in header files that are included in relevant source files
• Ensure external dependencies (headers) are available in system include directories or in the workspace
• Run the extraction on the target platform. For example, choose a Windows runner to analyze Windows projects to give access to platform specific headers and compilers

Autobuild summary for C/C++

The behavior of the autobuild step varies according to the operating system that the extraction runs on.

Windows autodetection

On Windows, the autobuild step attempts to autodetect a suitable build method for C/C++ using the following approach:

1. Invoke MSBuild.exe on the solution (.sln) or project (.vcxproj) file closest to the root.
   If autobuild detects multiple solution or project files at the same (shortest) depth from the top level directory, it will attempt to build all of them.
2. Invoke a script that looks like a build script—build.bat, build.cmd, and build.exe (in that order).

Linux and macOS autodetection

On Linux and macOS, the autobuild step reviews the files present in the repository to determine the build system used:

1. Look for a build system in the root directory.
2. If none are found, search subdirectories for a unique directory with a build system for C/C++.
3. Run an appropriate command to configure the system.

Runner requirements for C/C++

On Ubuntu Linux runners, autobuild may try to automatically install dependencies required by the detected configuration and build steps. By default, this behavior is enabled on GitHub-hosted runners and disabled on self-hosted runners. You can enable or disable this feature explicitly by setting CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES to true or false in the environment. For more information about defining environment variables, see Store information in variables.

For self-hosted runners, unless automatic installation of dependencies is enabled, you will likely need to install the gcc compiler, and specific projects may also require access to clang or msvc executables. You will also need to install the build system (for example msbuild, make, cmake, bazel) and utilities (such as python, perl, lex, and yacc) that your projects depend on.
If you enable automatic installation of dependencies, you must ensure that the runner is using Ubuntu and that it can run sudo apt-get without requiring a password.

Windows runners require powershell.exe to be on the PATH.

Building C#

CodeQL supports build modes none, autobuild or manual for C# code.

When you enable default setup for a repository that contains C# code, the build mode is set to none automatically.

No build for C#

CodeQL restores dependencies and generates a few additional source files, to give more accurate results, before creating a database from all the source files and dependencies.

Dependencies are restored using multiple heuristics and strategies. The following files are the primary source of information: *.csproj, *.sln, nuget.config, packages.config, global.json, and project.assets.json. If a private NuGet feed is defined for the organization, this is also used, see Code scanning default setup access to private registries and Determining whether code scanning default setup used any private registries.

The following generated source files are optional, but significantly increase the correctness of the CodeQL database:

• global generated using directives to handle the implicit using feature of MSbuild.
• ASP.NET core view files, .cshtml files are converted to .cs files.

The information from the dependency assembly names, generated source files, dependencies stored in private feeds, and the source files in the repository is compiled and used to create a CodeQL database.

Accuracy of no build analysis for C#

Creating a CodeQL database without building the full code relies on being able to restore dependencies and being able to compile together the source files in the repository. When there are problems restoring dependencies or compiling the source code, this can affect the accuracy of the CodeQL database and code scanning analysis results.

You can ensure a more accurate analysis by taking the following steps:

• Provide access to the public internet or ensure that access to a private NuGet feed is available, see Code scanning default setup access to private registries.
• Check whether the repository requires multiple versions of the same NuGet dependency. CodeQL can use only one version and usually chooses the newer version where there are multiple versions. This approach may not work for all repositories.
• Check whether multiple versions of .NET are referenced, for example, net48, net5.0, and netstandard1.6. CodeQL can use only one version and this may affect accuracy.
• Avoid colliding class names, otherwise this may cause missing method call targets, which has an impact on dataflow analysis.

Autobuild summary for C#

Windows autodetection

The autobuild process attempts to autodetect a suitable build method for C# using the following approach:

1. Invoke dotnet build on the solution (.sln) or project (.csproj) file closest to the root.
2. Invoke MSBuild.exe on the solution or project file closest to the root.
   If autobuild detects multiple solution or project files at the same (shortest) depth from the top level directory, it will attempt to build all of them.
3. Invoke a script that looks like a build script—build.bat, build.cmd, and build.exe (in that order).

Runner requirements for C# on Windows

For .NET Core application development on self-hosted runners, the .NET SDK is required (for dotnet).

For .NET Framework application development, you will need Microsoft Build Tools (for msbuild) and NuGet CLI (for nuget).

Windows runners require powershell.exe to be on the PATH.

If you plan to create CodeQL databases using build-mode: none, you also need to provide access to the public internet, or you must ensure that access to a private NuGet feed is available.

Linux and macOS autodetection

1. Invoke dotnet build on the solution (.sln) or project (.csproj) file closest to the root.
2. Invoke MSbuild on the solution or project file closest to the root.
   If autobuild detects multiple solution or project files at the same (shortest) depth from the top level directory, it will attempt to build all of them.
3. Invoke a script that looks like a build script—build and build.sh (in that order).

Runner requirements for C# on Linux and macOS

For .NET Core application development on self-hosted runners, the .NET SDK is required (for dotnet).

For .NET Framework application development, you will require Mono Runtime (to run mono, msbuild, or nuget).

If you plan to create CodeQL databases using build-mode: none, you also need to provide access to the public internet, or you must ensure that access to a private NuGet feed is available.

C# compiler flags injected by CodeQL for manual builds

The CodeQL tracer enables the extraction of all compiled languages by intercepting build processes and forwarding information to the relevant CodeQL language extractors. The tracer injects certain flags into the C# compiler invocation to ensure every component is built and included in the CodeQL database, which may cause your C# code to build in a different way to what you expect during CodeQL analysis.

/p:MvcBuildViews=true

When this option is set to true, the views in ASP.NET model-view-controller (MVC) projects are precompiled as part of the build process, which can help to catch errors and improve performance. The tracer injects this flag to make sure CodeQL finds and highlights security issues that may involve dataflow through the code generated from these views. For more information, see Adding a View to an MVC Application in Microsoft Learn.

/p:UseSharedCompilation=false

Setting this option to false disables the use of the shared compilation feature, which may result in slower build times. When /p:UseSharedCompilation=false is not specified, msbuild starts a compiler server process, and all the compilation will be done by that single process. However, the CodeQL tracer depends on inspecting the arguments of newly created processes.

/p:EmitCompilerGeneratedFiles=true

Setting this option to true will emit compiler-generated files during the build process. This option causes the compiler to generate additional source files that are used to support features such as improved regular expression support, serialization, and web application view generation. These generated artifacts are typically not written to disk by the compiler, but setting the option to true forces writing the files to disk, and so the extractor can process the files.

For some legacy projects, and projects that use .sqlproj files, you may see that the injected /p:EmitCompilerGeneratedFiles=true property causes unexpected issues with msbuild. For information about troubleshooting this, see C# compiler unexpectedly failing.

Building Go

CodeQL supports build modes autobuild or manual for Go code.

Autobuild summary for Go

Autodetection for Go

The autobuild process attempts to autodetect a suitable way to install the dependencies needed by a Go repository before extracting all .go files:

1. Invoke make, ninja, ./build or ./build.sh (in that order) until one of these commands succeeds and a subsequent go list ./... also succeeds, indicating that the needed dependencies have been installed.
2. If none of those commands succeeded, look for go.mod, Gopkg.toml or glide.yaml, and run go get (unless vendoring is in use), dep ensure -v or glide install respectively to try to install dependencies.
3. Finally, if configurations files for these dependency managers are not found, rearrange the repository directory structure suitable for addition to GOPATH, and use go get to install dependencies. The directory structure reverts to normal after extraction completes.
4. Extract all Go code in the repository, similar to running go build ./....

Extractor options for Go

By default, test code (code in files ending in _test.go) is not analyzed. You can override this with the option --extractor-option extract_tests=true when using the CodeQL CLI, or by setting the environment variable CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS to true.

Additionally, vendor directories are excluded from CodeQL Go analysis by default. You can override this by passing the --extractor-option extract_vendor_dirs=true option when using the CodeQL CLI, or by setting the environment variable CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS to true.

Building Java and Kotlin

CodeQL supports the following build modes.

• Java: none, autobuild, or manual
• Kotlin: autobuild or manual

When you first enable default setup for a repository, if only Java code is detected then the build mode is set to none. If Kotlin or a combination of Java and Kotlin code is detected, then the build mode is set to autobuild.

If you later add Kotlin code to a repository that uses the none build mode, CodeQL analysis reports a warning message explaining that Kotlin is not supported. You will need to disable default setup and re-enable it. When you re-enable default setup, the build mode will change to autobuild so that both languages can be analyzed. Alternatively, you can change to an advanced setup. For more information, see Warning: Detected X Kotlin files in your project that could not be processed without a build.

No build for Java

CodeQL will attempt to run Gradle or Maven to extract accurate dependency information (but not to invoke a build), before creating a database from all Java files present. Every root Maven or Gradle project file (a build script without any build script present in an ancestor directory) is queried for dependency information, and more recent dependency versions are preferred if there is a clash. For information about the runner requirements to run Maven or Gradle, see Runner requirements for Java.

If a private Maven registry is defined for the organization, this is also used, see Code scanning default setup access to private registries and Determining whether code scanning default setup used any private registries.

Accuracy of no build analysis for Java

Creating a CodeQL Java database without a build may produce less accurate results than using autobuild or manual build steps if:

• Gradle or Maven build scripts cannot be queried for dependency information, and dependency guesses (based on Java package names) are inaccurate.
• The repository normally generates code during the build process. This would be analyzed if you created the CodeQL database using a different mode.

You can ensure a more accurate analysis by taking the following steps:

• Provide access to the public internet or ensure that access to a private artifact repository is available, see Code scanning default setup access to private registries.
• Check whether the repository requires multiple versions of the same dependency. CodeQL can use only one version and usually chooses the newer version where there are multiple versions. This approach may not work for all repositories.
• Check whether more than one version of the JDK API is required by different source Java files. When multiple versions are seen, CodeQL will use the highest version required by any build script. This may mean that some files that require a lower version of the JDK will be partially analyzed. For example, if some files require JDK 8 but a JDK 17 requirement is found in one or more build scripts, CodeQL will use JDK 17. Any files that require JDK 8 and could not be built using JDK 17 will be partially analyzed.
• Avoid colliding class names (for example, multiple files defining org.myproject.Test), otherwise this may cause missing method call targets, which has an impact on dataflow analysis.

Autobuild summary for Java

Autodetection for Java

The autobuild process tries to determine the build system for Java codebases by applying this strategy:

1. Search for a build file in the root directory. Check for Gradle then Maven then Ant build files.
2. Run the first build file found. If both Gradle and Maven files are present, the Gradle file is used.
3. Otherwise, search for build files in direct subdirectories of the root directory. If only one subdirectory contains build files, run the first file identified in that subdirectory (using the same preference as for 1). If more than one subdirectory contains build files, report an error.

Runner requirements for Java

If you're using self-hosted runners, the required version(s) of Java should be present:

• If the runner will be used for analyzing repositories that need a single version of Java, then the appropriate JDK version needs to be installed, and needs to be present in the PATH variable (so that java and javac can be found).

• If the runner will be used for analyzing repositories that need multiple versions of Java, then the appropriate JDK versions need to be installed, and can be specified via the toolchains.xml file. This is a configuration file, typically used by Apache Maven, that allows you to specify the location of the tools, the version of the tools, and any additional configuration that is required to use the tools. For more information, see Guide to Using Toolchains in the Apache Maven documentation.

The following executables will likely be required for a range of Java projects, and should be present in the PATH variable, but they will not be essential in all cases:

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

You will also need to install the build system (for example make, cmake, bazel) and utilities (such as python, perl, lex, and yacc) that your projects depend on.

Windows runners require powershell.exe to be on the PATH.

Building Rust

CodeQL supports build mode none for Rust code.

No build for Rust

CodeQL uses rust-analyzer to compile and run build scripts (build.rs files) and compile macro code, but does not invoke a full build. A database is created from all Rust files present. A Cargo.toml or rust-project.json file must be present.

Runner requirements for Rust

Rust analysis requires rustup and cargo to be installed.

Building Swift

CodeQL supports build modes autobuild or manual for Swift code.

Autobuild summary for Swift

The autobuild process tries to build the biggest target from an Xcode project or workspace.

Code scanning of Swift code uses macOS runners by default. Since GitHub-hosted macOS runners are more expensive than Linux and Windows runners, we recommend that you build only the code that you want to analyze. For more information about pricing for GitHub-hosted runners, see GitHub Actions billing.

Code scanning of Swift code is not supported for runners that are part of an Actions Runner Controller (ARC), because ARC runners only use Linux and Swift requires macOS runners. However, you can have a mixture of both ARC runners and self-hosted macOS runners. For more information, see Actions Runner Controller.

Customizing Swift compilation in a CodeQL analysis workflow

xcodebuild and swift build are both supported for Swift builds. We recommend only targeting one architecture during the build. For example, ARCH=arm64 for xcodebuild, or --arch arm64 for swift build.

You can pass the archive and test options to xcodebuild. However, the standard xcodebuild command is recommended as it should be the fastest, and should be all that CodeQL requires for a successful scan.

For Swift analysis, you must always explicitly install dependencies managed via CocoaPods or Carthage before generating the CodeQL database.