Bagikan melalui

/external (Diagnostik header eksternal)

  • Artikel

Opsi /external kompilator memungkinkan Anda menentukan perilaku diagnostik pengkompilasi untuk file header tertentu. Header "Eksternal" adalah pelengkap alami dari "Hanya kode saya": File header seperti file sistem atau file pustaka pihak ketiga yang tidak dapat Atau tidak ingin Anda ubah. Karena Anda tidak akan mengubah file-file ini, Anda mungkin memutuskan tidak berguna untuk melihat pesan diagnostik dari pengkompilasi tentang file tersebut. Opsi /external kompilator memberi Anda kontrol atas peringatan ini.

Opsi /external pengkompilasi tersedia mulai dari Visual Studio 2017 versi 15.6. Dalam versi Visual Studio sebelum Visual Studio 2019 versi 16.10, opsi ini /external mengharuskan /experimental:external Anda juga mengatur opsi pengkompilasi.

Sintaks

Gunakan opsi header eksternal (Tidak diperlukan dalam 16.10 dan yang lebih baru):

/experimental:external

Tentukan header eksternal:

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

Tentukan perilaku diagnostik:

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

Argumen

/experimental:external
Mengaktifkan opsi header eksternal. Opsi ini tidak diperlukan di Visual Studio 2019 versi 16.10 dan yang lebih baru.

/external:anglebrackets
Memperlakukan semua header yang disertakan oleh #include <header>, di mana header file diapit dalam tanda kurung sudut (< >), sebagai header eksternal.

/external:I path
Menentukan direktori akar yang berisi header eksternal. Semua subdirektori path rekursif dianggap eksternal, tetapi hanya path nilai yang ditambahkan ke daftar direktori yang dicari kompilator untuk menyertakan file. Ruang antara /external:I dan path bersifat opsional. Direktori yang menyertakan spasi harus diapit dalam tanda kutip ganda. Direktori mungkin merupakan jalur absolut atau jalur relatif.

/external:env:var
Menentukan nama variabel var lingkungan yang menyimpan daftar direktori header eksternal yang dipisahkan titik koma. Ini berguna untuk sistem build yang mengandalkan variabel lingkungan seperti INCLUDE, yang Anda gunakan untuk menentukan daftar file sertakan eksternal. Atau, CAExcludePath, untuk file yang seharusnya tidak dianalisis oleh /analyze. Misalnya, Anda dapat menentukan /external:env:INCLUDE untuk membuat setiap direktori di INCLUDE direktori header eksternal sekaligus. Ini sama dengan menggunakan /external:I untuk menentukan direktori individu, tetapi jauh lebih sedikit verbose. Seharusnya tidak ada ruang antara var dan /external:env:.

/external:Wn
Opsi ini mengatur tingkat peringatan default ke n (nilai dari 0 hingga 4) untuk header eksternal. Misalnya, /external:W0 secara efektif menonaktifkan peringatan untuk header eksternal. Jika opsi ini tidak ditentukan, pengkompilasi mengeluarkan peringatan baris perintah D9007 untuk opsi lain /external . Opsi tersebut diabaikan, karena tidak akan berpengaruh.

Opsi /external:Wn ini memiliki efek yang mirip dengan membungkus header yang disertakan dalam direktif #pragma warning :

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

/external:templates-
Memungkinkan peringatan dari header eksternal saat terjadi dalam templat yang dibuat dalam kode Anda.

Keterangan

Secara default, tingkat peringatan yang /Wn Anda tentukan untuk build Anda berlaku untuk semua file. Opsi untuk menentukan header eksternal hanya menentukan sekumpulan file yang dapat Anda terapkan tingkat peringatan default yang berbeda. Jadi, jika Anda menentukan header eksternal, gunakan /external:Wn juga untuk menentukan tingkat peringatan eksternal untuk mengubah perilaku pengkompilasi.

Semua mekanisme yang ada untuk mengaktifkan, menonaktifkan, dan menekan peringatan masih berfungsi di file eksternal dan non-eksternal. Misalnya, warning pragma masih dapat mengambil alih tingkat peringatan default yang Anda tetapkan untuk header eksternal.

Contoh: Mengatur tingkat peringatan eksternal

Program sampel ini memiliki dua file sumber, program.cpp dan header_file.h. File header_file.h berada dalam include_dir subdirektori direktori yang berisi program.cpp file:

File sumber 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
};

File sumber program.cpp:

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

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

Anda dapat membuat sampel dengan menggunakan baris perintah ini:

cl /EHsc /I include_dir /W4 program.cpp

Seperti yang diharapkan, sampel ini menghasilkan peringatan:

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

Untuk memperlakukan file header sebagai file eksternal dan menekan peringatan, Anda dapat menggunakan baris perintah ini sebagai gantinya*:

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

Baris perintah ini menekan peringatan di dalam header_file.h saat mempertahankan peringatan di dalam program.cpp.

Peringatan di seluruh batas internal dan eksternal

