Utilize os verificadores das Diretrizes Principais do C++

As Diretrizes Principais do C++ são um conjunto portátil de diretrizes, regras e práticas recomendadas sobre codificação em C++ criado por especialistas e designers em C++. Atualmente, o Visual Studio oferece suporte a um subconjunto dessas regras como parte de suas ferramentas de análise de código do Microsoft C++. Os principais verificadores de diretrizes são instalados por padrão no Visual Studio 2017 e no Visual Studio 2019. Eles estão disponíveis como um pacote NuGet para o Visual Studio 2015.

O projeto de diretrizes principais do C++

Criadas por Bjarne Stroustrup e outros, as Diretrizes Principais do C++ são um guia para usar o C++ moderno de forma segura e eficaz. As Diretrizes enfatizam a segurança do tipo estático e a segurança dos recursos. Eles identificam maneiras de eliminar ou minimizar as partes mais propensas a erros da linguagem. Eles também sugerem como tornar seu código mais simples, mais confiável e ter melhor desempenho. Essas diretrizes são mantidas pela Standard C++ Foundation. Para saber mais, consulte a documentação, C++ Core Guidelines, e acesse os arquivos de projeto de documentação C++ Core Guidelines no GitHub.

Habilite as diretrizes de verificação principal do C++ na Análise de Código

Um subconjunto de regras C++ Core Check está incluído no conjunto de regras Microsoft Native Recommended . É o conjunto de regras que é executado por padrão quando a análise de código da Microsoft está habilitada.

Para habilitar a análise de código em seu projeto

1. Abra a caixa de diálogo Páginas de propriedades do seu projeto.

2. Selecione a página de propriedades Propriedades de Configuração>Análise de Código.

3. Defina as propriedades Habilitar Análise de Código em Compilar e Habilitar Análise de Código da Microsoft .

Você também pode optar por executar todas as regras de verificação de núcleo C++ suportadas ou selecionar seu próprio subconjunto para executar:

Para habilitar mais regras de verificação principal

1. Abra a caixa de diálogo Páginas de propriedades do seu projeto.

2. Selecione a página de propriedades Propriedades de Configuração>Code Analysis>Microsoft.

3. Abra a lista suspensa Regras Ativas e selecione Escolher vários conjuntos de regras.

4. Na caixa de diálogo Adicionar ou Remover Conjuntos de Regras , escolha quais conjuntos de regras você deseja incluir.

Exemplos

Aqui está um exemplo de alguns dos problemas que as regras de verificação principal do C++ podem encontrar:

// CoreCheckExample.cpp
// Add CppCoreCheck package and enable code analysis in build for warnings.

int main()
{
    int arr[10];           // warning C26494
    int* p = arr;          // warning C26485

    [[gsl::suppress("bounds.1", justification : "This attribute suppresses Bounds rules #1")]]
    {
        int* q = p + 1;    // warning C26481 (suppressed)
        p = q++;           // warning C26481 (suppressed)
    }

    return 0;
}

Este exemplo demonstra alguns dos avisos que as regras de verificação de núcleo C++ podem encontrar:

• C26494 é a regra Type.5: Sempre inicializar um objeto.

• C26485 é a regra Bounds.3: Sem deterioração de matriz para ponteiro.

• C26481 é a regra Bounds.1: Não use aritmética de ponteiro. Utilize span em substituição.

Instale e habilite os conjuntos de regras de análise de código C++ Core Check e, em seguida, compile esse código. A análise de código gera os dois primeiros avisos e suprime o terceiro. Aqui está a saída de compilação do código de exemplo no Visual Studio 2015:

