.vcxproj dan .props struktur file
MSBuild adalah sistem proyek default di Visual Studio; ketika Anda memilih File>Proyek Baru di Visual C++ Anda membuat proyek MSBuild yang pengaturannya disimpan dalam file proyek XML yang memiliki ekstensi ..vcxproj File proyek juga dapat mengimpor .props file dan .targets file tempat pengaturan dapat disimpan.
Jika Anda berniat untuk mempertahankan properti proyek Anda di IDE, kami sarankan Anda hanya membuat dan memodifikasi proyek Anda .vcxproj di IDE, dan menghindari pengeditan manual ke file. Dalam kebanyakan kasus, Anda tidak perlu mengedit file proyek secara manual. Pengeditan manual dapat merusak koneksi proyek yang diperlukan untuk mengubah pengaturan proyek di halaman properti Visual Studio, dan dapat menyebabkan kesalahan build yang sulit di-debug dan diperbaiki. Untuk informasi selengkapnya tentang menggunakan halaman properti, lihat Mengatur pengkompilasi C++ dan membuat properti di Visual Studio.
Dalam skala besar, mengelola banyak proyek individu dalam IDE menjadi melelahkan dan rawan kesalahan. Sulit untuk mempertahankan konsistensi atau menerapkan standarisasi di puluhan atau ratusan proyek. Dalam kasus ini, ada baiknya mengedit file proyek Anda untuk menggunakan file yang disesuaikan .props atau .targets file untuk properti umum di banyak proyek. Anda juga dapat menggunakan file-file ini ketika Anda memerlukan penyesuaian yang tidak dimungkinkan dalam IDE. Tempat yang berguna untuk menyisipkan penyesuaian adalah Directory.Build.props file dan Directory.Build.targets , yang secara otomatis diimpor di semua proyek berbasis MSBuild.
Dalam beberapa kasus, disesuaikan .props atau .targets file saja mungkin tidak cukup untuk kebutuhan manajemen proyek Anda. Anda mungkin masih perlu mengubah .vcxproj file proyek atau lembar properti secara manual. Pengeditan manual memerlukan pemahaman yang baik tentang MSBuild, dan harus mengikuti panduan dalam artikel ini. Agar IDE memuat dan memperbarui .vcxproj file secara otomatis, file-file ini memiliki beberapa batasan yang tidak berlaku untuk file proyek MSBuild lainnya. Kesalahan dapat menyebabkan IDE crash atau berperilaku dengan cara yang tidak terduga.
Untuk skenario pengeditan manual, artikel ini berisi informasi dasar tentang struktur .vcxproj dan file terkait.
Pertimbangan penting
Jika Anda memilih untuk mengedit .vcxproj file secara manual, ketahui fakta-fakta berikut:
Struktur file harus mengikuti formulir yang ditentukan, yang dijelaskan dalam artikel ini.
Sistem proyek Visual Studio C++ saat ini tidak mendukung kartubebas atau daftar langsung dalam item proyek. Misalnya, formulir ini tidak didukung:
<ItemGroup> <None Include="*.txt"/> <ClCompile Include="a.cpp;b.cpp"/> </ItemGroup>Untuk informasi selengkapnya tentang dukungan kartubebas dalam proyek dan kemungkinan solusinya, lihat
.vcxprojfile dan kartubebas.Sistem proyek Visual Studio C++ saat ini tidak mendukung makro di jalur item proyek. Misalnya, formulir ini tidak didukung:
<ItemGroup> <ClCompile Include="$(IntDir)\generated.cpp"/> </ItemGroup>"Tidak didukung" berarti bahwa makro tidak dijamin berfungsi untuk semua operasi di IDE. Makro yang tidak mengubah nilainya dalam konfigurasi yang berbeda harus berfungsi, tetapi mungkin tidak dipertahankan jika item dipindahkan ke filter atau proyek lain. Makro yang mengubah nilainya untuk konfigurasi yang berbeda akan menyebabkan masalah. IDE tidak mengharapkan jalur item proyek berbeda untuk konfigurasi proyek yang berbeda.
Untuk menambahkan, menghapus, atau mengubah properti proyek dengan benar saat Anda mengeditnya dalam dialog Properti Proyek, file harus berisi grup terpisah untuk setiap konfigurasi proyek. Kondisi harus dalam bentuk ini:
Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"Setiap properti harus ditentukan dalam grup dengan label yang benar, seperti yang ditentukan dalam file aturan properti. Untuk informasi selengkapnya, lihat File aturan xml halaman properti.
.vcxproj elemen file
Anda dapat memeriksa konten .vcxproj file dengan menggunakan teks atau editor XML apa pun. Anda dapat melihatnya di Visual Studio dengan mengklik kanan proyek di Penjelajah Solusi, memilih Bongkar proyek lalu memilih Edit Foo.vcxproj.
Hal pertama yang perlu diperhatikan adalah bahwa elemen tingkat atas muncul dalam urutan tertentu. Contohnya:
Sebagian besar grup properti dan grup definisi item terjadi setelah impor untuk Microsoft.Cpp.Default.props.
Semua target diimpor di akhir file.
Ada beberapa grup properti, masing-masing dengan label unik, dan terjadi dalam urutan tertentu.
Urutan elemen dalam file proyek sangat penting, karena MSBuild didasarkan pada model evaluasi berurutan. Jika file proyek Anda, termasuk semua file dan .targets yang diimpor.props, terdiri dari beberapa definisi properti, definisi terakhir mengambil alih yang sebelumnya. Dalam contoh berikut, nilai "xyz" akan diatur selama kompilasi karena mesin MSBUild menemukannya terakhir selama evaluasinya.
<MyProperty>abc</MyProperty>
<MyProperty>xyz</MyProperty>
Cuplikan berikut menunjukkan file minimal .vcxproj . File apa pun .vcxproj yang dihasilkan oleh Visual Studio akan berisi elemen MSBuild tingkat atas ini. Dan, mereka akan muncul dalam urutan ini, meskipun mungkin berisi beberapa salinan dari setiap elemen tingkat atas tersebut. Atribut apa pun Label adalah tag arbitrer yang hanya digunakan oleh Visual Studio sebagai signpost untuk pengeditan; mereka tidak memiliki fungsi lain.
<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns='http://schemas.microsoft.com/developer/msbuild/2003'>
<ItemGroup Label="ProjectConfigurations" />
<PropertyGroup Label="Globals" />
<Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />
<PropertyGroup Label="Configuration" />
<Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
<ImportGroup Label="ExtensionSettings" />
<ImportGroup Label="PropertySheets" />
<PropertyGroup Label="UserMacros" />
<PropertyGroup />
<ItemDefinitionGroup />
<ItemGroup />
<Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
<ImportGroup Label="ExtensionTargets" />
</Project>
Bagian berikut menjelaskan tujuan masing-masing elemen ini dan mengapa elemen tersebut diurutkan dengan cara ini:
Elemen Project
<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns='http://schemas.microsoft.com/developer/msbuild/2003' >
Project adalah simpul akar. Ini menentukan versi MSBuild untuk digunakan dan juga target default untuk dijalankan ketika file ini diteruskan ke MSBuild.exe.
Elemen ItemGroup ProjectConfigurations
<ItemGroup Label="ProjectConfigurations" />
ProjectConfigurations berisi deskripsi konfigurasi proyek. Contohnya adalah Debug|Win32, Rilis|Win32, Debug|ARM dan sebagainya. Banyak pengaturan proyek khusus untuk konfigurasi tertentu. Misalnya, Anda mungkin ingin mengatur properti pengoptimalan untuk build rilis tetapi bukan build debug.
Grup ProjectConfigurations item tidak digunakan pada waktu build. IDE Visual Studio mengharuskannya untuk memuat proyek. Grup item ini dapat dipindahkan ke .props file dan diimpor ke .vcxproj dalam file. Namun, dalam hal ini, jika Anda perlu menambahkan atau menghapus konfigurasi, Anda harus mengedit .props file secara manual; Anda tidak dapat menggunakan IDE.
Elemen ProjectConfiguration
Cuplikan berikut menunjukkan konfigurasi proyek. Dalam contoh ini, 'Debug|x64' adalah nama konfigurasi. Nama konfigurasi proyek harus dalam format $(Configuration)|$(Platform). Simpul ProjectConfiguration dapat memiliki dua properti: Configuration dan Platform. Properti tersebut diatur secara otomatis dengan nilai yang ditentukan di sini saat konfigurasi aktif.
<ProjectConfiguration Include="Debug|x64">
<Configuration>Debug</Configuration>
<Platform>x64</Platform>
</ProjectConfiguration>
IDE mengharapkan untuk menemukan konfigurasi proyek untuk kombinasi Configuration dan Platform nilai apa pun yang digunakan di semua ProjectConfiguration item. Seringkali, itu berarti bahwa proyek mungkin memiliki konfigurasi proyek yang tidak berarti untuk memenuhi persyaratan ini. Misalnya, jika proyek memiliki konfigurasi ini:
Debug|Win32
Ritel|Win32
Pengoptimalan Khusus 32-bit|Win32
maka itu juga harus memiliki konfigurasi ini, meskipun "Pengoptimalan Khusus 32-bit" tidak berarti untuk x64:
Debug|x64
Ritel|x64
Pengoptimalan Khusus 32-bit|x64
Anda dapat menonaktifkan perintah build dan deploy untuk konfigurasi apa pun di Solution Configuration Manager.
Elemen Globals PropertyGroup
<PropertyGroup Label="Globals" />
Globals berisi pengaturan tingkat proyek seperti ProjectGuid, , RootNamespacedan ApplicationType atau ApplicationTypeRevision. Dua terakhir sering menentukan OS target. Proyek hanya dapat menargetkan satu OS karena saat ini, referensi dan item proyek tidak dapat memiliki kondisi. Properti ini biasanya tidak ditimpa di tempat lain dalam file proyek. Grup ini tidak bergantung pada konfigurasi, dan biasanya hanya satu Globals grup yang ada dalam file proyek.
Elemen Impor Microsoft.Cpp.default.props
<Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />
Lembar properti Microsoft.Cpp.default.props dilengkapi dengan Visual Studio dan tidak dapat dimodifikasi. Ini berisi pengaturan default untuk proyek. Default mungkin bervariasi tergantung pada ApplicationType.
Elemen PropertyGroup Konfigurasi
<PropertyGroup Label="Configuration" />
Configuration Grup properti memiliki kondisi konfigurasi terlampir (seperti Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'") dan hadir dalam beberapa salinan, satu per konfigurasi. Grup properti ini menghosting properti yang diatur untuk konfigurasi tertentu. Properti konfigurasi termasuk PlatformToolset dan juga mengontrol penyertaan lembar properti sistem di Microsoft.Cpp.props. Misalnya, jika Anda menentukan properti <CharacterSet>Unicode</CharacterSet>, maka lembar properti sistem microsoft. Cpp.unicodesupport.props akan disertakan. Jika Anda memeriksa Microsoft.Cpp.props, Anda akan melihat baris: <Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />.
Elemen Impor Microsoft.Cpp.props
<Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
Lembar properti Microsoft.Cpp.props (secara langsung atau melalui impor) menentukan nilai default untuk banyak properti khusus alat. Contohnya termasuk properti Tingkat Pengoptimalan dan Peringatan kompilator, properti TypeLibraryName alat MIDL, dan sebagainya. Ini juga mengimpor berbagai lembar properti sistem berdasarkan properti konfigurasi mana yang ditentukan dalam grup properti segera sebelum.
Elemen Extension Pengaturan ImportGroup
<ImportGroup Label="ExtensionSettings" />
Grup ExtensionSettings berisi impor untuk lembar properti yang merupakan bagian dari Kustomisasi Build. Kustomisasi Build ditentukan oleh hingga tiga file: .targets file, .props file, dan .xml file. Grup impor ini berisi impor untuk file..props
Elemen PropertySheets ImportGroup
<ImportGroup Label="PropertySheets" />
Grup PropertySheets berisi impor untuk lembar properti pengguna. Impor ini adalah lembar properti yang Anda tambahkan melalui tampilan Pengelola Properti di Visual Studio. Urutan di mana impor ini tercantum penting dan tercermin dalam Pengelola Properti. File proyek biasanya berisi beberapa instans grup impor semacam ini, satu untuk setiap konfigurasi proyek.
Elemen UserMacros PropertyGroup
<PropertyGroup Label="UserMacros" />
UserMacros berisi properti yang Anda buat sebagai variabel yang digunakan untuk menyesuaikan proses build Anda. Misalnya, Anda dapat menentukan makro pengguna untuk menentukan jalur output kustom Anda sebagai $(CustomOutputPath) dan menggunakannya untuk menentukan variabel lain. Grup properti ini menampung properti tersebut. Di Visual Studio, grup ini tidak diisi dalam file proyek karena Visual C++ tidak mendukung makro pengguna untuk konfigurasi. Makro pengguna didukung dalam lembar properti.
Elemen PropertyGroup per konfigurasi
<PropertyGroup />
Ada beberapa instans grup properti ini, satu per konfigurasi untuk semua konfigurasi proyek. Setiap grup properti harus memiliki satu kondisi konfigurasi yang terpasang. Jika ada konfigurasi yang hilang, dialog Properti Proyek tidak akan berfungsi dengan benar. Tidak seperti grup properti yang tercantum sebelumnya, grup properti ini tidak memiliki label. Grup ini berisi pengaturan tingkat konfigurasi proyek. Pengaturan ini berlaku untuk semua file yang merupakan bagian dari grup item yang ditentukan. Metadata definisi item kustomisasi build diinisialisasi di sini.
PropertyGroup ini harus muncul setelahnya <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> dan tidak boleh ada PropertyGroup lain tanpa Label sebelum itu (jika tidak, pengeditan Properti Proyek tidak akan berfungsi dengan benar).
Elemen ItemDefinitionGroup per konfigurasi
<ItemDefinitionGroup />
Berisi definisi item. Definisi ini harus mengikuti aturan kondisi yang sama dengan elemen per konfigurasi PropertyGroup tanpa label.
Elemen ItemGroup
<ItemGroup />
ItemGroup elemen berisi item (file sumber, dan sebagainya) dalam proyek. Kondisi tidak didukung untuk item Project (yaitu, jenis item yang diperlakukan sebagai item proyek menurut definisi aturan).
Metadata harus memiliki kondisi konfigurasi untuk setiap konfigurasi, meskipun semuanya sama. Contohnya:
<ItemGroup>
<ClCompile Include="stdafx.cpp">
<TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">true</TreatWarningAsError>
<TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">true</TreatWarningAsError>
</ClCompile>
</ItemGroup>
Sistem proyek Visual Studio C++ saat ini tidak mendukung kartubebas dalam item proyek.
<ItemGroup>
<ClCompile Include="*.cpp"> <!--Error-->
</ItemGroup>
Sistem proyek Visual Studio C++ saat ini tidak mendukung makro dalam item proyek.
<ItemGroup>
<ClCompile Include="$(IntDir)\generated.cpp"> <!--not guaranteed to work in all scenarios-->
</ItemGroup>
Referensi ditentukan dalam ItemGroup, dan memiliki batasan berikut:
Referensi tidak mendukung kondisi.
Metadata referensi tidak mendukung kondisi.
Elemen Impor Microsoft.Cpp.targets
<Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
Menentukan (langsung atau melalui impor) target C++ seperti build, clean, dan sebagainya.
Elemen ExtensionTargets ImportGroup
<ImportGroup Label="ExtensionTargets" />
Grup ini berisi impor untuk file target Kustomisasi Build.
Konsekuensi dari pengurutan yang salah
IDE Visual Studio bergantung pada file proyek yang memiliki urutan yang dijelaskan sebelumnya. Misalnya, saat Anda menentukan nilai properti di halaman properti, IDE umumnya akan menempatkan definisi properti dalam grup properti dengan label kosong. Pengurutan ini memastikan bahwa nilai default yang dibawa dalam lembar properti sistem ditimpa oleh nilai yang ditentukan pengguna. Demikian pula, file target diimpor di akhir karena mereka menggunakan properti yang ditentukan sebelumnya, dan karena umumnya tidak menentukan properti itu sendiri. Demikian juga, lembar properti pengguna diimpor setelah lembar properti sistem (disertakan oleh Microsoft.Cpp.props). Urutan ini memastikan bahwa pengguna dapat mengambil alih default apa pun yang dibawa oleh lembar properti sistem.
.vcxproj Jika file tidak mengikuti tata letak ini, hasil build mungkin bukan yang Anda harapkan. Misalnya, jika Anda salah mengimpor lembar properti sistem setelah lembar properti yang ditentukan oleh pengguna, pengaturan pengguna akan ditimpa oleh lembar properti sistem.
Bahkan pengalaman waktu desain IDE tergantung pada batas tertentu pada urutan elemen yang benar. Misalnya, jika file Anda .vcxproj tidak memiliki PropertySheets grup impor, IDE mungkin tidak dapat menentukan tempat menempatkan lembar properti baru yang telah dibuat pengguna di Pengelola Properti. Ini dapat mengakibatkan lembar pengguna ditimpa oleh lembar sistem. Meskipun heuristik yang digunakan oleh IDE dapat mentolerir inkonsistensi kecil dalam .vcxproj tata letak file, kami sangat menyarankan Anda untuk tidak menyimpang dari struktur yang ditunjukkan sebelumnya dalam artikel ini.
Bagaimana IDE menggunakan label elemen
Di IDE, saat Anda mengatur properti UseOfAtl di halaman properti umum, properti tersebut ditulis ke grup properti Konfigurasi dalam file proyek. Properti TargetName di halaman properti yang sama ditulis ke grup properti per konfigurasi tanpa label. Visual Studio melihat file xml halaman properti untuk informasi tempat menulis setiap properti. Untuk halaman Properti umum, dengan asumsi Anda memiliki versi bahasa Inggris Visual Studio 2019 Enterprise Edition, file tersebut adalah %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xml. File aturan XML halaman properti menentukan informasi statis tentang Aturan dan semua propertinya. Salah satu informasi tersebut adalah posisi properti Aturan yang lebih disukai dalam file tujuan (file tempat nilainya akan ditulis). Posisi yang disukai ditentukan oleh atribut Label pada elemen file proyek.
Tata letak Lembar Properti
Cuplikan XML berikut adalah tata letak minimal file lembar properti (.props). Ini mirip .vcxproj dengan file, dan fungsionalitas .props elemen dapat disimpulkan dari diskusi sebelumnya.
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ImportGroup Label="PropertySheets" />
<PropertyGroup Label="UserMacros" />
<PropertyGroup />
<ItemDefinitionGroup />
<ItemGroup />
</Project>
Untuk membuat lembar properti Anda sendiri, salin salah .props satu file di VCTargets folder dan ubah untuk tujuan Anda. Untuk edisi Visual Studio 2019 Enterprise, jalur defaultnya VCTargets adalah %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets.
Baca juga
Mengatur properti kompilator dan build C++ di Visual Studio
File XML Halaman Properti
.vcxproj file dan kartubebas
Saran dan Komentar
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: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk