Použití kontrolních mechanismů C++ Core Guidelines

C++ Core Guidelines je přenosná sada pokynů, pravidel a osvědčených postupů pro kódování v jazyce C++ vytvořených odborníky a návrháři jazyka C++. Visual Studio v současné době podporuje podmnožinu těchto pravidel jako součást nástrojů Microsoft C++ Code Analysis Tools. Základní nástroje pro kontrolu obecných zásad se ve výchozím nastavení instalují v sadě Visual Studio 2017 a Visual Studio 2019. Jsou k dispozici jako balíček NuGet pro Visual Studio 2015.

Projekt C++ Core Guidelines

Vytvořili jsme Bjarne Stroustrup a další, pokyny pro C++ Core Guidelines jsou vodítkem k bezpečnému a efektivnímu používání moderního jazyka C++. Pokyny zvýrazňují bezpečnost statického typu a bezpečnost prostředků. Identifikují způsoby, jak eliminovat nebo minimalizovat nejvíce náchylné k chybám částí jazyka. Také navrhují, jak zjednodušit, spolehlivější a výkon vašeho kódu. Tyto pokyny spravuje standard C++ Foundation. Další informace najdete v dokumentaci, pokynech pro C++ Core Guidelines a přístup k souborům projektu dokumentace C++ Core Guidelines na GitHubu.

Povolení pokynů pro kontrolu jádra C++ v analýze kódu

Podmnožina pravidel kontroly jádra C++ je součástí sady pravidel Microsoft Native Recommended. Je to sada pravidel, která se spouští ve výchozím nastavení, když je povolená analýza kódu Microsoftu.

Povolení analýzy kódu v projektu

1. Otevřete dialogové okno Stránky vlastností projektu.

2. Vyberte stránku vlastností analýzy kódu konfigurace>.

3. Nastavte možnost Povolit analýzu kódu při sestavení a povolte vlastnosti analýzy kódu společnosti Microsoft.

Můžete také zvolit spuštění všech podporovaných pravidel kontroly jádra C++ nebo můžete vybrat vlastní podmnožinu, kterou chcete spustit:

Umožnit více pravidel Core Check

1. Otevřete dialogové okno Stránky vlastností projektu.

2. Vyberte stránku vlastností Analýzy kódu konfigurace

3. Otevřete rozevírací seznam Aktivní pravidla a vyberte Vybrat více sad pravidel.

4. V dialogovém okně Přidat nebo odebrat sady pravidel zvolte, které sady pravidel chcete zahrnout.

Příklady

Tady je příklad některých problémů, které můžou najít pravidla kontroly jádra C++:

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

Tento příklad ukazuje několik upozornění, která můžou najít pravidla kontroly jádra C++:

• C26494 je pravidlo Type.5: Vždy inicializujte objekt.

• C26485 je pravidlo Bounds.3: Bez rozpadu pole na ukazatel.

• C26481 je pravidlo Bounds.1: Nepoužívejte aritmetické aritmetické ukazatele. Místo toho použijte span.

Nainstalujte a povolte sady pravidel analýzy kódu C++ Core a pak tento kód zkompilujte. Analýza kódu vypíše první dvě upozornění a potlačí třetí. Tady je výstup sestavení z ukázkového kódu v sadě 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 ==========

K dispozici jsou pokyny pro C++ Core Guidelines, které vám pomůžou psát lepší a bezpečnější kód. Můžete ale najít instanci, ve které by se nemělo použít pravidlo nebo profil. Je snadné ho potlačit přímo v kódu. Atribut můžete použít [[gsl::suppress]] k tomu, aby nástroj C++ Core Check detekoval a hlásil jakékoli porušení pravidla v následujícím bloku kódu. Můžete označit jednotlivé příkazy, které potlačí konkrétní pravidla. Celý profil hranic můžete dokonce potlačit zápisem [[gsl::suppress("bounds")]] bez zahrnutí konkrétního čísla pravidla.

Podporované sady pravidel

Při přidání nových pravidel do nástroje C++ Core Guidelines Checker se může zvýšit počet upozornění generovaných pro již existující kód. Pomocí předdefinovaných sad pravidel můžete filtrovat, které typy pravidel se mají povolit. Referenční články pro většinu pravidel najdete v části Visual Studio C++ Core Check Reference.

• Aritmetická pravidla: Pravidla pro detekci aritmetického přetečení, operace se znaménkem a bez znaménka, a bitové manipulace.^15.6

• Pravidla hranic: Vynucujte profil hranic základních pokynů jazyka C++.^15.3

• Pravidla třídy: Několik pravidel, která se zaměřují na správné použití speciálních členských funkcí a virtuálních specifikací. Jedná se o podmnožinu kontrol doporučených pro třídy a hierarchie tříd.^15.5

• Pravidla souběžného zpracování: Jedno pravidlo, které zachycuje špatné deklarace objektu ochrany. Další informace najdete v pokynech týkajících se souběžnosti.^15.5

• Pravidla const: Vynucujte kontroly související s const z pokynů C++ Core Guidelines.^15.3

• Pravidla deklarace: Několik pravidel z pokynů rozhraní, která se zaměřují na způsob deklarace globálních proměnných.^15.5

• Pravidla pro výčty: Tato pravidla vynucují kontroly týkající se výčtů z C++ Core Guidelines.^16.3

• Experimentální pravidla Jsou to experimentální pravidla kontroly C++ Core, která jsou užitečná, ale nejsou připravená pro každodenní použití. Vyzkoušejte si je a poskytněte nám svůj názor.^16.0

• Pravidla funkce: Dvě kontroly, které pomáhají s přijetím specifikátoru noexcept . Jsou součástí pokynů pro jasný návrh a implementaci funkcí.^15.5

• Pravidla GSL: Tato pravidla vynucují kontroly související s knihovnou podpory pokynů z C++ Core Guidelines.^15.7

• Pravidla životnosti: Tato pravidla vynucují profil životnosti pravidel C++ Core Guidelines.^15.7

• PRAVIDLA pro ukazatel vlastníka: Vynucujte kontroly správy prostředků související s vlastníkem<T> z C++ Core Guidelines.^15.3

• Nezpracovaná pravidla ukazatele: Vynucujte kontroly správy prostředků související s nezpracovaným ukazateli z pokynů C++ Core Guidelines.^15.3

• Pravidla pro sdílené ukazatele: Jsou součástí prosazování zásad řízení prostředků.15.5 Přidali jsme několik pravidel specifických pro to, jak se sdílené ukazatele předávají do funkcí nebo se používají lokálně.

• Pravidla STL: Tato pravidla vynucují kontroly související se standardní knihovnou C++ (STL) z C++ Core Guidelines.^15.7

• Pravidla stylu: Jedna jednoduchá, ale důležitá kontrola, která zakáže použití goto.^15.5 Je prvním krokem ke zlepšení stylu kódování a použití výrazů a příkazů v jazyce C++.

• Pravidla typů: Vynucujte profil typu pokynů pro C++ Core.^15.3

• Pravidla jedinečných ukazatelů: Vynucujte kontroly správy prostředků související s typy s jedinečnou sémantikou ukazatele z pokynů pro C++ Core Guidelines.^15.3

• Pravidla kontroly jádra C++: Tato sada pravidel obsahuje všechny aktuálně implementované kontroly z pravidel C++ Core Guidelines s výjimkou experimentálních pravidel.

^15.3 Tato pravidla se poprvé objevila ve verzi 15.3 sady Visual Studio 2017
^15.5 Tato pravidla se poprvé objevila v sadě Visual Studio 2017 verze 15.5
^15.6 Tato pravidla se poprvé objevila v sadě Visual Studio 2017 verze 15.6
^15.7 Tato pravidla se poprvé objevila v sadě Visual Studio 2017 verze 15.7
^16.0 Tato pravidla se poprvé objevila v aplikaci Visual Studio 2019 Verze 16.0
^16.3 Tato pravidla se poprvé objevila ve Visual Studio 2019 verze 16.3

Můžete se rozhodnout omezit upozornění jenom na jednu nebo několik skupin. Nativní minimální a nativní doporučené sady pravidel zahrnují pravidla kontroly C++ Core a další kontroly PREfast.

Pokud chcete zobrazit dostupné sady pravidel, otevřete dialogové okno Vlastnosti projektu. V dialogovém okně Stránky vlastností vyberte Vlastnosti konfigurace>Analýza kódu>Microsoftu. Potom otevřete rozevírací seznam v kombinovaném poli Aktivní pravidla, aby se zobrazily dostupné sady pravidel. Pokud chcete vytvořit vlastní kombinaci sad pravidel, vyberte Vybrat více sad pravidel. Dialogové okno Přidat nebo odebrat sady pravidel obsahuje seznam pravidel, ze které si můžete vybrat. Další informace o používání sad pravidel v sadě Visual Studio naleznete v tématu Použití sad pravidel k určení pravidel jazyka C++, která se mají spustit.

Makra

Nástroj C++ Core Guidelines Checker obsahuje soubor hlaviček, který definuje makra, která usnadňují potlačení celých kategorií upozornění v kódu:

ALL_CPPCORECHECK_WARNINGS
CPPCORECHECK_TYPE_WARNINGS
CPPCORECHECK_RAW_POINTER_WARNINGS
CPPCORECHECK_CONST_WARNINGS
CPPCORECHECK_OWNER_POINTER_WARNINGS
CPPCORECHECK_UNIQUE_POINTER_WARNINGS
CPPCORECHECK_BOUNDS_WARNINGS

Tato makra odpovídají sadám pravidel a rozšiřují seznam čísel upozornění oddělených mezerami. Pomocí vhodných konstruktorů pragma můžete nakonfigurovat efektivní sadu pravidel, která jsou zajímavá pro projekt nebo oddíl kódu. V následujícím příkladu analýza kódu varuje pouze o chybějících modifikátorech konstant:

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

Atributy

Kompilátor Jazyka Microsoft C++ má pro atribut omezenou podporu [[gsl::suppress]] . Může být použit k potlačení varování u výrazů a blokových příkazů uvnitř funkcí.

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

Potlačení analýzy pomocí možností příkazového řádku

Místo #pragmas můžete pomocí možností příkazového řádku na stránce vlastností souboru potlačit upozornění pro projekt nebo jeden soubor. Pokud chcete například zakázat upozornění C26400 pro soubor:

1. Klikněte pravým tlačítkem myši na soubor v Průzkumník řešení a zvolte Vlastnosti.

2. V dialogovém okně Stránky vlastností vyberte stránku vlastností Konfigurační vlastnosti>C/C++>Příkazový řádek.

3. Do textového pole Další možnosti přidejte /wd26400.

Pomocí možnosti příkazového řádku můžete dočasně zakázat všechny analýzy kódu pro soubor zadáním /analyze-. Zobrazí se upozornění D9025 přenastavení /analyze na /analyze-, které vám připomene, abyste později znovu povolili analýzu kódu.

Povolení nástroje C++ Core Guidelines Checker pro konkrétní soubory projektu

Někdy je užitečné provádět zaměřenou analýzu kódu a stále používat integrované vývojové prostředí sady Visual Studio. Vyzkoušejte následující ukázkový scénář pro velké projekty. Může ušetřit čas sestavení a usnadnit filtrování výsledků:

1. V příkazovém prostředí nastavte proměnnou esp.extension prostředí.

2. Pokud chcete tuto proměnnou dědit, otevřete visual Studio z příkazového prostředí.

3. Načtěte projekt a otevřete jeho vlastnosti.

4. Povolte analýzu kódu, vyberte odpovídající sady pravidel, ale nepovolujte rozšíření analýzy kódu.

5. Přejděte k souboru, který chcete analyzovat pomocí nástroje C++ Core Guidelines Checker, a otevřete jeho vlastnosti.

6. Zvolte Vlastnosti>konfigurace C/C++>Další možnosti příkazového řádku>a přidejte/analyze:plugin EspXEngine.dll

7. Zakažte použití předkompilované hlavičky (>Předkompilované hlavičky). Je nutné, protože modul rozšíření se může pokusit přečíst své interní informace z předkompilované hlavičky (PCH). Pokud byl PCH zkompilován s výchozími možnostmi projektu, nebude kompatibilní.

8. Znovu sestavte projekt. Běžné kontroly PREFast by se měly spouštět na všech souborech. Vzhledem k tomu, že nástroj C++ Core Guidelines Checker není ve výchozím nastavení povolený, měl by běžet jenom na souboru, který je nakonfigurovaný tak, aby ho používal.

Jak používat nástroj C++ Core Guidelines Checker mimo Visual Studio

Kontroly C++ Core Guidelines můžete použít v automatizovaných buildech.

MSBuild

Kontrola nativní analýzy kódu (PREfast) je integrovaná do prostředí MSBuild vlastními cílovými soubory. Vlastnosti projektu můžete použít k jeho povolení a přidat nástroj C++ Core Guidelines Checker (který je založený na prEfast):

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

Před importem Microsoft.Cpp.targets souboru nezapomeňte tyto vlastnosti přidat. Můžete vybrat konkrétní sady pravidel nebo vytvořit vlastní sadu pravidel. Nebo použijte výchozí sadu pravidel, která obsahuje další kontroly PREfast.

Nástroj C++ Core Checker můžete spustit pouze u zadaných souborů. Použijte stejný přístup, jak je popsáno výše, ale použijte soubory MSBuild. Proměnné prostředí lze nastavit pomocí BuildMacro položky:

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

Pokud nechcete upravovat soubor projektu, můžete předat vlastnosti na příkazovém řádku:

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

Projekty jiné než MSBuild

Pokud používáte systém sestavení, který nespoléhá na MSBuild, můžete spustit kontrolu. Abyste ho mohli použít, musíte se seznámit s některými interními informacemi o konfiguraci modulu analýzy kódu. Neposkytujeme záruku podpory těchto interních prvků v budoucích verzích Visual Studio.

Analýza kódu vyžaduje několik proměnných prostředí a možností příkazového řádku kompilátoru. Doporučujeme použít prostředí příkazového řádku nativních nástrojů, abyste nemuseli hledat konkrétní cesty pro kompilátor, zahrnout adresáře atd.

• Proměnné prostředí

  • set esp.extensions=cppcorecheck.dll Toto říká enginu, aby načetl modul C++ Core Guidelines.
  • Od Visual Studio 2019 už nedoporučujeme nastavit esp.annotationbuildlevel proměnnou prostředí, protože to může vést k falešným pozitivům. Pokud se zobrazí neočekávané výsledky, odeberte tuto proměnnou z vašeho prostředí.
  • set caexcludepath=%include% Důrazně doporučujeme zakázat upozornění, která se objevují na standardních záhlavích. Tady můžete přidat další cesty, například cestu k běžným záhlavím v projektu.

• Možnosti příkazového řádku

  • /analyze Umožňuje analýzu kódu (zvažte také použití /analyze:only a /analyze:quiet).
  • /analyze:plugin EspXEngine.dll Tato možnost načte modul Rozšíření analýzy kódu do PREfast. Tento motor zase načte nástroj C++ Core Guidelines Checker.

Použití knihovny podpory pokynů

Knihovna GSL (Guidelines Support Library) je navržená tak, aby vám pomohla postupovat podle základních pokynů. GSL obsahuje definice, které umožňují nahradit konstruktory náchylné k chybám bezpečnějšími alternativami. Můžete například nahradit T*, length dvojici parametrů typem span<T> . Projekt GSL je k dispozici na GitHubu na adrese https://github.com/Microsoft/GSL. Knihovna je opensourcová, takže můžete zobrazit zdroje, vytvářet komentáře nebo přispívat. Můžete také použít správce balíčků vcpkg ke stažení a instalaci knihovny místně.

Viz také

• Referenční dokumentace ke kontrole Core v programu Visual Studio C++