Opções e etapas de build do CodeQL para idiomas compilados

Passos de compilação automática para linguagens compiladas

           Se você usar corredores auto-hospedados para GitHub Actions, talvez seja necessário instalar software adicional para usar o `autobuild` processo. Além disso, se seu repositório precisar de uma versão específica de uma ferramenta de criação, talvez seja necessário instalá-lo manualmente. 
           Para executores auto-hospedados, você deve instalar dependências diretamente nos próprios executores. Fornecemos exemplos de dependências comuns para C/C++, C#e Java em cada uma das seções `autobuild` deste artigo para esses idiomas. Para obter mais informações, consulte [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners).

Compilação em C/C++

          CodeQLdá suporte aos modos `autobuild`de build ou `manual` ao código C/C++.

Resumo de compilação automática para C/C++

Tipo de sistema compatível	Nome do sistema
Sistema operacional	Windows, macOS e Linux
Sistema de criação	Windows: MSBuild e scripts de compilação Linux e macOS: Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild e scripts de build

O comportamento da etapa autobuild varia de acordo com o sistema operacional em que a extração é executada.

Detecção automática do Windows

No Windows, a etapa autobuild tenta fazer a detecção automática de um método de build adequado para C/C++ usando a seguinte abordagem:

1. Invocar MSBuild.exe no arquivo de solução (.sln) ou de projeto (.vcxproj) mais próximo da raiz. Se autobuild detectar vários arquivos de solução ou de projeto na mesma profundidade (mais curta) do diretório de nível superior, ele tentará compilar todos eles.
2. Invocar um script parecido com um script de build—build.bat, build.cmd e build.exe (nessa ordem).

Detecção automática de Linux e macOS

No Linux e no macOS, a etapa autobuild revisa os arquivos presentes no repositório para determinar o sistema de build usado:

1. Procure um sistema de criação no diretório-raiz.
2. Se nenhum for encontrado, procure um diretório único nos subdiretórios com um sistema de criação para C/C++.
3. Execute um comando apropriado para configurar o sistema.

Requisitos do executor para C/C++

Nos executores do Ubuntu Linux, autobuild pode tentar instalar automaticamente as dependências exigidas pelas etapas de configuração e compilação detectadas. Por padrão, esse comportamento é habilitado em GitHubexecutores hospedados e desabilitado em executores auto-hospedados. Você pode habilitar ou desabilitar esse recurso explicitamente definindo CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES para true ou false no ambiente. Para obter mais informações sobre a definição de variáveis de ambiente, confira Armazenar informações em variáveis.

Para executores auto-hospedados, a menos que a instalação automática de dependências esteja habilitada, você provavelmente precisará instalar o compilador gcc e projetos específicos também podem exigir acesso a executáveis clang ou msvc. Você também precisará instalar o sistema de compilação (por exemplo msbuild, make, cmake, bazel) e utilitários (como python, perl, lex e yacc) dos quais seus projetos dependem. Se você habilitar a instalação automática de dependências, deverá garantir que o executor esteja usando o Ubuntu e que ele possa ser executado sudo apt-get sem a necessidade de uma senha.

Os executores do Windows precisam que o powershell.exe esteja em PATH.

Compilação C#

          CodeQL suporta os modos de build `none`, `autobuild` ou `manual` para código C#.

Quando você habilita a configuração padrão para um repositório que contém código C#, o modo de compilação é definido automaticamente como none.

Nenhuma compilação para C#

          CodeQL restaura dependências e gera alguns arquivos de origem adicionais, para fornecer resultados mais precisos, antes de criar um banco de dados de todos os arquivos e dependências de origem.

As dependências são restauradas usando várias heurísticas e estratégias. Os seguintes arquivos são a principal fonte de informações: *.csproj, *.sln, nuget.config, packages.config, global.json e project.assets.json. Se um feed NuGet privado estiver definido para a organização, ele também será utilizado, consulte o acesso ao registro privado na configuração padrão de verificação de código e determinando se a configuração padrão de verificação de código usou algum registro privado.