Mengatur tingkat peringatan rendah untuk header eksternal dapat menyembunyikan beberapa peringatan yang dapat ditindakkan. Secara khusus, ini dapat menonaktifkan peringatan yang dipancarkan pada instans templat dalam kode pengguna. Peringatan ini mungkin menunjukkan masalah dalam kode Anda yang hanya terjadi dalam instans untuk jenis tertentu. (Misalnya, jika Anda lupa menerapkan penghapusan sifat const jenis atau &.) Untuk menghindari peringatan silencing di dalam templat yang ditentukan di header eksternal, Anda dapat menggunakan opsi ./external:templates- Pengkompilasi mempertimbangkan tingkat peringatan efektif dalam file yang menentukan templat, dan tingkat peringatan tempat instansiasi templat terjadi. Peringatan yang dipancarkan di dalam templat eksternal muncul jika templat dibuat dalam kode non-eksternal. Misalnya, baris perintah ini mengaktifkan kembali peringatan dari sumber templat dalam kode* sampel:

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

Peringatan C4245 muncul lagi dalam output, meskipun kode templat berada di dalam header eksternal.

Mengaktifkan, menonaktifkan, atau menyembunyikan peringatan

Semua mekanisme yang ada untuk mengaktifkan, menonaktifkan, dan menekan peringatan masih berfungsi di header eksternal. Saat peringatan muncul karena Anda menggunakan /external:templates- opsi , Anda masih dapat menekan peringatan di titik instansiasi. Misalnya, untuk secara eksplisit menekan peringatan dalam sampel yang muncul kembali karena , gunakan warning arahan /external:templates-pragma:

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

Penulis pustaka dapat menggunakan mekanisme yang sama untuk memberlakukan peringatan tertentu, atau semua peringatan pada tingkat tertentu, jika mereka merasa peringatan tersebut tidak boleh didiamkan oleh /external:Wn. Misalnya, versi file header ini memaksa peringatan C4245 untuk melaporkan kesalahan:

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

Dengan perubahan ini ke header pustaka, penulis pustaka memastikan bahwa tingkat peringatan global di header ini adalah 4, tidak peduli apa yang ditentukan dalam /external:Wn. Sekarang semua peringatan tingkat 4 ke atas dilaporkan. Penulis pustaka juga dapat memaksa peringatan tertentu menjadi kesalahan, dinonaktifkan, ditekan, atau dipancarkan hanya sekali di header. Opsi /external tidak mengambil alih pilihan yang disarankan tersebut.

system_header pragma

#pragma system_header adalah penanda intrusif yang memungkinkan penulis pustaka menandai header tertentu sebagai eksternal. File yang berisi #pragma system_header dianggap eksternal dari titik pragma ke akhir file, seolah-olah ditentukan sebagai eksternal pada baris perintah. Pengkompilasi memancarkan diagnostik apa pun setelah pragma pada tingkat peringatan yang ditentukan oleh /external:Wn. Untuk informasi selengkapnya, lihat system_header pragma.

Batasan

Beberapa peringatan yang dipancarkan oleh pembuatan kode back-end kompilator tidak terpengaruh oleh /external opsi. Peringatan ini biasanya dimulai dengan C47XX, meskipun tidak semua peringatan C47XX adalah peringatan back-end. Anda masih dapat menonaktifkan peringatan ini satu per satu dengan menggunakan /wd47XX. Peringatan analisis kode juga tidak terpengaruh, karena tidak memiliki tingkat peringatan.

Untuk mengatur opsi pengkompilasi ini di lingkungan pengembangan Visual Studio

Di Visual Studio 2019 versi 16.10 dan yang lebih baru:

  1. Buka kotak dialog Halaman Properti proyek. Untuk detailnya, lihat Mengatur pengkompilasi C++ dan membuat properti di Visual Studio.

  2. Pilih halaman properti Properti>Konfigurasi VC++ Direktori .

  3. Atur properti External Include Directories untuk menentukan ide yang setara dengan /external:I path opsi untuk setiap jalur yang dibatasi titik koma.

  4. Pilih halaman properti Properti>Konfigurasi C/C++>External Includes.

  5. Atur properti:

    • Atur Perlakukan File Yang Disertakan dengan Kurung Sudut sebagai Eksternal ke Ya untuk mengatur /external:anglebrackets opsi.

    • Tingkat Peringatan Header Eksternal memungkinkan Anda mengatur /external:Wn opsi. Jika nilai ini diatur ke Mewarisi Tingkat Peringatan Proyek atau default, opsi lain /external diabaikan.

    • Atur Diagnostik Templat di Header Eksternal ke Ya untuk mengatur /external:templates- opsi.

  6. Pilih OK atau Terapkan untuk menyimpan perubahan Anda.

Di versi Visual Studio sebelum Visual Studio 2019 versi 16.10:

  1. Buka kotak dialog Halaman Properti proyek. Untuk detailnya, lihat Mengatur pengkompilasi C++ dan membuat properti di Visual Studio.

  2. Pilih halaman properti Properti>Konfigurasi C/C++>Baris Perintah.

  3. /experimental:external Masukkan opsi dan opsi pengkompilasi lainnya /external dalam kotak Opsi Tambahan.

  4. Pilih OK atau Terapkan untuk menyimpan perubahan Anda.

Untuk mengatur opsi pengkompilasi ini secara terprogram

* Tambahkan /experimental:external opsi untuk mengaktifkan opsi header eksternal di versi Visual Studio sebelum Visual Studio 2019 versi 16.10.

Lihat juga

Opsi pengkompilasi MSVC
Sintaks baris perintah pengkompilasi MSVC