/external (Diagnostika externích hlaviček)

Možnosti /external kompilátoru umožňují určit chování diagnostiky kompilátoru pro určité soubory hlaviček. Hlavičky "Externí" jsou přirozeným doplňkem "Jen můj kód": Soubory hlaviček, jako jsou systémové soubory nebo soubory knihovny třetích stran, které nemůžete nebo nechcete změnit. Vzhledem k tomu, že tyto soubory nezměníte, můžete se rozhodnout, že není užitečné vidět diagnostické zprávy z kompilátoru o nich. Možnosti kompilátoru /external poskytují kontrolu nad těmito upozorněními.

Možnosti kompilátoru /external jsou dostupné od sady Visual Studio 2017 verze 15.6. Ve verzích sady Visual Studio před sadou Visual Studio 2019 verze 16.10 /external vyžadují, abyste také nastavili možnost kompilátoru /experimental:external .

Syntaxe

Použijte možnosti externí hlavičky (není vyžadováno ve verzi 16.10 a novější):

/experimental:external

Zadejte externí hlavičky:

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

Určení chování diagnostiky:

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

Argumenty

/experimental:external
Povolí možnosti externích hlaviček. Tato možnost není vyžadována v sadě Visual Studio 2019 verze 16.10 a novější.

/external:anglebrackets
Zachází se všemi záhlavími, které jsou součástí #include <header>, kde header je soubor uzavřený v úhlových závorkách (< >), jako externí záhlaví.

/external:I path
Definuje kořenový adresář, který obsahuje externí hlavičky. Všechny rekurzivní podadresáře path jsou považovány za externí, ale do seznamu adresářů, které kompilátor hledá v souborech include, se přidá pouze path hodnota. Mezera mezi /external:I a path je nepovinná. Adresáře, které obsahují mezery, musí být uzavřeny do dvojitých uvozovek. Adresář může být absolutní nebo relativní cesta.

/external:env:var
Určuje název proměnné var prostředí, která obsahuje seznam externích adresářů hlaviček oddělený středníkem. Je užitečné pro systémy sestavení, které spoléhají na proměnné prostředí, jako INCLUDEje například , které používáte k určení seznamu externích souborů zahrnutí. Nebo , pro soubory, CAExcludePathkteré by neměly být analyzovány /analyze. Můžete například zadat /external:env:INCLUDE , aby se každý adresář v INCLUDE externím adresáři záhlaví najednou. Je to stejné jako použití /external:I k určení jednotlivých adresářů, ale mnohem méně podrobné. var Mezi a /external:env:.

/external:Wn
Tato možnost nastaví výchozí úroveň upozornění ( n hodnota od 0 do 4) pro externí hlavičky. /external:W0 Například efektivně vypne upozornění pro externí hlavičky. Pokud tato možnost není zadaná, kompilátor vydá upozornění příkazového řádku D9007 pro další /external možnosti. Tyto možnosti jsou ignorovány, protože by neměly žádný vliv.

Tato /external:Wn možnost má podobný efekt jako zabalení zahrnuté hlavičky do direktivy #pragma warning :

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

/external:templates-
Umožňuje upozornění z externích hlaviček, když se objeví v šabloně, která se vytvoří v kódu.

Poznámky

Ve výchozím nastavení platí pro všechny soubory úroveň upozornění, /Wn kterou pro sestavení zadáte. Možnosti pro zadání externích hlaviček definují pouze sadu souborů, na které můžete použít jinou výchozí úroveň upozornění. Pokud tedy zadáte externí hlavičky, použijte /external:Wn také k určení úrovně externího upozornění pro změnu chování kompilátoru.

Všechny existující mechanismy pro povolení, zakázání a potlačení upozornění stále fungují v externích i ne externích souborech. Například direktiva warning pragma může přepsat výchozí úroveň upozornění, kterou jste nastavili pro externí hlavičky.

Příklad: Nastavení úrovně externího upozornění

Tento ukázkový program má dva zdrojové soubory program.cpp a header_file.h. Soubor header_file.h je v include_dir podadresáři adresáře obsahujícího program.cpp soubor:

Zdrojový soubor 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
};

Zdrojový soubor program.cpp:

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

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

Ukázku můžete sestavit pomocí tohoto příkazového řádku:

cl /EHsc /I include_dir /W4 program.cpp

Podle očekávání vygeneruje tato ukázka upozornění:

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

Pokud chcete zacházet se souborem záhlaví jako s externím souborem a potlačit upozornění, můžete místo toho* použít tento příkazový řádek:

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

Tento příkazový řádek potlačí upozornění uvnitř header_file.h při zachování upozornění uvnitř program.cpp.

Upozornění přes vnitřní a vnější hranici

