Använda kontrollverktygen för C++ Core Guidelines

C++ Core Guidelines är en bärbar uppsättning riktlinjer, regler och metodtips för kodning i C++ som skapats av C++-experter och designers. Visual Studio stöder för närvarande en delmängd av dessa regler som en del av dess kodanalysverktyg för C++. De grundläggande riktlinjekontrollerna installeras som standard i Visual Studio 2017 och Visual Studio 2019. De är tillgängliga som ett NuGet-paket för Visual Studio 2015.

C++ Core Guidelines-projektet

C++ Core Guidelines har skapats av Bjarne Stroustrup och andra och är en guide till att använda modern C++ på ett säkert och effektivt sätt. Riktlinjerna betonar säkerhet av statisk typ och resurssäkerhet. De identifierar sätt att eliminera eller minimera de mest felbenägna delarna av språket. De föreslår också hur du gör koden enklare, mer tillförlitlig och får bättre prestanda. Dessa riktlinjer upprätthålls av Standard C++ Foundation. Mer information finns i dokumentationen, C++ Core Guidelines och få åtkomst till projektfilerna för C++ Core Guidelines-dokumentationen på GitHub.

Aktivera riktlinjerna för C++ Core Check i kodanalys

En delmängd av C++ Core Check-regler ingår i microsofts interna rekommenderade regeluppsättning. Det är regeluppsättningen som körs som standard när Microsofts kodanalys är aktiverad.

Så här aktiverar du kodanalys i projektet:

1. Öppna dialogrutan Egenskapssidor för projektet.

2. Välj egenskapssidan Konfigurationsegenskaper>Kodanalys.

3. Ange egenskaperna Aktivera kodanalys på Build och Aktivera Microsoft Code Analysis .

Du kan också välja att köra alla C++ Core Check-regler som stöds eller välja din egen delmängd som ska köras:

Så här aktiverar du fler Core Check-regler

1. Öppna dialogrutan Egenskapssidor för projektet.

2. Välj egenskapssidan Configuration Properties>Code Analysis>Microsoft .

3. Öppna listrutan Aktiva regler och välj Välj flera regeluppsättningar.

4. I dialogrutan Lägg till eller ta bort regeluppsättningar väljer du vilka regeluppsättningar du vill inkludera.

Exempel

Här är ett exempel på några av de problem som C++ Core Check-reglerna kan hitta:

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

Det här exemplet visar några av de varningar som C++ Core Check-reglerna kan hitta:

• C26494 är regeltyp.5: Initiera alltid ett objekt.

• C26485 är regeln Bounds.3: Ingen matris-till-pekare-sönderfall.

• C26481 är regelgräns.1: Använd inte pekarearitmetik. Använd span i stället.

Installera och aktivera kodanalysregleruppsättningarna C++ Core Check och kompilera sedan den här koden. Kodanalysen matar ut de två första varningarna och undertrycker den tredje. Här är byggutdata från exempelkoden i 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 ==========

Riktlinjerna för C++ Core finns där för att hjälpa dig att skriva bättre och säkrare kod. Du kan dock hitta en instans där en regel eller en profil inte ska tillämpas. Det är enkelt att ignorera det direkt i koden. Du kan använda [[gsl::suppress]] attributet för att förhindra att C++ Core Check identifierar och rapporterar överträdelser av en regel i följande kodblock. Du kan markera enskilda uttalanden för att undertrycka specifika regler. Du kan till och med utelämna hela gränsprofilen genom att skriva [[gsl::suppress("bounds")]] utan att inkludera ett specifikt regelnummer.

Regeluppsättningar som stöds

När nya regler läggs till i C++ Core Guidelines Checker kan antalet varningar som skapas för befintlig kod öka. Du kan använda fördefinierade regeluppsättningar för att filtrera vilka typer av regler som ska aktiveras. Du hittar referensartiklar för de flesta regler under Visual Studio C++ Core Check Reference.

• Aritmetiska regler: Regler för att identifiera aritmetiskt spill, signerade osignerade åtgärder och bitmanipulering. ^15,6

• Gränsregler: Framtvinga gränsprofilen för C++ Core Guidelines. ^15.3

• Klassregler: Några regler som fokuserar på korrekt användning av särskilda medlemsfunktioner och virtuella specifikationer. De är en delmängd av de kontroller som rekommenderas för klasser och klasshierarkier. ^15,5

• Samtidighetsregler: En enda regel som fångar dåliga skyddsobjektdeklarationer. Mer information finns i riktlinjer som rör samtidighet. ^15,5

• Const-regler: Framtvinga const-relaterade kontroller från C++ Core Guidelines. ^15.3

• Deklarationsregler: Ett par regler från gränssnittsriktlinjerna som fokuserar på hur globala variabler deklareras. ^15,5

• Uppräkningsregler: Dessa regler tillämpar uppräkningsrelaterade kontroller från C++ Core Guidelines. ^16.3

• Experimentella regler Dessa är experimentella C++ Core Check-regler som är användbara men inte redo för daglig användning. Prova dem och ge feedback. ^16.0

• Funktionsregler: Två kontroller som hjälper till med implementeringen av noexcept specificeraren. De ingår i riktlinjerna för tydlig funktionsdesign och implementering. ^15,5

• GSL-regler: Dessa regler tillämpar kontroller relaterade till riktlinjernas supportbibliotek från C++ Core Guidelines. ^15,7

• Livslängdsregler: Dessa regler tillämpar livslängdsprofilen för C++ Core-riktlinjerna. ^15,7

• Regler för ägarpekare: Framtvinga resurshanteringskontroller relaterade till ägare<T> från C++ Core-riktlinjerna.^15.3

• Rådataregler: Framtvinga resurshanteringskontroller relaterade till rådata från C++ Core Guidelines. ^15.3

• Regler för delad pekare: Det är en del av tillämpningen av riktlinjerna för resurshantering . ^15.5 Vi har lagt till några regler som är specifika för hur delade pekare skickas till funktioner eller används lokalt.

• STL-regler: Dessa regler framtvingar kontroller relaterade till C++ Standard Library (STL) från C++ Core Guidelines. ^15,7

• Stilregler: En enkel men viktig kontroll, som förbjuder användning av goto. ^15.5 Det är det första steget för att förbättra kodningsstilen och användningen av uttryck och uttryck i C++.

• Typregler: Framtvinga typprofilen för C++ Core-riktlinjerna. ^15.3

• Unika pekarregler: Framtvinga resurshanteringskontroller relaterade till typer med unik pekarsemantik från C++ Core Guidelines. ^15.3

• C++ Core Check Rules: Den här regeluppsättningen innehåller alla för närvarande implementerade kontroller från C++ Core Guidelines, förutom experimentella regler.

^15.3 Dessa regler visades först i Visual Studio 2017 version 15.3
^15.5 Dessa regler visades först i Visual Studio 2017 version 15.5
^15.6 Dessa regler visades först i Visual Studio 2017 version 15.6
^15.7 Dessa regler visades först i Visual Studio 2017 version 15.7
^16.0 Dessa regler visades först i Visual Studio 2019 version 16.0
^16.3 Dessa regler visades först i Visual Studio 2019 version 16.3

Du kan välja att begränsa varningar till bara en eller några av grupperna. De interna lägsta och interna rekommenderade regeluppsättningarna innehåller C++ Core Check-regler och andra PREfast-kontroller.

Om du vill se tillgängliga regeluppsättningar öppnar du dialogrutan Projektegenskaper . I dialogrutan Egenskapssidor väljer du egenskapssidan Konfigurationsegenskaper>Kodanalys>För Microsoft . Öppna sedan listrutan i kombinationsrutan Aktiva regler för att se tillgängliga regeluppsättningar. Om du vill skapa en anpassad kombination av regeluppsättningar väljer du Välj flera regeluppsättningar. I dialogrutan Lägg till eller ta bort regeluppsättningar visas de regler som du kan välja mellan. Mer information om hur du använder regeluppsättningar i Visual Studio finns i Använda regeluppsättningar för att ange vilka C++-regler som ska köras.

Makron

Kontrollverktyget för C++ Core Guidelines levereras med en rubrikfil som definierar makron som gör det enklare att utelämna hela kategorier av varningar i kod:

ALL_CPPCORECHECK_WARNINGS
CPPCORECHECK_TYPE_WARNINGS
CPPCORECHECK_RAW_POINTER_WARNINGS
CPPCORECHECK_CONST_WARNINGS
CPPCORECHECK_OWNER_POINTER_WARNINGS
CPPCORECHECK_UNIQUE_POINTER_WARNINGS
CPPCORECHECK_BOUNDS_WARNINGS

Dessa makron motsvarar regeluppsättningarna och expanderas till en blankstegsavgränsad lista med varningsnummer. Genom att använda lämpliga pragmakonstruktioner kan du konfigurera den effektiva uppsättning regler som är intressanta för ett projekt eller ett kodavsnitt. I följande exempel varnar kodanalysen endast för saknade konstanta modifierare:

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

Egenskaper

Microsoft C++-kompilatorn har begränsat stöd för attributet [[gsl::suppress]] . Den kan användas för att ignorera varningar om uttrycks- och blockinstruktioner i funktioner.

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

Ignorera analys med hjälp av kommandoradsalternativ

I stället för #pragmas kan du använda kommandoradsalternativ på filens egenskapssida för att förhindra varningar för ett projekt eller en enda fil. Om du till exempel vill inaktivera varningen C26400 för en fil:

1. Högerklicka på filen i Solution Explorer och välj Egenskaper.

2. I dialogrutan Egenskapssidor väljer du egenskapssidan Konfigurationsegenskaper>C/C++>Kommandorad .

3. I redigeringsrutan Ytterligare alternativ lägger du till /wd26400.

Du kan använda kommandoradsalternativet för att tillfälligt inaktivera all kodanalys för en fil genom att ange /analyze-. Du ser en varning om att D9025 åsidosätter '/analysera' med '/analyze-', vilket påminner dig om att återaktivera kodanalys senare.

Aktivera C++ Core Guidelines Checker för specifika projektfiler

Ibland är det användbart att göra fokuserad kodanalys och fortfarande använda Visual Studio IDE. Prova följande exempelscenario för stora projekt. Det kan spara byggtid och göra det enklare att filtrera resultat:

1. Ange miljövariabeln i esp.extension kommandogränssnittet.

2. Om du vill ärva den här variabeln öppnar du Visual Studio från kommandogränssnittet.

3. Ladda in projektet och öppna dess egenskaper.

4. Aktivera kodanalys, välj lämpliga regeluppsättningar, men aktivera inte kodanalystillägg.

5. Gå till den fil som du vill analysera med C++ Core Guidelines Checker och öppna dess egenskaper.

6. Välj Konfigurationsegenskaper>C/C++>Kommandorad>ytterligare alternativ och lägg till /analyze:plugin EspXEngine.dll

7. Inaktivera användning av förkompilerat huvud (Konfigurationsegenskaper>C/C++>Förkompilerade rubriker). Det är nödvändigt eftersom tilläggsmodulen kan försöka läsa sin interna information från den förkompilerade headern (PCH). Om PCH kompilerades med standardprojektalternativ är den inte kompatibel.

8. Återskapa projektet. De vanliga PREFast-kontrollerna ska köras på alla filer. Eftersom C++ Core Guidelines Checker inte är aktiverad som standard ska den bara köras på filen som har konfigurerats för att använda den.

Använda C++ Core Guidelines Checker utanför Visual Studio

Du kan använda C++ Core Guidelines-kontrollerna i automatiserade versioner.

MSBuild

Den interna kodanalyskontrollen (PREfast) är integrerad i MSBuild-miljön med anpassade målfiler. Du kan använda projektegenskaper för att aktivera den och lägga till C++ Core Guidelines Checker (som baseras på PREfast):

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

Se till att du lägger till de här egenskaperna innan du importerar Microsoft.Cpp.targets filen. Du kan välja specifika regeluppsättningar eller skapa en anpassad regeluppsättning. Eller använd standardregeluppsättningen som innehåller andra PREfast-kontroller.

Du kan bara köra C++ Core Checker på angivna filer. Använd samma metod som tidigare, men använd MSBuild-filer. Miljövariablerna kan anges med hjälp av objektet BuildMacro :

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

Om du inte vill ändra projektfilen kan du skicka egenskaper på kommandoraden:

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

Icke-MSBuild-projekt

Om du använder ett byggsystem som inte förlitar sig på MSBuild kan du fortfarande köra kontrollen. Om du vill använda den måste du bekanta dig med några interna kodanalysmotorkonfigurationer. Vi garanterar inte stöd för dessa interna objekt i framtida versioner av Visual Studio.

Kodanalys kräver några miljövariabler och kommandoradsalternativ för kompilatorn. Vi rekommenderar att du använder kommandotolken för inbyggda verktyg så att du inte behöver söka efter specifika sökvägar för kompilatorn, inkludera kataloger och så vidare.

• Miljövariabler

  • set esp.extensions=cppcorecheck.dll Detta talar om för motorn att läsa in modulen C++ Core Guidelines.
  • Sedan Visual Studio 2019 rekommenderar vi inte längre att ställa in esp.annotationbuildlevel miljövariabeln, eftersom det kan resultera i falska positiva. Om oväntade resultat visas tar du bort den här variabeln från din miljö.
  • set caexcludepath=%include% Vi rekommenderar starkt att du inaktiverar varningar som utlöses på standardhuvuden. Du kan lägga till fler sökvägar här, till exempel sökvägen till de gemensamma rubrikerna i projektet.

• Kommandoradsalternativ

  • /analyze Aktiverar kodanalys (överväg även att använda /analyze:only och /analyze:quiet).
  • /analyze:plugin EspXEngine.dll Det här alternativet läser in motorn för kodanalystillägg i PREfast. Den här motorn laddar C++ Core Guidelines Checker.

Använd stödbiblioteket för riktlinjer

Stödbiblioteket för riktlinjer (GSL) är utformat för att hjälpa dig att följa de grundläggande riktlinjerna. GSL innehåller definitioner som gör att du kan ersätta felbenägna konstruktioner med säkrare alternativ. Du kan till exempel ersätta ett T*, length par parametrar med span<T> typen . GSL-projektet är tillgängligt på GitHub på https://github.com/Microsoft/GSL. Biblioteket har öppen källkod, så du kan visa källorna, kommentera eller bidra. Du kan också använda pakethanteraren för vcpkg för att ladda ned och installera biblioteket lokalt.

Se även

• Referens för Kontroll av Visual Studio C++ Core