/external (Diagnostyka nagłówków zewnętrznych)

Opcje kompilatora /external umożliwiają określenie zachowania diagnostycznego kompilatora dla niektórych plików nagłówkowych. Nagłówki "Zewnętrzne" są naturalnym uzupełnieniem "Tylko mój kod": pliki nagłówkowe, takie jak pliki systemowe lub pliki bibliotek innych firm, których nie można zmienić lub nie zamierzasz zmieniać. Ponieważ nie zamierzasz zmieniać tych plików, możesz zdecydować, że nie jest przydatne wyświetlanie komunikatów diagnostycznych z kompilatora o nich. Opcje kompilatora /external zapewniają kontrolę nad tymi ostrzeżeniami.

Opcje kompilatora /external są dostępne od wersji 15.6 programu Visual Studio 2017. W wersjach programu Visual Studio przed programem Visual Studio 2019 w wersji 16.10 /external opcje wymagają również ustawienia opcji kompilatora /experimental:external .

Składnia

Użyj opcji nagłówka zewnętrznego (nie jest to wymagane w wersji 16.10 lub nowszej):

/experimental:external

Określ nagłówki zewnętrzne:

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

Określ zachowanie diagnostyczne:

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

Argumenty

/experimental:external
Włącza opcje nagłówków zewnętrznych. Ta opcja nie jest wymagana w programie Visual Studio 2019 w wersji 16.10 lub nowszej.

/external:anglebrackets
Traktuje wszystkie nagłówki dołączone przez #include <header>element , gdzie header plik jest ujęty w nawiasy kątowe (< >), jako nagłówki zewnętrzne.

/external:I path
Definiuje katalog główny zawierający nagłówki zewnętrzne. Wszystkie cykliczne podkatalogi path są uznawane za zewnętrzne, ale tylko path wartość jest dodawana do listy katalogów, których kompilator wyszukuje w plikach dołączanych. Odstęp między /external:I i path jest opcjonalny. Katalogi zawierające spacje muszą być ujęte w cudzysłowy. Katalog może być ścieżką bezwzględną lub ścieżką względną.

/external:env:var
Określa nazwę zmiennej środowiskowej var , która zawiera rozdzieloną średnikami listę katalogów nagłówków zewnętrznych. Jest to przydatne w przypadku systemów kompilacji, które opierają się na zmiennych środowiskowych, takich jak INCLUDE, które są używane do określania listy plików dołączania zewnętrznego. Lub , CAExcludePathdla plików, które nie powinny być analizowane przez /analyze. Można na przykład określić /external:env:INCLUDE , aby każdy katalog był jednocześnie w INCLUDE katalogu nagłówka zewnętrznego. Jest to takie samo, jak użycie /external:I do określania poszczególnych katalogów, ale znacznie mniej pełne. Między i /external:env:nie powinno być spacji var .

/external:Wn
Ta opcja ustawia domyślny poziom ostrzeżenia na (wartość od 0 do n 4) dla nagłówków zewnętrznych. Na przykład /external:W0 skutecznie wyłącza ostrzeżenia dla nagłówków zewnętrznych. Jeśli ta opcja nie zostanie określona, kompilator wystawia ostrzeżenie wiersza polecenia D9007 dla innych /external opcji. Te opcje są ignorowane, ponieważ nie miałyby one wpływu.

Opcja /external:Wn ma efekt podobny do zawijania dołączonego nagłówka #pragma warning w dyrektywie:

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

/external:templates-
Umożliwia wyświetlanie ostrzeżeń z nagłówków zewnętrznych w przypadku wystąpienia szablonu utworzonego w kodzie.

Uwagi

Domyślnie /Wn poziom ostrzeżenia określony dla kompilacji ma zastosowanie do wszystkich plików. Opcje określania nagłówków zewnętrznych definiują tylko zestaw plików, do których można zastosować inny domyślny poziom ostrzeżenia. Dlatego jeśli określisz nagłówki zewnętrzne, użyj /external:Wn również do określenia zewnętrznego poziomu ostrzeżenia w celu zmiany zachowania kompilatora.

Wszystkie istniejące mechanizmy włączania, wyłączania i pomijania ostrzeżeń nadal działają zarówno w plikach zewnętrznych, jak i innych niż zewnętrzne. Na przykład warning pragma może nadal zastąpić domyślny poziom ostrzeżenia ustawiony dla nagłówków zewnętrznych.

Przykład: Ustawianie zewnętrznego poziomu ostrzeżenia

Ten przykładowy program ma dwa pliki źródłowe i program.cppheader_file.h. Plik header_file.h znajduje się w include_dir podkatalogu katalogu zawierającego program.cpp plik:

Plik include_dir/header_file.hźródłowy:

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

Plik program.cppźródłowy:

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

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

Przykład można utworzyć przy użyciu tego wiersza polecenia:

cl /EHsc /I include_dir /W4 program.cpp

Zgodnie z oczekiwaniami ten przykład generuje ostrzeżenie:

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

Aby traktować plik nagłówka jako plik zewnętrzny i pomijać ostrzeżenie, możesz zamiast tego użyć tego wiersza* polecenia:

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

Ten wiersz polecenia pomija ostrzeżenie wewnątrz header_file.h , zachowując ostrzeżenia wewnątrz program.cppelementu .

Ostrzeżenia w granicach wewnętrznych i zewnętrznych

Ustawienie niskiego poziomu ostrzeżenia dla nagłówków zewnętrznych może ukryć niektóre ostrzeżenia umożliwiające podejmowanie działań. W szczególności może wyłączyć ostrzeżenia emitowane w wystąpieniach szablonu w kodzie użytkownika. Te ostrzeżenia mogą wskazywać na problem w kodzie, który występuje tylko w wystąpieniach dla określonych typów. (Jeśli na przykład nie pamiętasz o zastosowaniu usuwania const cech typu lub &. Aby uniknąć ostrzeżeń dotyczących wyciszania wewnątrz szablonów zdefiniowanych w nagłówkach zewnętrznych, możesz użyć /external:templates- opcji . Kompilator uwzględnia zarówno skuteczny poziom ostrzeżenia w pliku, który definiuje szablon, jak i poziom ostrzeżenia, na którym wystąpi wystąpienie szablonu. Ostrzeżenia emitowane wewnątrz szablonu zewnętrznego są wyświetlane, jeśli szablon jest tworzone w kodzie nienależącym do zewnętrznego. Na przykład ten wiersz polecenia ponownie włącza ostrzeżenia ze źródeł szablonów w przykładowym kodzie*:

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

Ostrzeżenie C4245 pojawia się ponownie w danych wyjściowych, mimo że kod szablonu znajduje się wewnątrz nagłówka zewnętrznego.

Włączanie, wyłączanie lub pomijanie ostrzeżeń

Wszystkie istniejące mechanizmy włączania, wyłączania i pomijania ostrzeżeń nadal działają w nagłówkach zewnętrznych. Gdy pojawi się ostrzeżenie, ponieważ używasz /external:templates- opcji, nadal można pominąć ostrzeżenie w momencie utworzenia wystąpienia. Aby na przykład jawnie pominąć ostrzeżenie w przykładzie, które pojawia się ponownie z /external:templates-powodu , należy użyć warning dyrektywy pragma:

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

Autorzy bibliotek mogą używać tych samych mechanizmów do wymuszania niektórych ostrzeżeń lub wszystkich ostrzeżeń na pewnym poziomie, jeśli czują, że te ostrzeżenia nigdy nie powinny być wyciszone przez /external:Wnprogram . Na przykład ta wersja pliku nagłówka wymusza ostrzeżenie C4245 w celu zgłoszenia błędu:

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

Dzięki tej zmianie nagłówka biblioteki autor biblioteki zapewnia, że globalny poziom ostrzeżenia w tym nagłówku wynosi 4, niezależnie od tego, co zostanie określone w /external:Wnpliku . Teraz są zgłaszane wszystkie ostrzeżenia na poziomie 4 i wyższym. Autor biblioteki może również wymusić błędy, wyłączone, pominięte lub emitowane tylko raz w nagłówku. Opcje /external nie zastępują tego celowego wyboru.

system_header Pragmy

#pragma system_header jest niepożądanym znacznikiem, który umożliwia autorom bibliotek oznaczenie niektórych nagłówków jako zewnętrznych. Plik zawierający #pragma system_header jest uważany za zewnętrzny od punktu pragma na końcu pliku, tak jakby został określony jako zewnętrzny w wierszu polecenia. Kompilator emituje wszelkie dane diagnostyczne po pragma na poziomie ostrzeżenia określonym przez /external:Wn. Aby uzyskać więcej informacji, zobacz system_header pragma.

Ograniczenia

Niektóre ostrzeżenia emitowane przez generowanie kodu zaplecza kompilatora nie mają wpływu na /external opcje. Te ostrzeżenia zwykle zaczynają się od C47XX, choć nie wszystkie ostrzeżenia C47XX są ostrzeżeniami zaplecza. Nadal można wyłączyć te ostrzeżenia indywidualnie przy użyciu polecenia /wd47XX. Ostrzeżenia dotyczące analizy kodu również nie mają wpływu, ponieważ nie mają one poziomów ostrzeżeń.

Aby ustawić tę opcję kompilatora w środowisku programowania Visual Studio

W programie Visual Studio 2019 w wersji 16.10 lub nowszej:

1. Otwórz okno dialogowe Strony właściwości projektu. Aby uzyskać szczegółowe informacje, zobacz Set C++ compiler and build properties in Visual Studio (Ustawianie właściwości kompilatora języka C++ i kompilowania w programie Visual Studio).

2. Wybierz stronę właściwości Właściwości>konfiguracji KATALOGi VC++.

3. Ustaw właściwość Katalogi dołączania zewnętrznego, aby określić odpowiednik /external:I path środowiska IDE dla każdej ścieżki rozdzielanej średnikami.

4. Wybierz stronę Właściwości>konfiguracji C/C++>External Includes.

5. Ustaw właściwości:

   • Ustaw opcję Traktuj pliki dołączone do nawiasów kątowych jako zewnętrzne na wartość Tak , aby ustawić /external:anglebrackets opcję .

   • Poziom ostrzeżenia nagłówka zewnętrznego /external:Wn umożliwia ustawienie opcji. Jeśli ta wartość ma wartość Dziedzicz poziom ostrzeżenia projektu lub wartość domyślna, inne /external opcje są ignorowane.

   • Ustaw opcję Diagnostyka szablonu w nagłówkach zewnętrznych na wartość Tak/external:templates-.

6. Wybierz przycisk OK lub Zastosuj , aby zapisać zmiany.

W wersjach programu Visual Studio przed programem Visual Studio 2019 w wersji 16.10:

1. Otwórz okno dialogowe Strony właściwości projektu. Aby uzyskać szczegółowe informacje, zobacz Set C++ compiler and build properties in Visual Studio (Ustawianie właściwości kompilatora języka C++ i kompilowania w programie Visual Studio).

2. Wybierz stronę Właściwości>konfiguracji C/C++>Wiersza polecenia.

3. /experimental:external Wprowadź opcję i inne /external opcje kompilatora w polu Opcje dodatkowe.

4. Wybierz przycisk OK lub Zastosuj , aby zapisać zmiany.

Aby programowo ustawić tę opcję kompilatora

• Zobacz: AdditionalOptions.

* Dodaj /experimental:external opcję włączania opcji nagłówków zewnętrznych w wersjach programu Visual Studio przed programem Visual Studio 2019 w wersji 16.10.

Zobacz też

Opcje kompilatora MSVC
Składnia wiersza polecenia kompilatora MSVC