Utiliser les vérificateurs de C++ Core Guidelines

Les recommandations de base C++ sont un ensemble portable de recommandations, de règles et de bonnes pratiques sur le codage en C++ créé par des experts et concepteurs C++. Visual Studio prend actuellement en charge un sous-ensemble de ces règles dans le cadre de ses outils d’analyse de code pour C++. Les vérificateurs de recommandations de base sont installés par défaut dans Visual Studio 2017 et Visual Studio 2019. Ils sont disponibles en tant que package NuGet pour Visual Studio 2015.

Projet de recommandations de base C++

Créés par Bjarne Stroustrup et d’autres, les instructions de base C++ sont un guide pour utiliser C++ moderne en toute sécurité et efficacement. Les instructions mettent l’accent sur la sécurité des types statiques et la sécurité des ressources. Ils identifient les façons d’éliminer ou de réduire les parties les plus sujettes aux erreurs de la langue. Ils suggèrent également comment rendre votre code plus simple, plus fiable et avoir de meilleures performances. Ces instructions sont conservées par la Fondation C++ Standard. Pour en savoir plus, consultez la documentation, C++ Core Guidelines et accédez aux fichiers projet de documentation des instructions C++ Core sur GitHub.

Activer les instructions de vérification de base C++ dans l’analyse du code

Un sous-ensemble de règles de vérification de base C++ est inclus dans l’ensemble de règles recommandées par Microsoft Native. Il s’agit du jeu de règles qui s’exécute par défaut lorsque l’analyse du code Microsoft est activée.

Pour activer l’analyse du code sur votre projet :

1. Ouvrez le dialogue Pages de propriétés du projet.

2. Sélectionnez la page de propriétés d’analyse du code de>configuration.

3. Définissez les propriétés Activer l’analyse du code sur build et activer Microsoft Code Analysis .

Vous pouvez également choisir d’exécuter toutes les règles C++ Core Check prises en charge, ou sélectionner votre propre sous-ensemble à exécuter :

Pour activer davantage de règles Core Check

1. Ouvrez le dialogue Pages de propriétés du projet.

2. Sélectionnez la page de propriétés de configuration>Analyse>du code Microsoft.

3. Ouvrez la liste déroulante Règles actives et sélectionnez Choisir plusieurs ensembles de règles.

4. Dans la boîte de dialogue Ajouter ou supprimer des ensembles de règles, choisissez les ensembles de règles à inclure.

Exemples

Voici un exemple de quelques-uns des problèmes que les règles de vérification de base C++ peuvent trouver :

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

Cet exemple illustre quelques-uns des avertissements que les règles de vérification principale C++ peuvent trouver :

• C26494 est la règle Type.5 : Initialise toujours un objet.

• C26485 est la règle Bounds.3 : aucune décomposition de tableau à pointeur.

• C26481 est la règle Bounds.1 : n’utilisez pas l’arithmétique du pointeur. Utilisez span à la place.

Installez et activez les ensembles de règles d’analyse de code C++ Core Check, puis compilez ce code. L’analyse du code génère les deux premiers avertissements et supprime le troisième. Voici la sortie de build de l’exemple de code dans 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 ==========

Les instructions de base C++ sont là pour vous aider à écrire du code mieux et plus sûr. Toutefois, vous pouvez trouver une instance où une règle ou un profil ne doit pas être appliqué. Il est facile de le supprimer directement dans le code. Vous pouvez utiliser l’attribut [[gsl::suppress]] pour empêcher C++ Core Check de détecter et de signaler toute violation d’une règle dans le bloc de code suivant. Vous pouvez marquer des instructions individuelles pour supprimer des règles spécifiques. Vous pouvez même supprimer l’intégralité du profil de limites en écrivant [[gsl::suppress(bounds)]] sans inclure un numéro de règle spécifique.

Ensembles de règles pris en charge

À mesure que de nouvelles règles sont ajoutées au vérificateur des instructions principales C++, le nombre d’avertissements générés pour le code préexistant peut augmenter. Vous pouvez utiliser des ensembles de règles prédéfinis pour filtrer les types de règles à activer. Vous trouverez des articles de référence pour la plupart des règles sous Visual Studio C++ Core Check Reference.

• Règles arithmétiques : règles pour détecter le dépassement arithmétique, les opérations signées non signées et la manipulation de bits.^15.6

• Règles de limites : appliquez le profil Limites des instructions de base C++.^15.3

• Règles de classe : quelques règles qui se concentrent sur l’utilisation appropriée des fonctions membres spéciales et des spécifications virtuelles. Il s’agit d’un sous-ensemble des vérifications recommandées pour les classes et les hiérarchies de classes.^15.5

• Règles d’accès concurrentiel : règle unique, qui intercepte les déclarations d’objets de protection incorrectes. Pour plus d’informations, consultez les instructions relatives à la concurrence.^15.5

• Règles const : appliquez des vérifications liées à const à partir des instructions de base C++.^15.3

• Règles de déclaration : deux règles des instructions d’interfaces qui se concentrent sur la façon dont les variables globales sont déclarées.^15.5

• Règles d’énumération : ces règles appliquent des vérifications liées à l’énumération à partir des instructions de base C++.^16.3

• Les règles expérimentales sont des règles de vérification de base C++ expérimentales qui sont utiles, mais qui ne sont pas prêtes pour une utilisation quotidienne. Essayez-les et fournissez des commentaires.^16.0

• Règles de fonction : deux vérifications qui aident à l’adoption du noexcept spécificateur. Ils font partie des instructions relatives à la conception et à l’implémentation claires des fonctions.^15.5

• Règles GSL : ces règles appliquent des vérifications liées à la bibliothèque de prise en charge des instructions à partir des instructions principales C++.^15.7

• Règles de durée de vie : ces règles appliquent le profil de durée de vie des instructions de base C++.^15.7

• Règles de pointeur de propriétaire : appliquez les vérifications de gestion des ressources liées au propriétaire<T> à partir des instructions de base C++.^15.3

• Règles de pointeur brutes : appliquez des vérifications de gestion des ressources liées aux pointeurs bruts à partir des instructions de base C++.^15.3

• Règles de pointeur partagé : elle fait partie de l’application des directives de gestion des ressources.^15.5 Nous avons ajouté quelques règles spécifiques à la façon dont les pointeurs partagés sont passés dans des fonctions ou utilisés localement.

• Règles STL : ces règles appliquent des vérifications liées à la bibliothèque standard C++ (STL) à partir des instructions de base C++.^15.7

• Règles de style : une vérification simple mais importante, qui interdit l’utilisation de goto.^15.5 Il s’agit de la première étape pour améliorer votre style de codage et l’utilisation d’expressions et d’instructions en C++.

• Règles de type : appliquez le profil de type des instructions de base C++.^15.3

• Règles de pointeur uniques : appliquez des vérifications de gestion des ressources liées aux types avec une sémantique de pointeur unique à partir des instructions principales C++.^15.3

• Règles de vérification de base C++ : cet ensemble de règles contient toutes les vérifications actuellement implémentées à partir des instructions de base C++, à l’exception des règles expérimentales.

^15.3 Ces règles sont d’abord apparues dans Visual Studio 2017 version 15.3
^15.5 Ces règles sont d’abord apparues dans Visual Studio 2017 version 15.5
^15.6 Ces règles sont d’abord apparues dans Visual Studio 2017 version 15.6
^15.7 Ces règles sont d’abord apparues dans Visual Studio 2017 version 15.7
^16.0 Ces règles sont d’abord apparues dans Visual Studio 2019 version 16.0
^16.3 Ces règles apparaissent d’abord dans Visual Studio 2019 version 16.3

Vous pouvez choisir de limiter les avertissements à un ou plusieurs des groupes. Les ensembles de règles minimum et natif recommandés incluent les règles C++ Core Check et d’autres vérifications PREfast.

Pour afficher les ensembles de règles disponibles, ouvrez la boîte de dialogue Propriétés du projet. Dans la boîte de dialogue Pages de propriétés, sélectionnez la page de propriétés de configuration>Analyse>du code Microsoft. Ensuite, ouvrez la liste déroulante dans la zone de liste déroulante Règles actives pour afficher les ensembles de règles disponibles. Pour créer une combinaison personnalisée de jeux de règles, sélectionnez Choisir plusieurs ensembles de règles. La boîte de dialogue Ajouter ou supprimer des ensembles de règles répertorie les règles parmi lesquelles vous pouvez choisir. Pour plus d’informations sur l’utilisation des ensembles de règles dans Visual Studio, consultez Utiliser des ensembles de règles pour spécifier les règles C++ à exécuter.

Macros

Le vérificateur des instructions principales C++ est fourni avec un fichier d’en-tête, qui définit des macros qui facilitent la suppression des catégories entières d’avertissements dans le code :

ALL_CPPCORECHECK_WARNINGS
CPPCORECHECK_TYPE_WARNINGS
CPPCORECHECK_RAW_POINTER_WARNINGS
CPPCORECHECK_CONST_WARNINGS
CPPCORECHECK_OWNER_POINTER_WARNINGS
CPPCORECHECK_UNIQUE_POINTER_WARNINGS
CPPCORECHECK_BOUNDS_WARNINGS

Ces macros correspondent aux ensembles de règles et s’étendent dans une liste séparée par des espaces de numéros d’avertissement. En utilisant les constructions pragma appropriées, vous pouvez configurer l’ensemble effectif de règles intéressantes pour un projet ou une section de code. Dans l’exemple suivant, l’analyse du code avertit uniquement les modificateurs de constante manquants :

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

Attributs

Le compilateur Microsoft C++ a une prise en charge limitée de l’attribut [[gsl::suppress]] . Il peut être utilisé pour supprimer des avertissements sur les instructions d’expression et de bloc à l’intérieur des fonctions.

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

Supprimer l’analyse à l’aide des options de ligne de commande

Au lieu de #pragmas, vous pouvez utiliser des options de ligne de commande dans la page de propriétés du fichier pour supprimer les avertissements d’un projet ou d’un seul fichier. Par exemple, pour désactiver l’avertissement C26400 pour un fichier :

1. Cliquez avec le bouton droit sur le fichier dans Explorateur de solutions, puis choisissez Propriétés.

2. Dans la boîte de dialogue Pages de propriétés, sélectionnez la page de propriétés de la> ligne de commande C/C++>Configuration.

3. Dans la zone d’édition Options supplémentaires, ajoutez /wd26400.

Vous pouvez utiliser l’option de ligne de commande pour désactiver temporairement toutes les analyses de code d’un fichier en spécifiant /analyze-. Vous verrez l’avertissement D9025 en remplaçant « /analyze » par « /analyze », ce qui vous rappelle de réactiver l’analyse du code ultérieurement.

Activer le vérificateur des instructions principales C++ sur des fichiers projet spécifiques

Parfois, il est utile d’effectuer une analyse de code axée et d’utiliser l’IDE Visual Studio. Essayez l’exemple de scénario suivant pour les projets volumineux. Il peut gagner du temps de génération et faciliter le filtrage des résultats :

1. Dans l’interpréteur de commandes, définissez la variable d’environnement esp.extension .

2. Pour hériter de cette variable, ouvrez Visual Studio à partir de l’interpréteur de commandes.

3. Chargez votre projet et ouvrez ses propriétés.

4. Activez l’analyse du code, choisissez les ensembles de règles appropriés, mais n’activez pas les extensions d’analyse du code.

5. Accédez au fichier que vous souhaitez analyser avec le Vérificateur des instructions principales C++ et ouvrez ses propriétés.

6. Choisir les propriétés>de configuration C/C++>Options supplémentaires de ligne>de commande et ajouter/analyze:plugin EspXEngine.dll

7. Désactivez l’utilisation de l’en-tête précompilé (Propriétés>de configuration C/C++>En-têtes précompilés). Il est nécessaire, car le moteur d’extensions peut tenter de lire ses informations internes à partir de l’en-tête précompilé (PCH). Si le PCH a été compilé avec les options de projet par défaut, il n’est pas compatible.

