/external (Diagnostica intestazioni esterne)

  • Articolo

Le opzioni del /external compilatore consentono di specificare il comportamento di diagnostica del compilatore per determinati file di intestazione. Le intestazioni "Esterne" sono il complemento naturale di "Just my code": file di intestazione come file di sistema o file di libreria di terze parti che non è possibile o non si intende modificare. Poiché non si intende modificare questi file, è possibile decidere che non è utile visualizzare i messaggi di diagnostica dal compilatore su di essi. Le opzioni del /external compilatore forniscono il controllo su questi avvisi.

Le opzioni del /external compilatore sono disponibili a partire da Visual Studio 2017 versione 15.6. Nelle versioni di Visual Studio precedenti a Visual Studio 2019 versione 16.10, le /external opzioni richiedono anche l'impostazione dell'opzione del /experimental:external compilatore.

Sintassi

Usare le opzioni di intestazione esterne (non obbligatorio nella versione 16.10 e successive):

/experimental:external

Specificare le intestazioni esterne:

/external:anglebrackets
/external:env:var
/external:I path

Specificare il comportamento di diagnostica:

/external:W0
/external:W1
/external:W2
/external:W3
/external:W4
/external:templates-

Argomenti

/experimental:external
Abilita le opzioni delle intestazioni esterne. Questa opzione non è necessaria in Visual Studio 2019 versione 16.10 e successive.

/external:anglebrackets
Considera tutte le intestazioni incluse da #include <header>, dove il header file è racchiuso tra parentesi angolari (< >), come intestazioni esterne.

/external:I path
Definisce una directory radice che contiene intestazioni esterne. Tutte le sottodirectory ricorsive di path sono considerate esterne, ma solo il path valore viene aggiunto all'elenco di directory in cui il compilatore cerca i file di inclusione. Lo spazio tra /external:I e path è facoltativo. Le directory che includono spazi devono essere racchiuse tra virgolette doppie. Una directory può essere un percorso assoluto o un percorso relativo.

/external:env:var
Specifica il nome di una variabile var di ambiente che contiene un elenco delimitato da punto e virgola di directory di intestazioni esterne. È utile per i sistemi di compilazione che si basano su variabili di ambiente come INCLUDE, che vengono usate per specificare l'elenco di file di inclusione esterni. In alternativa, CAExcludePathper i file che non devono essere analizzati da /analyze. Ad esempio, è possibile specificare /external:env:INCLUDE per creare ogni directory in INCLUDE una directory di intestazione esterna contemporaneamente. È identico a usare /external:I per specificare le singole directory, ma molto meno dettagliato. Non deve esistere spazio tra var e /external:env:.

/external:Wn
Questa opzione imposta il livello di avviso predefinito su n (un valore compreso tra 0 e 4) per le intestazioni esterne. Ad esempio, /external:W0 disattiva efficacemente gli avvisi per le intestazioni esterne. Se questa opzione non è specificata, il compilatore genera l'avviso della riga di comando D9007 per altre /external opzioni. Queste opzioni vengono ignorate, perché non hanno alcun effetto.

L'opzione /external:Wn ha un effetto simile al wrapping di un'intestazione inclusa in una #pragma warning direttiva:

#pragma warning (push, 0)
// the global warning level is now 0 here
#include <external_header>
#pragma warning (pop)

/external:templates-
Consente avvisi da intestazioni esterne quando si verificano in un modello di cui viene creata un'istanza nel codice.

Osservazioni:

Per impostazione predefinita, il /Wn livello di avviso specificato per la compilazione si applica a tutti i file. Le opzioni per specificare intestazioni esterne definiscono solo un set di file a cui è possibile applicare un livello di avviso predefinito diverso. Pertanto, se si specificano intestazioni esterne, usare /external:Wn anche per specificare un livello di avviso esterno per modificare il comportamento del compilatore.

Tutti i meccanismi esistenti per abilitare, disabilitare e eliminare gli avvisi continuano a funzionare in file esterni e non esterni. Ad esempio, un warning pragma può comunque eseguire l'override del livello di avviso predefinito impostato per le intestazioni esterne.

Esempio: Impostare il livello di avviso esterno

Questo programma di esempio include due file di origine e program.cpp header_file.h. Il header_file.h file si trova in una include_dir sottodirectory della directory contenente il program.cpp file:

include_dir/header_file.hFile di origine :

// External header: include_dir/header_file.h

template <typename T>
struct sample_struct
{
    static const T value = -7; // W4: warning C4245: 'initializing':
    // conversion from 'int' to 'unsigned int', signed/unsigned mismatch
};

program.cppFile di origine :

// User code: program.cpp
#include <header_file.h>

int main()
{
    return sample_struct<unsigned int>().value;
}

È possibile compilare l'esempio usando questa riga di comando:

cl /EHsc /I include_dir /W4 program.cpp

Come previsto, questo esempio genera un avviso:

program.cpp
include_dir\header_file.h(6): warning C4245: 'initializing': conversion from 'int' to 'const T', signed/unsigned mismatch
        with
        [
            T=unsigned int
        ]
program.cpp(6): note: see reference to class template instantiation 'sample_struct<unsigned int>' being compiled

Per considerare il file di intestazione come file esterno e eliminare l'avviso, è possibile usare invece* questa riga di comando:

cl /EHsc /I include_dir /external:anglebrackets /external:W0 /W4 program.cpp

Questa riga di comando elimina l'avviso all'interno header_file.h mantenendo gli avvisi all'interno program.cppdi .

Avvisi attraverso il limite interno ed esterno

L'impostazione di un livello di avviso basso per le intestazioni esterne può nascondere alcuni avvisi interattivi. In particolare, può disattivare gli avvisi generati nelle istanze dei modelli nel codice utente. Questi avvisi potrebbero indicare un problema nel codice che si verifica solo nelle istanze per determinati tipi. Ad esempio, se si dimentica di applicare un tratto di tipo rimuovendo const o &.) Per evitare di mettere a tacere gli avvisi all'interno dei modelli definiti nelle intestazioni esterne, è possibile usare l'opzione /external:templates- . Il compilatore considera sia il livello di avviso effettivo nel file che definisce il modello che il livello di avviso in cui si verifica un'istanza del modello. Gli avvisi generati all'interno di un modello esterno vengono visualizzati se viene creata un'istanza del modello all'interno di codice non esterno. Ad esempio, questa riga di comando riabilita gli avvisi provenienti da origini modello nel codice* di esempio:

cl /EHsc /I include_dir /external:anglebrackets /external:W0 /external:templates- /W4 program.cpp

L'avviso C4245 viene visualizzato nuovamente nell'output, anche se il codice del modello si trova all'interno di un'intestazione esterna.

Abilitare, disabilitare o eliminare avvisi

Tutti i meccanismi esistenti per abilitare, disabilitare ed eliminare gli avvisi continuano a funzionare nelle intestazioni esterne. Quando viene visualizzato un avviso perché si usa l'opzione /external:templates- , è comunque possibile eliminare l'avviso al momento della creazione di istanze. Ad esempio, per eliminare in modo esplicito l'avviso nell'esempio che viene visualizzato nuovamente a causa di /external:templates-, usare una warning direttiva pragma:

int main()
{
    #pragma warning( suppress : 4245)
    return sample_struct<unsigned int>().value;
}

Gli autori di librerie possono usare gli stessi meccanismi per applicare determinati avvisi o tutti gli avvisi a un determinato livello, se si sentono che tali avvisi non devono mai essere disattivati da /external:Wn. Ad esempio, questa versione del file di intestazione forza l'avviso C4245 a segnalare un errore:

// External header: include_dir/header_file.h

#pragma warning( push, 4 )
#pragma warning( error : 4245 )

template <typename T>
struct sample_struct
{
    static const T value = -7; // W4: warning C4245: 'initializing': conversion from 'int'
                               // to 'unsigned int', signed/unsigned mismatch
};

#pragma warning( pop )

Con questa modifica all'intestazione della libreria, l'autore della libreria garantisce che il livello di avviso globale in questa intestazione sia 4, indipendentemente dal valore specificato in /external:Wn. Vengono ora segnalati tutti gli avvisi di livello 4 e superiore. L'autore della libreria può anche forzare determinati avvisi ad essere errori, disabilitati, eliminati o generati solo una volta nell'intestazione. Le /external opzioni non sostituiscono quella scelta intenzionale.

Pragma system_header

#pragma system_header è un marcatore intrusivo che consente ai writer di libreria di contrassegnare alcune intestazioni come esterne. Un file contenente #pragma system_header viene considerato esterno dal punto del pragma alla fine del file, come se fosse specificato come esterno nella riga di comando. Il compilatore genera qualsiasi diagnostica dopo il pragma a livello di avviso specificato da /external:Wn. Per altre informazioni, vedere system_header pragma.

Limiti

Alcuni avvisi generati dalla generazione di codice back-end del compilatore non sono interessati dalle /external opzioni. Questi avvisi iniziano in genere con C47XX, anche se non tutti gli avvisi C47XX sono avvisi back-end. È comunque possibile disabilitare questi avvisi singolarmente usando /wd47XX. Anche gli avvisi di analisi del codice non sono interessati, poiché non hanno livelli di avviso.

Per impostare l'opzione del compilatore nell'ambiente di sviluppo di Visual Studio

In Visual Studio 2019 versione 16.10 e successive:

  1. Aprire la finestra di dialogo Pagine delle proprietà del progetto. Per informazioni dettagliate, vedere Impostare il compilatore e le proprietà di compilazione.

  2. Selezionare la pagina delle proprietà Directory di VC++ Proprietà>di configurazione.

  3. Impostare la proprietà External Include Directories per specificare l'equivalente dell'IDE dell'opzione /external:I path per ogni percorso delimitato da punto e virgola.

  4. Selezionare la pagina delle proprietà Proprietà di configurazione C/C++External Includes.Select the Configuration Properties>C/C++>External Includes property page.

  5. Impostare le proprietà:

    • Impostare Considera file inclusi tra parentesi angolari come esterni su Sì per impostare l'opzione /external:anglebrackets .

    • Il livello di avviso intestazione esterna consente di impostare l'opzione /external:Wn . Se questo valore è impostato su Eredita livello avviso progetto o impostazione predefinita, le altre /external opzioni vengono ignorate.

    • Impostare Diagnostica modello in Intestazioni esterne su Sì per impostare l'opzione /external:templates- .

  6. Scegliere OK o Applica per salvare le modifiche.

Nelle versioni di Visual Studio precedenti a Visual Studio 2019 versione 16.10:

  1. Aprire la finestra di dialogo Pagine delle proprietà del progetto. Per informazioni dettagliate, vedere Impostare il compilatore e le proprietà di compilazione.

  2. Selezionare la pagina delle proprietà Proprietà di configurazione>C/C++>Riga di comando.

  3. Immettere l'opzione /experimental:external e altre /external opzioni del compilatore nella casella Opzioni aggiuntive.

  4. Scegliere OK o Applica per salvare le modifiche.

Per impostare l'opzione del compilatore a livello di codice

* Aggiungere l'opzione /experimental:external per abilitare le opzioni delle intestazioni esterne nelle versioni di Visual Studio precedenti a Visual Studio 2019 versione 16.10.

Vedi anche

Opzioni del compilatore MSVC
Sintassi della riga di comando del compilatore MSVC