1>------ Build started: Project: CoreCheckExample, Configuration: Debug Win32 ------
1>  CoreCheckExample.cpp
1>  CoreCheckExample.vcxproj -> C:\Users\username\documents\visual studio 2015\Projects\CoreCheckExample\Debug\CoreCheckExample.exe
1>  CoreCheckExample.vcxproj -> C:\Users\username\documents\visual studio 2015\Projects\CoreCheckExample\Debug\CoreCheckExample.pdb (Full PDB)
c:\users\username\documents\visual studio 2015\projects\corecheckexample\corecheckexample\corecheckexample.cpp(6): warning C26494: Variable 'arr' is uninitialized. Always initialize an object. (type.5: http://go.microsoft.com/fwlink/p/?LinkID=620421)
c:\users\username\documents\visual studio 2015\projects\corecheckexample\corecheckexample\corecheckexample.cpp(7): warning C26485: Expression 'arr': No array to pointer decay. (bounds.3: http://go.microsoft.com/fwlink/p/?LinkID=620415)
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

As Diretrizes Principais do C++ existem para ajudá-lo a escrever um código melhor e mais seguro. No entanto, você pode encontrar uma instância em que uma regra ou um perfil não deve ser aplicado. É fácil suprimi-lo diretamente no código. Você pode usar o atributo para impedir que o [[gsl::suppress]] C++ Core Check detete e relate qualquer violação de uma regra no bloco de código a seguir. Você pode marcar declarações individuais para suprimir regras específicas. Você pode até mesmo suprimir todo o perfil de limites escrevendo [[gsl::suppress("bounds")]] sem incluir um número de regra específico.

Conjuntos de regras suportados

À medida que novas regras são adicionadas ao Verificador de Diretrizes Principais do C++, o número de avisos produzidos para código pré-existente pode aumentar. Você pode usar conjuntos de regras predefinidas para filtrar quais tipos de regras habilitar. Você encontrará artigos de referência para a maioria das regras em Visual Studio C++ Core Check Reference.

• Regras aritméticas: Regras para detetar estouro aritmético, operações assinadas-não assinadas e manipulação de bits. ^15,6

• Regras de limites: imponha o perfil de limites das diretrizes principais do C++. ^15,3

• Regras de classe: Algumas regras que se concentram no uso adequado de funções especiais de membro e especificações virtuais. Eles são um subconjunto das verificações recomendadas para classes e hierarquias de classe. ^15,5

• Regras de simultaneidade: uma única regra, que captura declarações inadequadas de 'guard object'. Para obter mais informações, consulte as diretrizes relacionadas à simultaneidade. ^15,5

• Regras Const: Aplique verificações relacionadas a const a partir das Diretrizes Principais do C++. ^15,3

• Regras de declaração: algumas regras das diretrizes de interfaces que se concentram em como as variáveis globais são declaradas. ^15,5

• Regras de Enum: essas regras impõem verificações relacionadas a enum das Diretrizes Principais do C++. ^16,3

• Regras Experimentais Estas são regras experimentais do C++ Core Check que são úteis, mas não estão prontas para uso diário. Experimente-os e forneça feedback. ^16,0

• Regras de função: Duas verificações que ajudam na adoção do noexcept especificador. Eles fazem parte das diretrizes para o design e implementação de funções claras. ^15,5

• Regras GSL: essas regras impõem verificações relacionadas à Biblioteca de Suporte de Diretrizes das Diretrizes Principais do C++. ^15,7

• Regras de tempo de vida: essas regras impõem o perfil de tempo de vida das diretrizes principais do C++. ^15,7

• Regras de ponteiro do proprietário: imponha verificações de gerenciamento de recursos relacionadas ao proprietário<T> a partir das Diretrizes principais do C++.^15,3

• Regras de Ponteiro Cru: aplicar verificações de gestão de recursos relacionadas a ponteiros crus das Diretrizes Principais do C++. ^15.3

• Regras de ponteiro compartilhado: Faz parte da aplicação de diretrizes de gerenciamento de recursos . ^15.5 Adicionamos algumas regras específicas sobre como ponteiros compartilhados são passados para funções ou usados localmente.

• Regras STL: essas regras impõem verificações relacionadas à STL (C++ Standard Library) das Diretrizes Principais do C++. ^15,7

• Regras de estilo: Uma verificação simples, mas importante, que proíbe o uso de goto. ^15.5 É o primeiro passo para melhorar seu estilo de codificação e uso de expressões e instruções em C++.

• Regras de tipo: aplique o perfil de tipos das C++ Core Guidelines. ^15.3

• Regras de ponteiro exclusivas: imponha verificações de gerenciamento de recursos relacionadas a tipos com semântica de ponteiro exclusiva das Diretrizes Principais do C++. ^15,3

• Regras de verificação principais do C++: este conjunto de regras contém todas as verificações atualmente implementadas das diretrizes principais do C++, exceto as regras experimentais.

^15.3 Essas regras apareceram pela primeira vez no Visual Studio 2017 versão 15.3
^15.5 Essas regras apareceram pela primeira vez no Visual Studio 2017 versão 15.5
^15.6 Essas regras apareceram pela primeira vez no Visual Studio 2017 versão 15.6
^15.7 Essas regras apareceram pela primeira vez no Visual Studio 2017 versão 15.7
^16.0 Essas regras apareceram pela primeira vez no Visual Studio 2019 versão 16.0
^16.3 Essas regras apareceram pela primeira vez no Visual Studio 2019 versão 16.3

Você pode optar por limitar os avisos a apenas um ou alguns dos grupos. Os conjuntos de regras Native Minimum e Native Recommended incluem regras C++ Core Check e outras verificações PREfast.

Para ver os conjuntos de regras disponíveis, abra a caixa de diálogo Propriedades do projeto . Na caixa de diálogo Property Pages, selecione a página de propriedades Configuration Properties>Code Analysis>Microsoft. Em seguida, abra o menu suspenso em Regras Ativas para ver os conjuntos de regras disponíveis. Para criar uma combinação personalizada de conjuntos de regras, selecione Escolher vários conjuntos de regras. A caixa de diálogo Adicionar ou Remover Conjuntos de Regras lista as regras que você pode escolher. Para obter mais informações sobre como usar conjuntos de regras no Visual Studio, consulte Usar conjuntos de regras para especificar as regras C++ a serem executadas.

Macros

O C++ Core Guidelines Checker vem com um arquivo de cabeçalho, que define macros que facilitam a supressão de categorias inteiras de avisos no código:

ALL_CPPCORECHECK_WARNINGS
CPPCORECHECK_TYPE_WARNINGS
CPPCORECHECK_RAW_POINTER_WARNINGS
CPPCORECHECK_CONST_WARNINGS
CPPCORECHECK_OWNER_POINTER_WARNINGS
CPPCORECHECK_UNIQUE_POINTER_WARNINGS
CPPCORECHECK_BOUNDS_WARNINGS

Essas macros correspondem aos conjuntos de regras e se expandem em uma lista separada por espaços de números de aviso. Usando as construções pragma apropriadas, você pode configurar o conjunto efetivo de regras que é interessante para um projeto ou uma seção de código. No exemplo a seguir, a análise de código avisa apenas sobre modificadores constantes ausentes:

#include <CppCoreCheck\Warnings.h>
#pragma warning(disable: ALL_CPPCORECHECK_WARNINGS)
#pragma warning(default: CPPCORECHECK_CONST_WARNINGS)

Atributos

O compilador Microsoft C++ tem suporte limitado para o [[gsl::suppress]] atributo. Ele pode ser usado para suprimir avisos na expressão e bloquear instruções dentro de funções.

// Suppress only warnings from the 'r.11' rule in expression.
[[gsl::suppress("r.11")]] new int;

// Suppress all warnings from the 'r' rule group (resource management) in block.
[[gsl::suppress("r")]]
{
    new int;
}

// Suppress only one specific warning number.
// For declarations, you might need to use the surrounding block.
// Macros are not expanded inside of attributes.
// Use plain numbers instead of macros from the warnings.h.
[[gsl::suppress("26400")]]
{
    int *p = new int;
}

Suprimir análise usando opções de linha de comando

Em vez de #pragmas, você pode usar opções de linha de comando na página de propriedades do arquivo para suprimir avisos para um projeto ou um único arquivo. Por exemplo, para desativar o aviso C26400 para um arquivo:

1. Clique com o botão direito do mouse no arquivo no Gerenciador de Soluções e escolha Propriedades.

2. Na caixa de diálogo Property Pages , selecione a página de propriedades Configuration Properties>C/C++>Command Line .

3. Na caixa de edição Opções Adicionais , adicione /wd26400.

Você pode usar a opção de linha de comando para desabilitar temporariamente toda a análise de código de um arquivo especificando /analyze-. Você verá o aviso D9025 substituindo '/analyze' por '/analyze-', o que o lembra de reativar a análise de código mais tarde.

Habilite o Verificador de Diretrizes Principais do C++ em arquivos de projeto específicos

Às vezes, é útil fazer análise de código focada e ainda usar o IDE do Visual Studio. Experimente o seguinte cenário de exemplo para projetos grandes. Ele pode economizar tempo de compilação e facilitar a filtragem de resultados:

1. No shell de comando, defina a esp.extension variável de ambiente.

2. Para herdar essa variável, abra o Visual Studio no shell de comando.

3. Carregue o seu projeto e abra as suas propriedades.

4. Habilite a análise de código, escolha os conjuntos de regras apropriados, mas não habilite as extensões de análise de código.

5. Vá para o arquivo que você deseja analisar com o C++ Core Guidelines Checker e abra suas propriedades.

6. Escolha Propriedades> de ConfiguraçãoC/C++>Opções Adicionais de Linha de Comando> e adicione/analyze:plugin EspXEngine.dll

7. Desative o uso de cabeçalho pré-compilado (Propriedades> de configuraçãoC/C++>Cabeçalhos pré-compilados). É necessário porque o motor de extensões pode tentar ler as suas informações internas a partir do cabeçalho pré-compilado (PCH). Se a PCH foi compilada com opções de projeto padrão, ela não será compatível.

8. Reconstrua o projeto. As verificações comuns do PREFast devem ser executadas em todos os arquivos. Como o Verificador de Diretrizes Principais do C++ não está habilitado por padrão, ele só deve ser executado no arquivo configurado para usá-lo.

Como usar o C++ Core Guidelines Checker fora do Visual Studio

Você pode usar as verificações das Diretrizes Principais do C++ em compilações automatizadas.

MSBuild

O verificador de análise de código nativo (PREfast) é integrado ao ambiente MSBuild por arquivos de destino personalizados. Você pode usar as propriedades do projeto para habilitá-lo e adicionar o Verificador de Diretrizes Principais do C++ (que se baseia no PREfast):

  <PropertyGroup>
    <EnableCppCoreCheck>true</EnableCppCoreCheck>
    <CodeAnalysisRuleSet>CppCoreCheckRules.ruleset</CodeAnalysisRuleSet>
    <RunCodeAnalysis>true</RunCodeAnalysis>
  </PropertyGroup>

Certifique-se de adicionar essas propriedades antes da importação do Microsoft.Cpp.targets arquivo. Você pode escolher conjuntos de regras específicos ou criar um conjunto de regras personalizado. Ou use o conjunto de regras padrão que inclui outras verificações PREfast.

Você pode executar o C++ Core Checker somente em arquivos especificados. Use a mesma abordagem descrita anteriormente, mas use arquivos MSBuild. As variáveis de ambiente podem ser definidas usando o BuildMacro item:

<ItemGroup>
    <BuildMacro Include="Esp_Extensions">
      <EnvironmentVariable>true</EnvironmentVariable>
      <Value>CppCoreCheck.dll</Value>
    </BuildMacro>
</ItemGroup>

Se você não quiser modificar o arquivo de projeto, você pode passar propriedades na linha de comando:

msbuild /p:EnableCppCoreCheck=true /p:RunCodeAnalysis=true /p:CodeAnalysisRuleSet=CppCoreCheckRules.ruleset ...

Projetos não-MSBuild

Se você usar um sistema de compilação que não depende do MSBuild, ainda poderá executar o verificador. Para usá-lo, você precisa se familiarizar com alguns componentes internos da configuração do mecanismo de Análise de Código. Não garantimos suporte para esses internos em versões futuras do Visual Studio.

A Análise de Código requer algumas variáveis de ambiente e opções de linha de comando do compilador. Recomendamos que você use o ambiente de prompt de comando de ferramentas nativas para não precisar procurar caminhos específicos para o compilador, incluir diretórios e assim por diante.

• Variáveis de ambiente

  • set esp.extensions=cppcorecheck.dll Isto indica ao motor para carregar o módulo C++ Core Guidelines.
  • Desde o Visual Studio 2019, não recomendamos mais definir a variável de ambiente porque defini-la esp.annotationbuildlevel pode resultar em falsos positivos. Se vir resultados inesperados, remova essa variável do seu ambiente.
  • set caexcludepath=%include% É altamente recomendável que se desative os avisos que surgem em cabeçalhos padrão. Você pode adicionar mais caminhos aqui, por exemplo, o caminho para os cabeçalhos comuns em seu projeto.

• Opções de linha de comando

  • /analyze Permite a análise de código (considere também usar /analyze:only e /analyze:quiet).
  • /analyze:plugin EspXEngine.dll Esta opção carrega o mecanismo de extensões de análise de código no PREfast. Esse mecanismo, por sua vez, carrega o C++ Core Guidelines Checker.

Usar a Biblioteca de Suporte de Diretrizes

A Biblioteca de Suporte de Diretrizes (GSL) foi projetada para ajudá-lo a seguir as Diretrizes Principais. O GSL inclui definições que permitem substituir construções propensas a erros por alternativas mais seguras. Por exemplo, você pode substituir um T*, length par de parâmetros pelo span<T> tipo. O projeto GSL está disponível no GitHub em https://github.com/Microsoft/GSL. A biblioteca é de código aberto, para que você possa visualizar as fontes, fazer comentários ou contribuir. Você também pode usar o gerenciador de pacotes vcpkg para baixar e instalar a biblioteca localmente.

Ver também

• Referência de verificação do Visual Studio C++ Core