8. Regénérez le projet. Les vérifications PREFast courantes doivent s’exécuter sur tous les fichiers. Étant donné que le vérificateur des instructions de base C++ n’est pas activé par défaut, il ne doit s’exécuter que sur le fichier configuré pour l’utiliser.

Guide pratique pour utiliser le vérificateur des instructions principales C++ en dehors de Visual Studio

Vous pouvez utiliser les vérifications des instructions principales C++ dans les builds automatisées.

MSBuild

Le vérificateur d’analyse du code natif (PREfast) est intégré à l’environnement MSBuild par des fichiers cibles personnalisés. Vous pouvez utiliser les propriétés du projet pour l’activer et ajouter le vérificateur des instructions principales C++ (basé sur PREfast) :

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

Veillez à ajouter ces propriétés avant l’importation du Microsoft.Cpp.targets fichier. Vous pouvez choisir des ensembles de règles spécifiques ou créer un ensemble de règles personnalisé. Vous pouvez également utiliser l’ensemble de règles par défaut qui inclut d’autres vérifications PREfast.

Vous pouvez exécuter le vérificateur principal C++ uniquement sur les fichiers spécifiés. Utilisez la même approche que celle décrite précédemment, mais utilisez les fichiers MSBuild. Les variables d’environnement peuvent être définies à l’aide de l’élément BuildMacro :

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

Si vous ne souhaitez pas modifier le fichier projet, vous pouvez transmettre des propriétés sur la ligne de commande :

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

Projets non MSBuild

Si vous utilisez un système de build qui ne s’appuie pas sur MSBuild, vous pouvez toujours exécuter le vérificateur. Pour l’utiliser, vous devez vous familiariser avec certains éléments internes de la configuration du moteur d’analyse du code. Nous ne garantissons pas la prise en charge de ces éléments internes dans les futures versions de Visual Studio.

L’analyse du code nécessite quelques variables d’environnement et options de ligne de commande du compilateur. Nous vous recommandons d’utiliser l’environnement d’invite de commandes Native Tools afin de ne pas avoir à rechercher des chemins spécifiques pour le compilateur, inclure des répertoires, et ainsi de suite.

• Variables d’environnement

  • set esp.extensions=cppcorecheck.dll Cela indique au moteur de charger le module Instructions principales C++.
  • Depuis Visual Studio 2019, nous vous déconseillons de définir la esp.annotationbuildlevel variable d’environnement, car elle peut entraîner des faux positifs. Si vous voyez des résultats inattendus, supprimez cette variable de votre environnement.
  • set caexcludepath=%include% Nous vous recommandons vivement de désactiver les avertissements qui se déclenchent sur les en-têtes standard. Vous pouvez ajouter d’autres chemins ici, par exemple le chemin d’accès aux en-têtes courants dans votre projet.

• Options de ligne de commande

  • /analyze Active l’analyse du code (envisagez également d’utiliser /analyze:only et /analyze:quiet).
  • /analyze:plugin EspXEngine.dll Cette option charge le moteur Des extensions d’analyse du code dans prEfast. Ce moteur charge, à son tour, le vérificateur des instructions de base C++.

Utiliser la bibliothèque de prise en charge des instructions

La bibliothèque de prise en charge des recommandations (GSL) est conçue pour vous aider à suivre les instructions principales. Le fichier GSL inclut des définitions qui vous permettent de remplacer les constructions sujettes aux erreurs par des alternatives plus sûres. Par exemple, vous pouvez remplacer une T*, length paire de paramètres par le span<T> type. Le projet GSL est disponible sur GitHub à l’adresse https://github.com/Microsoft/GSL. La bibliothèque est open source, ce qui vous permet d’afficher les sources, de faire des commentaires ou de contribuer. Vous pouvez également utiliser le gestionnaire de package vcpkg pour télécharger et installer la bibliothèque localement.

Voir aussi

• Informations de référence sur la vérification principale de Visual Studio C++