Nastavení nízké úrovně upozornění pro externí záhlaví může skrýt některá upozornění s možností akce. Konkrétně může vypnout upozornění vygenerované při vytváření instancí šablony v uživatelském kódu. Tato upozornění můžou znamenat problém v kódu, ke kterému dochází pouze v instancích pro konkrétní typy. (Pokud jste například zapomněli použít vlastnost typu odebrání const nebo &.) Pokud se chcete vyhnout upozorněním v rámci šablon definovaných v externích záhlavích, můžete použít /external:templates- tuto možnost. Kompilátor bere v úvahu efektivní úroveň upozornění v souboru, která definuje šablonu, a úroveň upozornění, ve které dochází k vytvoření instance šablony. Upozornění vygenerovaná uvnitř externí šablony se zobrazí, pokud je šablona vytvořena v rámci ne externího kódu. Tento příkazový řádek například znovu povolí upozornění ze zdrojů šablony v ukázkovém kódu*:

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

Ve výstupu se znovu zobrazí upozornění C4245, i když je kód šablony uvnitř externí hlavičky.

Povolení, zakázání nebo potlačení upozornění

Všechny existující mechanismy pro povolení, zakázání a potlačení upozornění stále fungují v externích hlavičkách. Když se zobrazí upozornění, protože tuto možnost používáte /external:templates- , můžete upozornění potlačit v okamžiku vytvoření instance. Pokud chcete například explicitně potlačit upozornění v ukázce, která se znovu zobrazí z důvodu /external:templates-, použijte direktivu warning pragma:

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

Autoři knihovny můžou použít stejné mechanismy k vynucení určitých upozornění nebo všech upozornění na určité úrovni, pokud mají pocit, že tato upozornění by nikdy neměla být umlčena /external:Wn. Například tato verze souboru hlaviček vynutí upozornění C4245, aby ohlásila chybu:

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

Při této změně hlavičky knihovny autor knihovny zajistí, že globální úroveň upozornění v této hlavičce je 4, bez ohledu na to, co je zadáno v /external:Wn. Nyní jsou hlášena všechna upozornění úrovně 4 a vyšší. Autor knihovny může také vynutit, aby některá upozornění byla chybná, zakázaná, potlačená nebo vygenerovaná pouze jednou v hlavičce. Možnosti /external nepřepíší záměrnou volbu.

system_header Pragma

#pragma system_header je rušivá značka, která umožňuje zapisovačům knihoven označit určitá záhlaví jako externí. Soubor obsahující #pragma system_header se považuje za externí z bodu direktivy pragma na konec souboru, jako by byl na příkazovém řádku zadán jako externí. Kompilátor generuje jakoukoli diagnostiku po direktivě pragma na úrovni upozornění určené ./external:Wn Další informace najdete v tématu system_header direktiva pragma.

Omezení

Některé upozornění vygenerované back-endovým generováním kódu kompilátoru nejsou ovlivněny možnostmi /external . Tato upozornění obvykle začínají C47XX, ale ne všechna upozornění C47XX jsou upozornění back-endu. Tato upozornění můžete přesto zakázat jednotlivě pomocí nástroje /wd47XX. Upozornění analýzy kódu také nemají vliv, protože nemají úrovně upozornění.

Nastavení tohoto parametru kompilátoru ve vývojovém prostředí Visual Studio

V sadě Visual Studio 2019 verze 16.10 a novější:

1. Otevřete dialogové okno Stránky vlastností projektu. Podrobnosti najdete v tématu Nastavení kompilátoru C++ a vlastností sestavení v sadě Visual Studio.

2. Vyberte stránku vlastností Vlastností>konfigurace VC++.

3. Nastavte vlastnost External Include Directories určit ekvivalent /external:I path IDE možnosti pro každou cestu oddělenou středníkem.

4. Vyberte stránku vlastností konfigurace>C/C++>External Includes.

5. Nastavit vlastnosti:

   • Pokud chcete nastavit možnost, nastavte možnost Nastavit jako externí soubory zahrnuté do úhlových závorek jako externí./external:anglebrackets

   • Úroveň upozornění externího záhlaví umožňuje nastavit /external:Wn možnost. Pokud je tato hodnota nastavená na Úroveň upozornění projektu nebo výchozí, /external ostatní možnosti se ignorují.

   • Nastavení diagnostiky šablony v externích hlavičkách na hodnotu Ano/external:templates-

6. Změny uložíte kliknutím na OK nebo Použít .

Ve verzích sady Visual Studio před sadou Visual Studio 2019 verze 16.10:

1. Otevřete dialogové okno Stránky vlastností projektu. Podrobnosti najdete v tématu Nastavení kompilátoru C++ a vlastností sestavení v sadě Visual Studio.

2. Vyberte stránku vlastností příkazového řádku C/C++>Vlastnosti>konfigurace.

3. /experimental:external Do pole Další možnosti zadejte možnost a další /external možnosti kompilátoru.

4. Změny uložíte kliknutím na OK nebo Použít .

Programové nastavení tohoto parametru kompilátoru

• Viz třída AdditionalOptions.

* Přidejte /experimental:external možnost pro povolení možností externích hlaviček ve verzích sady Visual Studio před sadou Visual Studio 2019 verze 16.10.

Viz také

Možnosti kompilátoru MSVC
Syntaxe příkazového řádku kompilátoru MSVC