Strukturerad SARIF-diagnostik

MSVC-kompilatorn kan göras för utdatadiagnostik som SARIF (statisk analys resultat utbytesformat). SARIF är ett maskinläsbart JSON-baserat format.

Det finns två sätt att få MSVC-kompilatorn att producera SARIF-diagnostik:

  • Skicka växeln /experimental:log på kommandoraden. Mer information finns i dokumentationen /experimental:log .
  • Starta cl.exe programmatiskt och ange SARIF_OUTPUT_PIPE miljövariabeln för att hämta SARIF-block via ett rör.

Hämtar SARIF via ett rör

Verktyg som använder SARIF från MSVC-kompilatorn medan en kompilering pågår använder en pipe. Mer information om hur du skapar Windows-rör finns i dokumentationen CreatePipe .

Om du vill hämta SARIF via ett rör anger du SARIF_OUTPUT_PIPE miljövariabeln som UTF-16-kodad heltalsrepresentation av HANDLE rörets skrivslut och startar cl.exesedan . SARIF skickas längs röret enligt följande:

  • När en ny diagnostik är tillgänglig skrivs den till det här röret.
  • Diagnostik skrivs till röret en i taget i stället för som ett helt SARIF-objekt.
  • Varje diagnostik representeras av ett JSON-RPC 2.0-meddelande av typen Meddelande.
  • Det JSON-RPC meddelandet är prefix med en Content-Length rubrik med formuläret Content-Length: <N> följt av två nya rader, där <N> är längden på följande JSON-RPC meddelande i byte.
  • Både JSON-RPC-meddelandet och huvudet kodas i UTF-8.
  • Det här JSON-RPC-with-header-formatet är kompatibelt med vs-streamjsonrpc.
  • Metodnamnet för JSON-RPC-anropet är OnSarifResult.
  • Anropet har en enda parameter som kodas efter namn med parameternamnet result.
  • Värdet för argumentet är ett enskilt result objekt som anges av SARIF Version 2.1-standarden.

Exempel

Här är ett exempel på ett JSON-RPC SARIF-resultat som produceras av cl.exe:

Content-Length: 334

{"jsonrpc":"2.0","method":"OnSarifResult","params":{"result":{"ruleId":"C1034","level":"fatal","message":{"text":"iostream: no include path set"},"locations":[{"physicalLocation":{"artifactLocation":{"uri":"file:///C:/Users/sybrand/source/repos/cppcon-diag/cppcon-diag/cppcon-diag.cpp"},"region":{"startLine":1,"startColumn":10}}}]}}}{"jsonrpc":"2.0","method":"OnSarifResult","params":{"result":{"ruleId":"C1034","level":"fatal","message":{"text":"iostream: no include path set"},"locations":[{"physicalLocation":{"artifactLocation":{"uri":"file:///C:/Users/sybrand/source/repos/cppcon-diag/cppcon-diag/cppcon-diag.cpp"},"region":{"startLine":1,"startColumn":10}}}]}}}

SARIF-resultatdata

Kompilatorn matar ut SARIF som kan innehålla ytterligare information som representerar den kapslade strukturen för vissa diagnostiker. En diagnostik (representeras av ett result SARIF-objekt) kan innehålla ett "diagnostikträd" med ytterligare information i fältet relatedLocations . Det här trädet kodas med en SARIF-egenskapsväska enligt följande:

Ett location objekts properties fält kan innehålla en nestingLevel egenskap vars värde är djupet på den här platsen i diagnostikträdet. Om en plats inte har något nestingLevel angivet anses djupet vara 0 och den här platsen är underordnad rotdiagnostiken som representeras av objektet som innehåller den result . Annars, om värdet är större än djupet på platsen omedelbart före den här platsen i fältet, är den här platsen underordnad relatedLocations den platsen. Annars är den här platsen ett syskon till närmast föregående location i relatedLocations fältet med samma djup.

Exempel

Överväg följande kod:

struct dog {};
struct cat {};

void pet(dog);
void pet(cat);

struct lizard {};

int main() {
    pet(lizard{});
}

När den här koden kompileras skapar kompilatorn följande result objekt (physicalLocation egenskaperna har tagits bort för korthet):

{
    "ruleId": "C2665",
    "level": "error",
    "message": {
        "text": "'pet': no overloaded function could convert all the argument types"
    },
    "relatedLocations": [
        {
            "id": 0,
            "message": {
                "text": "could be 'void pet(cat)'"
            }
        },
        {
            "id": 1,
            "message": {
                "text": "'void pet(cat)': cannot convert argument 1 from 'lizard' to 'cat'"
            },
            "properties": {
                "nestingLevel": 1
            }
        },
        {
            "id": 2,
            "message": {
                "text": "No user-defined-conversion operator available that can perform this conversion, or the operator cannot be called"
            },
            "properties": {
                "nestingLevel": 2
            }
        },
        {
            "id": 3,
            "message": {
                "text": "or       'void pet(dog)'"
            }
        },
        {
            "id": 4,
            "message": {
                "text": "'void pet(dog)': cannot convert argument 1 from 'lizard' to 'dog'"
            },
            "properties": {
                "nestingLevel": 1
            }
        },
        {
            "id": 5,
            "message": {
                "text": "No user-defined-conversion operator available that can perform this conversion, or the operator cannot be called"
            },
            "properties": {
                "nestingLevel": 2
            }
        },
        {
            "id": 6,
            "message": {
                "text": "while trying to match the argument list '(lizard)'"
            }
        }
    ]
}

Det logiska diagnostikträdet som skapas från meddelandena i det här result objektet är:

  • "husdjur": ingen överbelastad funktion kunde konvertera alla argumenttyper
    • kan vara "void pet(cat)"
      • "void pet(cat)": kan inte konvertera argument 1 från "ödla" till "katt"
        • Ingen användardefinierad konverteringsoperator tillgänglig som kan utföra den här konverteringen, eller så kan operatorn inte anropas
    • eller "void pet(dog)"
      • "void pet(dog)": kan inte konvertera argument 1 från "ödla" till "hund"
        • Ingen användardefinierad konverteringsoperator tillgänglig som kan utföra den här konverteringen, eller så kan operatorn inte anropas
    • när du försöker matcha argumentlistan (ödla)"

Se även

/experimental:log (Aktivera strukturerad SARIF-diagnostik)

  • Last updated on