Usar los comprobadores de C++ Core Guidelines

Las C++ Core Guidelines son un conjunto portátil de directrices, reglas y procedimientos recomendados sobre la codificación en C++ creado por expertos y diseñadores de C++. Visual Studio admite actualmente un subconjunto de estas reglas como parte de sus herramientas de análisis de código para C++. Los comprobadores de directrices principales se instalan de forma predeterminada en Visual Studio 2017 y Visual Studio 2019. Están disponibles como un paquete NuGet para Visual Studio 2015.

Proyecto C++ Core Guidelines

Creado por Bjarne Stroustrup y otros, las directrices C++ Core Guidelines son una guía para usar un C++ moderno de forma segura y eficaz. Las directrices resaltan tanto la seguridad de tipos estáticos como la de los recursos. Identifican formas de eliminar o minimizar las partes más propensas a errores del lenguaje. También sugieren cómo simplificar el código, hacerlo más confiable y tener un mejor rendimiento. Estas guías se mantienen por medio de la Standard C++ Foundation. Para más información, consulte la documentación, C++ Core Guidelines y acceda a los archivos del proyecto de documentación de C++ Core Guidelines en GitHub.

Habilitación de las directrices de C++ Core Check en Code Analysis

Un subconjunto de reglas de C++ Core Check se incluye en el conjunto de reglas nativas recomendadas de Microsoft. Es el conjunto de reglas que se ejecuta de forma predeterminada cuando el análisis de código de Micrófono está habilitado.

Para habilitar el análisis de código en el proyecto:

1. Abra el diálogo Páginas de propiedades del proyecto.

2. Seleccione la página de Propiedades de configuración>Code Analysis.

3. Establezca las propiedades Habilitar Code Analysis en Compilación y Habilitar Code Analysis de Microsoft.

También se puede optar por ejecutar todas las reglas compatibles de C++ Core Check o seleccionar el propio subconjunto para ejecutarlo:

Para habilitar más reglas de Comprobación básica

1. Abra el diálogo Páginas de propiedades del proyecto.

2. Seleccione la página de Propiedades de configuración>Code Analysis>Microsoft.

3. Abra la lista desplegable Reglas activas y seleccione Elegir varios conjuntos de reglas.

4. En el cuadro de diálogo Agregar o quitar conjuntos de reglas, elija qué conjuntos de reglas desea incluir.

Ejemplos

Este es un ejemplo de algunos de los problemas que las reglas de C++ Core Check pueden 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)]] // This attribute suppresses Bounds rule #1
    {
        int* q = p + 1;    // warning C26481 (suppressed)
        p = q++;           // warning C26481 (suppressed)
    }

    return 0;
}

En este ejemplo se muestran algunas de las advertencias que las reglas de C++ Core Check pueden encontrar:

• C26494 es la regla Type.5: inicializar siempre un objeto.

• C26485 es la regla Bounds.3: sin decadencia de matriz a puntero.

• C26481 es la regla Bounds.1: no use aritmética de puntero. En su lugar, use span.

Instale y habilite los conjuntos de reglas del análisis de código de C++ Core Check y después compile este código. El análisis de código genera las dos primeras advertencias y suprime la tercera. Esta es la salida de compilación del código de ejemplo en 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 ==========

Las directrices de C++ Core Guidelines están allí para ayudarle a escribir un código mejor y más seguro. Sin embargo, es posible que encuentre una instancia en la que no se debe aplicar una regla o un perfil. Es fácil suprimirlo directamente en el código. Se puede usar el atributo [[gsl::suppress]] para evitar que C++ Core Check detecte e informe cualquier infracción de una regla en el siguiente bloque de código. Se pueden marcar instrucciones individuales para suprimir reglas específicas. Se puede incluso suprimir todo el perfil de límites al escribir [[gsl::suppress(bounds)]] sin incluir un número de regla específico.

Conjuntos de reglas admitidos

A medida que se agregan nuevas reglas al Comprobador de directrices básicas de C++, es posible que aumente el número de advertencias generadas para código preexistente. Se pueden usar conjuntos de reglas predefinidos para filtrar qué tipos de reglas habilitar. Encontrará artículos de referencia para la mayoría de las reglas en la Referencia C++ Core Check de Visual Studio.

• Reglas aritméticas: reglas para detectar desbordamiento aritmético, operaciones firmadas y sin firmar y manipulación de bits.^15.6

• Reglas de límites: aplica el perfil de límites de C++ Core Guidelines.^15.3

• Reglas de clase: algunas reglas que se centran en el uso adecuado de funciones miembro especiales y especificaciones virtuales. Son un subconjunto de las comprobaciones recomendadas para las clases y las jerarquías de clases.^15.5

• Reglas de simultaneidad: una sola regla, que detecta declaraciones de objetos de protección incorrectas. Para obtener más información, consulte Directrices relacionadas con la simultaneidad.^15.5

• Reglas de constitución: aplique comprobaciones relacionadas con la constitución desde C++ Core Guidelines.^15.3

• Reglas de declaración: un par de reglas de las directrices de interfaces que se centran en cómo se declaran las variables globales.^15.5

• Reglas de enumeración: estas reglas aplican las comprobaciones relacionadas con la enumeración de C++ Core Guidelines.^16.3

• Reglas experimentales: estas son reglas experimentales de C++ Core Check que son útiles, pero no están listas para el uso diario. Pruébelos y proporcione comentarios.^16.0

• Reglas de función: dos comprobaciones que ayudan con la adopción del especificador noexcept. Forman parte de las directrices para el diseño y la implementación de funciones claras.^15.5

• Reglas de GSL: estas reglas aplican comprobaciones relacionadas con la Biblioteca de compatibilidad de directrices de C++ Core Guidelines.^15.7

• Reglas de duración: estas reglas aplican el perfil de duración de las directrices de C++ Core Guidelines.^15.7

• Reglas del puntero del propietario: aplica comprobaciones de administración de recursos relacionadas con el propietario<T> desde C++ Core Guidelines.^15.3

• Reglas del puntero básico del propietario: aplica comprobaciones de la administración de recursos relacionadas con los punteros básicos de las C++ Core Guidelines.^15.3

• Reglas de puntero compartido: forma parte de la aplicación de las directrices de administración de recursos.^15.5 Se han agregado algunas reglas específicas sobre cómo se pasan los punteros compartidos a funciones o se usan localmente.

• Reglas de STL: estas reglas aplican comprobaciones relacionadas con la Biblioteca Estándar (STL) de C++ desde C++ Core Guidelines.^15.7

• Reglas de estilo: una comprobación simple pero importante, que prohíbe el uso de goto.^15.5 Es el primer paso para mejorar el estilo de codificación y el uso de expresiones e instrucciones en C++.

• Reglas de tipo: aplica el tipo de límites de C++ Core Guidelines.^15.3

• Reglas de puntero únicas: aplican comprobaciones de administración de recursos relacionadas con tipos con semántica de puntero única de las C++ Core Guidelines.^15.3

• Reglas del C++ Core Check: este conjunto de reglas contiene todas las comprobaciones implementadas actualmente de las C++ Core Guidelines, excepto las reglas experimentales.

^15.3 Estas reglas aparecieron por primera vez en Visual Studio 2017 versión 15.3
^15.5 Estas reglas aparecieron por primera vez en Visual Studio 2017 versión 15.5
^15.6 Estas reglas aparecieron por primera vez en Visual Studio 2017 versión 15.6
^15.7 Estas reglas aparecieron por primera vez en Visual Studio 2017 versión 15.7
^16.0 Estas reglas aparecieron por primera vez en Visual Studio 2019 versión 16.0
^16.3 Estas reglas aparecieron por primera vez en Visual Studio 2019 versión 16.3

Puede optar por limitar las advertencias a solo uno o varios de los grupos. Los conjuntos de reglas nativas mínimas y nativas recomendadas incluyen reglas de C++ Core Check y otras comprobaciones PREfast.

Para ver los conjuntos de reglas disponibles, abra el cuadro de diálogo Propiedades del proyecto. En el cuadro de diálogo Páginas de propiedades, seleccione la página Propiedades de configuración>Code Analysis>Microsoft. A continuación, abra la lista desplegable en el cuadro combinado Reglas activas para ver los conjuntos de reglas disponibles. Para crear una combinación personalizada de conjuntos de reglas, seleccione Elegir varios conjuntos de reglas. En el cuadro de diálogo Agregar o quitar conjuntos de reglas se enumeran las reglas que se pueden elegir. Para obtener más información sobre el uso de los conjuntos de reglas en Visual Studio, consulte Usar conjuntos de reglas para especificar las reglas de C++ que se van a ejecutar.

Macros

El Comprobador de las C++ Core Guidelines incluye un archivo de encabezado, que define macros que facilitan la supresión de categorías completas de advertencias en el 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

Estas macros corresponden a los conjuntos de reglas y se expanden en una lista separada por espacios de números de advertencia. Mediante el uso de las construcciones pragma adecuadas, se puede configurar el conjunto eficaz de reglas que resulta interesante para un proyecto o una sección de código. En el ejemplo siguiente, el análisis de código advierte solo sobre los modificadores constantes que faltan:

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

Atributos

El compilador de Microsoft C++ tiene compatibilidad limitada con el atributo [[gsl::suppress]]. Se puede usar para suprimir las advertencias sobre las expresiones e instrucciones de bloqueo dentro de las funciones.

// 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;
}

Supresión de análisis mediante las opciones de línea de comandos

En lugar de #pragmas, se pueden usar opciones de línea de comandos en la página de propiedades del archivo para suprimir las advertencias de un proyecto o un único archivo. Por ejemplo, para deshabilitar la advertencia C26400 para un archivo:

1. Haga clic con el botón derecho en el archivo en el Explorador de soluciones y elija Propiedades.

2. En el cuadro de diálogo Páginas de propiedades, seleccione la página Propiedades de configuración>C/C++>Línea de comandos.

3. En el cuadro de edición Opciones adicionales, agregue /wd26400.

