/external
(Diagnostik header eksternal)
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:
Buka kotak dialog Halaman Properti proyek. Untuk detailnya, lihat Mengatur pengkompilasi C++ dan membuat properti di Visual Studio.
Pilih halaman properti Properti>Konfigurasi VC++ Direktori .
Atur properti External Include Directories untuk menentukan ide yang setara dengan
/external:I path
opsi untuk setiap jalur yang dibatasi titik koma.Pilih halaman properti Properti>Konfigurasi C/C++>External Includes.
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.
Pilih OK atau Terapkan untuk menyimpan perubahan Anda.
Di versi Visual Studio sebelum Visual Studio 2019 versi 16.10:
Buka kotak dialog Halaman Properti proyek. Untuk detailnya, lihat Mengatur pengkompilasi C++ dan membuat properti di Visual Studio.
Pilih halaman properti Properti>Konfigurasi C/C++>Baris Perintah.
/experimental:external
Masukkan opsi dan opsi pengkompilasi lainnya/external
dalam kotak Opsi Tambahan.Pilih OK atau Terapkan untuk menyimpan perubahan Anda.
Untuk mengatur opsi pengkompilasi ini secara terprogram
- Lihat AdditionalOptions.
* 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
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk