/external (Diagnose externer Header)

  • Artikel

Mit den /external Compileroptionen können Sie das Compilerdiagnoseverhalten für bestimmte Headerdateien angeben. "Externe" Header sind die natürliche Ergänzung von "Nur mein Code": Headerdateien wie Systemdateien oder Bibliotheksdateien von Drittanbietern, die Sie nicht ändern können oder nicht möchten. Da Sie diese Dateien nicht ändern werden, können Sie entscheiden, dass es nicht hilfreich ist, Diagnosemeldungen vom Compiler anzuzeigen. Mit /external den Compileroptionen können Sie diese Warnungen steuern.

Die /external Compileroptionen sind ab Visual Studio 2017, Version 15.6, verfügbar. In Versionen von Visual Studio vor Visual Studio 2019, Version 16.10, /external müssen Sie auch die /experimental:external Compileroption festlegen.

Syntax

Verwenden Sie externe Headeroptionen (in 16.10 und höher nicht erforderlich):

/experimental:external

Angeben externer Header:

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

Diagnoseverhalten angeben:

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

Argumente

/experimental:external
Aktiviert die Optionen für externe Header. Diese Option ist in Visual Studio 2019, Version 16.10 und höher, nicht erforderlich.

/external:anglebrackets
Behandelt alle Kopfzeilen, die enthalten #include <header>sind, wobei die header Datei in winkelige Klammern (< >) eingeschlossen ist, als externe Kopfzeilen.

/external:I path
Definiert ein Stammverzeichnis, das externe Header enthält. Alle rekursiven Unterverzeichnisse path werden als extern betrachtet, aber nur der path Wert wird der Liste der Verzeichnisse hinzugefügt, nach denen der Compiler nach eingeschlossenen Dateien sucht. Der Abstand zwischen /external:I und path ist optional. Verzeichnisse, die Leerzeichen enthalten, müssen in doppelte Anführungszeichen eingeschlossen werden. Ein Verzeichnis kann ein absoluter Pfad oder ein relativer Pfad sein.

/external:env:var
Gibt den Namen einer Umgebungsvariable var an, die eine durch Semikolons getrennte Liste externer Headerverzeichnisse enthält. Es ist nützlich für Buildsysteme, die auf Umgebungsvariablen INCLUDEwie z. B. basieren, die Sie zum Angeben der Liste der externen Includedateien verwenden. Oder, CAExcludePathfür Dateien, die nicht analysiert werden sollten./analyze Sie können z. B. angeben /external:env:INCLUDE , dass jedes Verzeichnis in INCLUDE einem externen Headerverzeichnis gleichzeitig festgelegt wird. Es ist identisch mit der Verwendung /external:I der einzelnen Verzeichnisse, aber viel weniger ausführlich. Es sollte kein Leerraum zwischen var und /external:env:.

/external:Wn
Diese Option legt die Standardwarnstufe für externe Header auf n (einen Wert von 0 bis 4) fest. Deaktiviert beispielsweise /external:W0 Warnungen für externe Header effektiv. Wenn diese Option nicht angegeben ist, gibt der Compiler die Befehlszeilenwarnung D9007 für andere /external Optionen aus. Diese Optionen werden ignoriert, da sie keine Auswirkung haben würden.

Die /external:Wn Option hat einen Effekt, der dem Umbruch eines eingeschlossenen Headers in einer #pragma warning Direktive ähnelt:

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

/external:templates-
Ermöglicht Warnungen von externen Headern, wenn sie in einer Vorlage auftreten, die in Ihrem Code instanziiert wird.

Hinweise

Standardmäßig gilt die /Wn für Den Build angegebene Warnstufe für alle Dateien. Die Optionen zum Angeben externer Header definieren nur eine Reihe von Dateien, auf die Sie eine andere Standardwarnungsstufe anwenden können. Wenn Sie also externe Header angeben, können /external:Wn Sie auch eine externe Warnstufe angeben, um das Compilerverhalten zu ändern.

Alle vorhandenen Mechanismen zum Aktivieren, Deaktivieren und Unterdrücken von Warnungen funktionieren weiterhin sowohl in externen als auch in nicht externen Dateien. Beispielsweise kann ein warning Pragma weiterhin die Standardwarnstufe außer Kraft setzen, die Sie für externe Header festgelegt haben.

Beispiel: Festlegen der externen Warnstufe

Dieses Beispielprogramm enthält zwei Quelldateien program.cpp und header_file.h. Die header_file.h Datei befindet sich in einem include_dir Unterverzeichnis des Verzeichnisses, das die program.cpp Datei enthält:

Quelldatei include_dir/header_file.h:

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

Quelldatei program.cpp:

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

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

Sie können das Beispiel mithilfe dieser Befehlszeile erstellen:

cl /EHsc /I include_dir /W4 program.cpp

Wie erwartet generiert dieses Beispiel eine Warnung:

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

Um die Headerdatei als externe Datei zu behandeln und die Warnung zu unterdrücken, können Sie stattdessen* diese Befehlszeile verwenden:

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

Diese Befehlszeile unterdrückt die Warnung in der Innenseite header_file.h , während Warnungen erhalten bleiben program.cpp.

Warnungen über die interne und externe Grenze hinweg

Das Festlegen einer niedrigen Warnstufe für externe Header kann einige Aktionen erfordernde Warnungen ausblenden. Insbesondere können Warnungen deaktiviert werden, die bei Vorlageninstanziierungen im Benutzercode ausgegeben werden. Diese Warnungen deuten möglicherweise auf ein Problem in Ihrem Code hin, das nur in Instanziierungen für bestimmte Typen auftritt. (Wenn Sie beispielsweise vergessen haben, eine Typeigenschaft zu entfernen const oder &.) Um Silencing-Warnungen innerhalb von Vorlagen zu vermeiden, die in externen Headern definiert sind, können Sie die /external:templates- Option verwenden. Der Compiler berücksichtigt sowohl die effektive Warnstufe in der Datei, die die Vorlage definiert, als auch die Warnstufe, auf der vorlageninstanziiert wird. Warnungen, die in einer externen Vorlage ausgegeben werden, werden angezeigt, wenn die Vorlage innerhalb von nicht externem Code instanziiert wird. Diese Befehlszeile aktiviert z. B. Warnungen aus Vorlagenquellen im Beispielcode* erneut:

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

Die C4245-Warnung wird in der Ausgabe erneut angezeigt, obwohl sich der Vorlagencode in einem externen Header befindet.

Aktivieren, Deaktivieren oder Unterdrücken von Warnungen

Alle vorhandenen Mechanismen zum Aktivieren, Deaktivieren und Unterdrücken von Warnungen funktionieren weiterhin in externen Headern. Wenn eine Warnung angezeigt wird, weil Sie die /external:templates- Option verwenden, können Sie die Warnung weiterhin an der Instanziierungsstelle unterdrücken. Verwenden Sie beispielsweise eine warning Pragma-Direktive, um die Warnung im Beispiel explizit zu unterdrücken, die erneut /external:templates-angezeigt wird:

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

Bibliotheksautoren können dieselben Mechanismen verwenden, um bestimmte Warnungen oder alle Warnungen auf bestimmter Ebene zu erzwingen, wenn sie der Ansicht sind, dass diese Warnungen niemals stummgehalten /external:Wnwerden sollten. Diese Version der Headerdatei erzwingt z. B. die Warnung C4245, einen Fehler zu melden:

// 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 )

Mit dieser Änderung an den Bibliotheksheader stellt der Autor der Bibliothek sicher, dass die globale Warnstufe in dieser Kopfzeile 4 ist, unabhängig davon, in welcher Eigenschaft angegeben /external:Wnwird. Jetzt werden alle Warnungen der Ebene 4 und höher gemeldet. Der Bibliotheksautor kann auch erzwingen, dass bestimmte Warnungen fehler, deaktiviert, unterdrückt oder nur einmal in der Kopfzeile ausgegeben werden. Die /external Optionen überschreiben diese absichtliche Auswahl nicht.

system_header-Pragma

#pragma system_header ist eine aufdringliche Markierung, mit der Bibliotheksautoren bestimmte Kopfzeilen als extern markieren können. Eine Datei, #pragma system_header die von dem Punkt des Pragmas bis zum Ende der Datei als extern eingestuft wird, als ob sie in der Befehlszeile als extern angegeben wurde. Der Compiler gibt alle Diagnosen nach dem Pragma auf der durch ./external:Wn Weitere Informationen finden Sie unter system_header pragma.

Begrenzungen

Einige Warnungen, die von der Back-End-Codegenerierung des Compilers ausgegeben werden, sind von den /external Optionen nicht betroffen. Diese Warnungen beginnen in der Regel mit C47XX, obwohl nicht alle C47XX-Warnungen Back-End-Warnungen sind. Sie können diese Warnungen weiterhin einzeln mithilfe von /wd47XX. Codeanalysewarnungen sind ebenfalls nicht betroffen, da sie keine Warnstufen haben.

So legen Sie diese Compileroption in der Visual Studio-Entwicklungsumgebung fest

In Visual Studio 2019, Version 16.10 und höher:

  1. Öffnen Sie das Dialogfeld Eigenschaftenseiten des Projekts. Weitere Informationen erhalten Sie unter Set C++ compiler and build properties in Visual Studio (Festlegen der Compiler- und Buildeigenschaften (C++) in Visual Studio).

  2. Wählen Sie die Eigenschaftenseite "Konfigurationseigenschaften>VC++-Verzeichnisse" aus.

  3. Legen Sie die Eigenschaft "Externe Includeverzeichnisse " fest, um die IDE-Entsprechung der /external:I path Option für jeden durch Semikolons getrennten Pfad anzugeben.

  4. Wählen Sie die Konfigurationseigenschaften>C/C++>External Includes-Eigenschaftenseite aus.

  5. Legen Sie Eigenschaften fest:

    • Legen Sie "Dateien behandeln" in eckigen Klammern als "Extern " auf "Ja " fest, um die /external:anglebrackets Option festzulegen.

    • Mit der Warnungsstufe für externe Kopfzeilen können Sie die /external:Wn Option festlegen. Wenn dieser Wert auf "Projektwarnungsstufe erben" oder "Standard" festgelegt ist, werden andere /external Optionen ignoriert.

    • Legen Sie die Vorlagendiagnose in externen Headern auf "Ja " fest, um die /external:templates- Option festzulegen.

  6. Wählen Sie OK oder Übernehmen, um die Änderungen zu speichern.

In Versionen von Visual Studio vor Visual Studio 2019, Version 16.10:

  1. Öffnen Sie das Dialogfeld Eigenschaftenseiten des Projekts. Weitere Informationen erhalten Sie unter Set C++ compiler and build properties in Visual Studio (Festlegen der Compiler- und Buildeigenschaften (C++) in Visual Studio).

  2. Klicken Sie auf der Eigenschaftenseite auf Konfigurationseigenschaften>C/C++>Befehlszeile.

  3. Geben Sie die /experimental:external Option und andere /external Compileroptionen in das Feld "Zusätzliche Optionen " ein.

  4. Wählen Sie OK oder Übernehmen, um die Änderungen zu speichern.

So legen Sie diese Compileroption programmgesteuert fest

* Fügen Sie die /experimental:external Option hinzu, um die Optionen für externe Header in Versionen von Visual Studio vor Visual Studio 2019, Version 16.10, zu aktivieren.

Siehe auch

MSVC-Compileroptionen
Syntax für die MSVC-Compilerbefehlszeile