Se puede usar la opción de línea de comandos para deshabilitar temporalmente todo el análisis de código de un archivo al especificar /analyze-. Se verá la advertencia D9025 anular '/analyze' con '/analyze-', que le recuerda que volverá a habilitar el análisis de código más adelante.

Habilitar el comprobador de las C++ Core Guidelines en archivos de proyecto específicos

A veces resulta útil realizar análisis de código centrados y seguir usando el IDE de Visual Studio. Pruebe el siguiente escenario de ejemplo para proyectos de gran tamaño. Puede ahorrar tiempo de compilación y facilitar el filtrado de los resultados:

1. En el shell de comandos, establezca la variable de esp.extension entorno.

2. Para heredar esta variable, abra Visual Studio desde el shell de comandos.

3. Cargue el proyecto y abra sus propiedades.

4. Habilite el análisis de código, elija los conjuntos de reglas adecuados, pero no habilite las extensiones de análisis de código.

5. Vaya al archivo que desea analizar con el comprobador de las C++ Core Guidelines y abra sus propiedades.

6. Elija Propiedades de configuración>C/C++>Línea de comandos>Opciones adicionales y agregue /analyze:plugin EspXEngine.dll

7. Deshabilite el uso del encabezado precompilado (Propiedades de configuración>C/C++>Encabezados precompilados). Es necesario porque el motor de extensiones podría intentar leer su información interna del encabezado precompilado (PCH). Si el PCH se compiló con opciones de proyecto predeterminadas, no será compatible.

8. Recompile el proyecto. Las comprobaciones PREFast comunes deben ejecutarse en todos los archivos. Dado que el comprobador de C++ Core Guidelines no está habilitado de forma predeterminada, solo debe ejecutarse en el archivo que está configurado para usarlo.

Cómo usar el comprobador de las C++ Core Guidelines fuera de Visual Studio

Se pueden usar las comprobaciones de las C++ Core Guidelines en compilaciones automatizadas.

MSBuild

El comprobador del Code Analysis nativo (PREfast) se integra en el entorno de MSBuild mediante archivos de destinos personalizados. Se pueden usar las propiedades del proyecto para habilitarla y agregar el comprobador de las C++ Core Guidelines (que se basa en PREfast):

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

Asegúrese de agregar estas propiedades antes de la importación del archivo Microsoft.Cpp.targets. Se pueden elegir conjuntos de reglas específicos o crear un conjunto de reglas personalizado. O bien, use el conjunto de reglas predeterminado que incluye otras comprobaciones PREfast.

Se puede ejecutar el C++ Core Check solo en los archivos especificados. Use el mismo enfoque que se describió anteriormente, pero use archivos de MSBuild. Las variables de entorno se pueden establecer mediante el elemento BuildMacro:

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

Si no desea modificar el archivo del proyecto, puede pasar propiedades en la línea de comandos:

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

Proyectos que no son de MSBuild

Si se usa un sistema de compilación que no se basa en MSBuild, todavía se puede ejecutar el comprobador. Para usarlo, debe familiarizarse con algunos elementos internos de la configuración del motor de Code Analysis. No garantizamos la compatibilidad con estos elementos internos en versiones futuras de Visual Studio.

Code Analysis requiere algunas variables de entorno y opciones de línea de comandos del compilador. Se recomienda usar el entorno del símbolo del sistema de herramientas nativas para que no se tengan que buscar las rutas de acceso específicas para el compilador, incluir directorios, etc.

• Variables de entorno

  • set esp.extensions=cppcorecheck.dll Esto indica al motor que cargue el módulo de las C++ Core Guidelines.
  • Desde Visual Studio 2019 ya no se recomienda establecer la esp.annotationbuildlevel variable de entorno porque establecerla puede dar lugar a falsos positivos. Si ve resultados inesperados, quite esta variable del entorno.
  • set caexcludepath=%include% Es muy recomendable deshabilitar las advertencias que se activan en los encabezados estándar. Se pueden agregar más rutas de acceso aquí, por ejemplo, la ruta de acceso a los encabezados comunes del proyecto.

• Opciones de la línea de comandos

  • /analyze Habilita el análisis de código (considere también el uso de /analyze:only y /analyze:quiet).
  • /analyze:plugin EspXEngine.dll Esta opción carga el motor de las extensiones de Code Analysis en PREfast. Este motor, a su vez, carga el comprobador de las C++ Core Guidelines.

Uso de la biblioteca de soporte técnico de directrices

La biblioteca de soporte técnico de directrices (GSL) está diseñada para ayudarle a seguir las directrices básicas. El GSL incluye definiciones que permiten reemplazar construcciones propensas a errores por alternativas más seguras. Por ejemplo, se puede reemplazar un par T*, length de parámetros por el tipo span<T>. El proyecto GSL está disponible en GitHub en https://github.com/Microsoft/GSL. La biblioteca es de código abierto, por lo que puede ver los orígenes, hacer comentarios o contribuir. También se puede usar el administrador de paquetes vcpkg para descargar e instalar la biblioteca localmente.

Consulte también

• Referencia de C++ Core Check de Visual Studio