Os seguintes arquivos de origem gerados são opcionais, mas aumentam significativamente a correção do banco de CodeQL dados:

• global gerou diretivas using para lidar com o recurso implícito using do MSbuild.
• Arquivos de exibição do ASP.NET Core, arquivos .cshtml são convertidos em arquivos .cs.

As informações dos nomes dos assemblies de dependências, dos arquivos de origem gerados, das dependências armazenadas em feeds privados e dos arquivos de origem no repositório são compiladas e utilizadas para criar um CodeQL banco de dados.

Precisão da análise sem compilação para C#

Criar um CodeQL banco de dados sem criar o código completo depende de ser capaz de restaurar dependências e ser capaz de compilar juntos os arquivos de origem no repositório. Quando há problemas para restaurar dependências ou compilar o código-fonte, isso pode afetar a precisão do CodeQL banco de dados e dos resultados da code scanning análise.

Você pode garantir uma análise mais precisa seguindo estas etapas:

• Forneça acesso à Internet pública ou certifique-se de que o acesso a um feed privado do NuGet está disponível, consulte Configuração padrão de verificação de código para registros privados.
• Verifique se o repositório requer várias versões da mesma dependência NuGet. CodeQL pode usar apenas uma versão e geralmente escolhe a versão mais recente em que há várias versões. Essa abordagem pode não funcionar para todos os repositórios.
• Verifique se várias versões de .NET são referenciadas, por exemplo, net48, net5.0 e netstandard1.6. CodeQL pode usar apenas uma versão e isso pode afetar a precisão.
• Evite colidir nomes de classe, caso contrário, isso pode ocasionar destinos de chamada de método ausentes, o que afeta a análise de fluxo de dados.

Resumo do autobuild para C#

Tipo de sistema compatível	Nome do sistema
Sistema operacional	Windows, macOS e Linux
Sistema de criação	.NET e MSbuild, bem como criar scripts

Detecção automática do Windows

O processo autobuild tenta fazer a detecção automática de um método de build adequado para C# usando a seguinte abordagem:

1. Invocar dotnet build no arquivo de solução (.sln) ou de projeto (.csproj) mais próximo da raiz.
2. Invocar MSBuild.exe no arquivo de solução ou de projeto mais próximo da raiz. Se autobuild detectar vários arquivos de solução ou de projeto na mesma profundidade (mais curta) do diretório de nível superior, ele tentará compilar todos eles.
3. Invocar um script parecido com um script de build—build.bat, build.cmd, e build.exe (nessa ordem).

Requisitos de executor para C# no Windows

Para o desenvolvimento de aplicativos .NET Core em executores auto-hospedados, o SDK do .NET é necessário (para dotnet).

Para o desenvolvimento de aplicativos do .NET Framework, você precisará de ferramentas de Microsoft Build (para msbuild) e CLI do NuGet (para nuget).

Os executores do Windows precisam que o powershell.exe esteja em PATH.

Se você planeja criar CodeQL bancos de dados usando build-mode: none, também precisa fornecer acesso à Internet pública ou garantir que o acesso a um feed NuGet privado esteja disponível.

Detecção automática de Linux e macOS

1. Invocar dotnet build no arquivo de solução (.sln) ou de projeto (.csproj) mais próximo da raiz.
2. Invocar MSbuild no arquivo de solução ou de projeto mais próximo da raiz. Se autobuild detectar vários arquivos de solução ou de projeto na mesma profundidade (mais curta) do diretório de nível superior, ele tentará compilar todos eles.
3. Invocar um script parecido com um script de build—build e build.sh (nessa ordem).

Requisitos do executor para C# no Linux e macOS

Para o desenvolvimento de aplicativos .NET Core em executores auto-hospedados, o SDK do .NET é necessário (para dotnet).

Para o desenvolvimento de aplicativos do .NET Framework, você exigirá o Mono Runtime (para executar mono, msbuild ou nuget).

Se você planeja criar CodeQL bancos de dados usando build-mode: none, também precisa fornecer acesso à Internet pública ou garantir que o acesso a um feed NuGet privado esteja disponível.

Sinalizadores do compilador C# injetados por CodeQL para builds manuais

O CodeQL rastreador permite a extração de todas as linguagens compiladas ao interceptar processos de compilação e encaminhando informações para os extratores relevantes de linguagem CodeQL. O rastreador injeta determinados sinalizadores na invocação do compilador C# para garantir que todos os componentes sejam construídos e incluídos no banco de dados CodeQL, o que pode fazer com que o código C# seja compilado de uma maneira diferente do que você espera durante a análise CodeQL.

/p:MvcBuildViews=true

Quando essa opção é definida como true, os modos de exibição em projetos ASP.NET MVC (model-view-controller) são pré-compilados como parte do processo de build, o que pode ajudar a capturar erros e melhorar o desempenho. O rastreador injeta esse sinalizador para verificar se CodeQL localiza e realça problemas de segurança que podem envolver o fluxo de dados por meio do código gerado a partir dessas exibições. Para obter mais informações, consulte Adicionando uma exibição a um aplicativo MVC no Microsoft Learn.

/p:UseSharedCompilation=false

Definir essa opção para false desabilita o uso do recurso de compilação compartilhada, o que pode resultar em tempos de compilação mais lentos. Quando /p:UseSharedCompilation=false não é especificado, o msbuild inicia um processo do servidor do compilador e toda a compilação será feita por esse único processo. No entanto, o CodeQL rastreador depende da inspeção dos argumentos dos processos recém-criados.

/p:EmitCompilerGeneratedFiles=true

Definir essa opção como true emitirá arquivos gerados pelo compilador durante o processo de compilação. Essa opção faz com que o compilador gere arquivos de origem adicionais que são usados ​​para dar suporte a recursos como suporte aprimorado a expressões regulares, serialização e geração de visualizações de aplicativos web. Esses artefatos gerados normalmente não são gravados em disco pelo compilador, mas definir a opção para true força a gravação dos arquivos no disco e, portanto, o extrator pode processar os arquivos.

Para alguns projetos legados e projetos que utilizam .sqlproj, você pode ver que a propriedade /p:EmitCompilerGeneratedFiles=true injetada causa problemas inesperados com o msbuild. Para obter informações sobre como solucionar esse problema, consulte Compilador C# falhando de forma inesperada.

Compilação Go

          CodeQL dá suporte aos modos `autobuild` de build ou `manual` ao código Go.

Resumo de compilação automática para Go

Tipo de sistema compatível	Nome do sistema
Sistema operacional	Windows, macOS e Linux
Sistema de criação	Módulos Go, dep e Glide, bem como scripts de build, incluindo Makefiles e scripts Ninja

Detecção automática para Go

O processo autobuild tenta fazer a detecção automática de uma forma adequada para instalar as dependências necessárias em um repositório Go antes de extrair todos os arquivos .go:

1. Invoque make, ninja, ./build ou ./build.sh (nessa ordem) até que um desses comandos seja bem-sucedido e um próximo go list ./... também seja bem-sucedido, indicando que as dependências necessárias foram instaladas.
2. Se nenhum desses comandos for bem-sucedido, procure go.mod, Gopkg.toml ou glide.yaml e execute go get (a menos que a cópia para a pasta Vendor esteja em uso), dep ensure -v ou glide install, respectivamente, para tentar instalar as dependências.
3. Por fim, se os arquivos de configurações desses gerenciadores de dependência não forem encontrados, reorganize a estrutura de diretório do repositório adequada para adição a GOPATH e use go get para instalar as dependências. A estrutura de diretório é revertida para normal após a conclusão da extração.
4. Extraia todo o código Go no repositório, semelhante à execução de go build ./....

Opções de extrator para Go

Por padrão, o código de teste (código em arquivos terminados em _test.go) não é analisado. Você pode substituir isso com a opção --extractor-option extract_tests=true ao usar o CodeQL CLI, ou definindo a variável CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS de ambiente como true.

Além disso, vendor diretórios são excluídos da análise Go CodeQL por padrão. Você pode substituir isso passando a opção --extractor-option extract_vendor_dirs=true ao usar o CodeQL CLI, ou definindo a variável CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS de ambiente como true.

Criando Java e Kotlin

          CodeQL dá suporte aos seguintes modos de build.

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

Quando você habilita a configuração padrão para um repositório pela primeira vez, se apenas Java código for detectado, o modo de build será definido como none. Se o Kotlin ou uma combinação de código Java e Kotlin for detectado, o modo de build será definido como autobuild.

Se mais tarde você adicionar o código Kotlin a um repositório que usa o modo de compilação none, a análise CodeQL reporta uma mensagem de aviso explicando que o Kotlin não é suportado. Você precisará desativar a configuração padrão e reativá-la. Quando você reativar a instalação padrão, o modo de compilação será alterado para autobuild para que ambos os idiomas possam ser analisados. Como alternativa, você pode alterar para uma configuração avançada. Para saber mais, confira Aviso: Detectados X arquivos Kotlin no seu projeto que não puderam ser processados sem compilação.

Nenhuma compilação para Java

          CodeQL tentará executar o Gradle ou o Maven para extrair informações precisas de dependência (mas não para invocar um build), antes de criar um banco de dados de todos os arquivos Java presentes. Cada arquivo de projeto raiz do Maven ou do Gradle (um script de compilação sem qualquer script de compilação presente em um diretório ancestral) é consultado para obter informações de dependência e, em caso de conflito, as versões de dependência mais recentes são preferidas. Para obter informações sobre os requisitos do executor do Maven ou do Gradle, consulte [Requisitos do Runner para Java](#runner-requirements-for-java).


          Se um registro Maven privado for definido para a organização, isso também será usado, consulte [o acesso de configuração padrão de verificação de código para registros privados](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries#code-scanning-default-setup-access-to-private-registries) e [determinando se a configuração padrão de verificação de código usou registros privados](/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs#determining-whether-code-scanning-default-setup-used-any-private-registries).

Precisão da análise sem compilação para Java

Criar um banco de dados CodeQL Java sem um build pode produzir resultados menos precisos do que usar autobuild ou etapas de build manuais se:

• Os scripts de build do Gradle ou Maven não puderem ser consultados para obter informações de dependência, e as suposições de dependência (baseadas em nomes de pacotes Java) forem imprecisas.
• O repositório normalmente gera código durante o processo de compilação. Isso seria analisado se você criasse o CodeQL banco de dados usando um modo diferente.

Você pode garantir uma análise mais precisa seguindo estas etapas:

• Forneça acesso à internet pública ou verifique se o acesso a um repositório de artefatos privado está disponível, consulte Configuração padrão de verificação de código para acesso a registros privados.
• Verifique se o repositório requer várias versões da mesma dependência. CodeQL pode usar apenas uma versão e geralmente escolhe a versão mais recente em que há várias versões. Essa abordagem pode não funcionar para todos os repositórios.
• Verifique se mais de uma versão da API do JDK é necessária por diferentes arquivos de Java de origem. Quando várias versões forem vistas, CodeQL usará a versão mais alta exigida por qualquer script de build. Isso pode significar que alguns arquivos que exigem uma versão inferior do JDK serão analisados ​​parcialmente. Por exemplo, se alguns arquivos exigirem o JDK 8, mas um requisito do JDK 17 for encontrado em um ou mais scripts de build, CodeQL usará o JDK 17. Quaisquer arquivos que exijam o JDK 8 e não possam ser compilados usando o JDK 17 serão parcialmente analisados.
• Evite colidir nomes de classes (por exemplo, vários arquivos definindo org.myproject.Test), caso contrário, isso poderá causar destinos de chamadas de método ausentes, o que afeta a análise do fluxo de dados.

Resumo da construção automatizada para Java

Tipo de sistema compatível	Nome do sistema
Sistema operacional	Windows, macOS e Linux (sem restrição)
Sistema de criação	Gradle, Maven e Ant

Autodeteção para Java

O processo autobuild tenta determinar o sistema de build para bases de código Java ao aplicar esta estratégia:

1. Procurar um arquivo de criação no diretório-raiz. Verifique o arquivos do Gradle, do Maven e, em seguida, do Ant.
2. Execute o primeiro arquivo de criação encontrado. Se os arquivos do Gradle e do Maven estiverem presentes, será usado o arquivo do Gradle.
3. Caso contrário, procure arquivos de criação nos subdiretórios diretos do diretório-raiz. Se apenas um subdiretório contiver arquivos de criação, execute o primeiro arquivo identificado nesse subdiretório (usando a mesma preferência de 1). Se mais de um subdiretório conter arquivos de criação, relate um erro.

Requisitos do executor para Java

Se você estiver usando executores auto-hospedados, as versões necessárias de Java deverão estar presentes:

• Se o executor for usado para analisar repositórios que precisam de uma única versão do Java, a versão apropriada do JDK precisa ser instalada e precisa estar presente na variável PATH (para que java e javac possam ser encontrados).

• Se o executor for usado para analisar repositórios que precisam de várias versões do Java, as versões apropriadas do JDK precisarão ser instaladas e poderão ser especificadas por meio do arquivo toolchains.xml. Este é um arquivo de configuração, normalmente usado pelo Apache Maven, que permite especificar o local e a versão das ferramentas, além de qualquer configuração adicional necessária para utilizá-las. Para obter mais informações, consulte Guia para usar cadeia de ferramentas na documentação do Apache Maven.

Os seguintes executáveis provavelmente serão necessários para um intervalo de projetos Java e devem estar presentes na variável PATH, mas eles não serão essenciais em todos os casos:

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

Você também precisará instalar o sistema de compilação (por exemplo make, cmake, bazel) e utilitários (como python, perl, lex e yacc) dos quais seus projetos dependem.

Os executores do Windows precisam que o powershell.exe esteja em PATH.

Compilação Swift

          CodeQL dá suporte aos modos `autobuild` de build ou `manual` ao código Swift.

Resumo de compilação automática para Swift

Tipo de sistema compatível	Nome do sistema
Sistema operacional	macOS
Sistema de criação	Xcode

O processo autobuild tenta criar o maior destino de um projeto ou workspace Xcode.

A verificação do código Swift usa executores do macOS por padrão.

O Code scanning do código Swift não é compatível com executores que fazem parte de um Actions Runner Controller (ARC), porque os executores ARC usam apenas o Linux e o Swift requer executores macOS. No entanto, você pode ter uma mistura de executores ARC e executores macOS auto-hospedados. Para saber mais, confira Controlador de Ações Runner.

Personalizando a compilação Swift em um Fluxo de trabalho de análise do CodeQL

          `xcodebuild` e `swift build` são compatíveis com builds Swift. Recomendamos direcionar apenas uma arquitetura durante o build. Por exemplo, `ARCH=arm64` para `xcodebuild` ou `--arch arm64` para `swift build`.

Você pode passar as opções archive e test para xcodebuild. No entanto, o comando padrão xcodebuild é recomendado, pois deve ser o mais rápido e deve ser tudo o que CodeQL requer para uma verificação bem-sucedida.

Para análise do Swift, você deve sempre instalar explicitamente as dependências gerenciadas por meio do CocoaPods ou do Carthage antes de gerar o CodeQL banco de dados.