Bagikan melalui

CMakePresets.json dan CMakeUserPresets.json peta vendor Microsoft

  • Artikel

CMake mendukung dua file, CMakePresets.json dan CMakeUserPresets.json, yang memungkinkan pengguna menentukan opsi konfigurasi, build, dan pengujian umum dan membagikannya dengan orang lain.

CMakePresets.json dan CMakeUserPresets.json dapat digunakan untuk mendorong CMake di Visual Studio, di Visual Studio Code, dalam alur Integrasi Berkelanjutan (CI), dan dari baris perintah.

CMakePresets.json dimaksudkan untuk menyimpan build di seluruh proyek, dan CMakeUserPresets.json ditujukan bagi pengembang untuk menyimpan build lokal mereka sendiri. Skema untuk kedua file identik.

CMakePresets.json dan CMakeUserPresets.json mendukung peta vendor untuk menyimpan informasi khusus vendor. Microsoft mempertahankan dua peta vendor dengan opsi khusus untuk Visual Studio dan Visual Studio Code. Di sini kami mendokumenkan dua peta vendor Microsoft dan makro vendor. Untuk informasi selengkapnya tentang sisa skema, lihat dokumentasi CMake resmi. Ini termasuk informasi tentang Mengonfigurasi Preset, Build Presets, dan Test Presets.

Untuk informasi selengkapnya tentang cara menggunakan CMakePresets.json di Visual Studio, lihat Mengonfigurasi dan membangun dengan CMake Presets di Visual Studio

Untuk informasi selengkapnya tentang cara menggunakan CMakePresets.json di Visual Studio Code, lihat Mengonfigurasi dan membangun dengan CMake Presets di VISUAL Code

Peta vendor Pengaturan Visual Studio

Satu peta vendor dengan URI microsoft.com/VisualStudioSettings/CMake/<version> vendor diizinkan per Mengonfigurasi Preset dan berisi opsi khusus untuk integrasi CMake di Visual Studio dan Visual Studio Code. Semua opsi dalam peta vendor berlaku untuk Visual Studio. Opsi yang berlaku untuk Visual Studio dan Visual Studio Code telah ditandai secara eksplisit.

Semua pengaturan di peta vendor Pengaturan Visual Studio bersifat opsional dan diwarisi dari Konfigurasi Preset yang ditentukan oleh kunci inherits . Hanya opsi yang telah dimodifikasi yang ditulis ke file. Peta vendor Pengaturan Visual Studio didukung oleh CMakePresets.json dan CMakeUserPresets.json.

Opsi dalam peta vendor Pengaturan Visual Studio tidak memengaruhi konstruksi baris perintah CMake atau CTest. Ini sehingga file yang sama CMakePresets.json dapat digunakan untuk mendorong CMake dengan Visual Studio, Visual Studio Code, dan dari baris perintah. Pengecualian adalah cacheRoot opsi dan cmakeGenerateCommand . Opsi ini khusus untuk skenario Buka Cache yang Ada di Visual Studio dan tidak dapat direprovisi dari baris perintah.

Pengaturan Deskripsi
hostOS Array sistem operasi (OS) yang didukung. Nilai yang diterima adalah Windows, Linux, dan macOS.

Nilai hostOS digunakan oleh Visual Studio dan Visual Studio Code untuk menyembunyikan Konfigurasi Preset yang tidak berlaku untuk OS sistem target dan memberikan pengalaman pengguna yang lebih baik.

Jika hostOS tidak ditentukan, maka Visual Studio dan Visual Studio Code akan selalu menampilkan semua Preset Konfigurasi untuk pilihan. Bidang ini juga dapat berupa string, yang setara dengan array yang berisi satu string

Opsi ini didukung oleh Visual Studio dan Visual Studio Code.
intelliSenseMode Menentukan mode yang digunakan untuk menghitung informasi IntelliSense di Visual Studio dengan format <target>-<toolset>-<arch>.

Nilai yang diterima:

android-clang-arm
android-clang-arm64
android-clang-x6
android-clang-x86
ios-clang-ar
ios-clang-arm64
ios-clang-x6
ios-clang-x86
linux-gcc-arm
linux-gcc-x64
linux-gcc-x86
windows-clang-arm
windows-clang-arm64
windows-clang-x64
windows-clang-x86
windows-msvc-arm
windows-msvc-arm64
windows-msvc-x64
windows-msvc-x86

Jika intelliSenseMode tidak ditentukan, Visual Studio menggunakan mode IntelliSense yang cocok dengan kompilator dan arsitektur target yang Anda tentukan. intelliSenseMode sering digunakan untuk menyediakan IntelliSense yang ditingkatkan untuk kompilasi silang.

Di Visual Studio 2019, Anda harus secara eksplisit menentukan mode IntelliSense clang saat membangun dengan clang atau clang-cl.
intelliSenseOptions Peta opsi konfigurasi IntelliSense tambahan.

useCompilerDefaults: Yang bool menentukan apakah akan menggunakan default kompilator menentukan dan menyertakan jalur untuk IntelliSense. Seharusnya hanya false jika pengkompilasi yang digunakan tidak mendukung argumen gaya gcc. Default ke true.

additionalCompilerArgs: Array opsi tambahan untuk mengontrol IntelliSense di Visual Studio. Opsi ini mendukung ekspansi makro.
enableMicrosoftCodeAnalysis bool Yang memungkinkan analisis kode Microsoft di Visual Studio saat membangun dengan cl atau clang-cl. Default ke false.
codeAnalysisRuleset Menentukan aturan yang akan digunakan saat menjalankan analisis kode Microsoft di Visual Studio. Anda dapat menggunakan jalur ke file ruleset, atau nama file ruleset yang diinstal dengan Visual Studio. Opsi ini mendukung ekspansi makro.
disableExternalAnalysis bool Yang menentukan apakah analisis kode harus berjalan pada header eksternal di Visual Studio.
codeAnalysisExternalRuleset Menentukan set aturan yang akan digunakan saat menjalankan analisis kode Microsoft pada header eksternal di Visual Studio. Anda dapat menggunakan jalur ke file ruleset, atau nama file ruleset yang diinstal dengan Visual Studio. Opsi ini mendukung ekspansi makro.
enableClangTidyCodeAnalysis Bool yang memungkinkan analisis kode clang-rapi di Visual Studio saat membangun dengan clang-cl. Default ke false.
clangTidyChecks Daftar peringatan yang dipisahkan koma diteruskan ke clang-rapi saat menjalankan analisis kode clang-rapi di Visual Studio. Kartubebas diperbolehkan, dan awalan - akan menghapus pemeriksaan.
cacheRoot Menentukan jalur ke cache CMake. Direktori ini harus berisi file yang ada CMakeCache.txt . Kunci ini hanya didukung oleh skenario Buka Cache yang Ada di Visual Studio. Opsi ini mendukung ekspansi makro.
cmakeGenerateCommand Alat baris perintah (ditentukan sebagai program baris perintah dan argumen, misalnya, gencache.bat debug) untuk menghasilkan cache CMake. Perintah ini berjalan di shell menggunakan lingkungan preset yang ditentukan saat konfigurasi CMake dipanggil. Kunci ini hanya didukung oleh skenario Buka Cache yang Ada di Visual Studio. Opsi ini mendukung ekspansi makro.

Peta vendor Pengaturan Jarak Jauh Visual Studio

Satu peta vendor dengan URI microsoft.com/VisualStudioRemoteSettings/CMake/<version> vendor diizinkan per Mengonfigurasi Preset dan berisi opsi khusus untuk pengembangan jarak jauh di Visual Studio. Pengembangan jarak jauh berarti Anda memanggil CMake pada koneksi SSH jarak jauh atau WSL. Tidak ada opsi di peta vendor Pengaturan Jarak Jauh Visual Studio yang berlaku untuk Visual Studio Code.

Semua pengaturan di peta vendor Pengaturan Jarak Jauh Visual Studio bersifat opsional dan diwarisi dari Konfigurasi Preset yang ditentukan oleh inherits kunci. Hanya opsi yang telah dimodifikasi yang ditulis ke file. Peta vendor Pengaturan Jarak Jauh Visual Studio didukung oleh CMakePresets.json dan CMakeUserPresets.json.

Opsi dalam peta vendor Pengaturan Visual Studio tidak memengaruhi konstruksi baris perintah CMake atau CTest. Ini sehingga file yang sama CMakePresets.json dapat digunakan untuk mendorong CMake dengan Visual Studio, Visual Studio Code, dan dari baris perintah.

Banyak opsi di peta vendor Pengaturan Jarak Jauh Visual Studio diabaikan saat menargetkan WSL1. Ini karena toolset WSL1 menjalankan semua perintah secara lokal dan bergantung pada drive Windows yang dipasang di bawah /mnt folder untuk mengakses file sumber lokal dari WSL1. Tidak diperlukan salinan file sumber. Opsi yang diabaikan saat menargetkan WSL1 telah ditandai secara eksplisit.

Pengaturan Deskripsi
sourceDir Jalur ke direktori pada sistem jarak jauh tempat proyek akan disalin. Default ke $env{HOME}/.vs/$ms{projectDirName}. Opsi ini mendukung ekspansi makro.

Dalam skenario salinan jarak jauh, makro ${sourceDir} mengevaluasi ke direktori sumber proyek pada sistem jarak jauh dan bukan direktori sumber proyek pada komputer Windows. Skenario salinan jarak jauh termasuk menargetkan koneksi SSH jarak jauh. Dalam kasus ini, direktori sumber proyek pada sistem jarak jauh ditentukan oleh nilai sourceDir dalam peta vendor Pengaturan Jarak Jauh Visual Studio. Opsi ini diabaikan saat menargetkan WSL1.
copySources Jika true, Visual Studio akan menyalin sumber dari Windows ke sistem jarak jauh. Atur ke false jika Anda mengelola sinkronisasi file sendiri. Default ke true. Opsi ini diabaikan saat menargetkan WSL1.
copySourcesOptions Objek opsi yang terkait dengan salinan sumber dari Windows ke sistem jarak jauh. Objek ini diabaikan ketika menargetkan WSL1.

copySourcesOptions.exclusionList: Daftar jalur yang akan dikecualikan saat menyalin file sumber ke sistem jarak jauh. Jalur dapat berupa nama file atau direktori, atau jalur relatif dari akar salinan. Default ke [ ".vs", ".git", "out" ]. Opsi ini mendukung ekspansi makro.

copySourcesOptions.method: Metode yang digunakan untuk menyalin file sumber ke sistem jarak jauh. Nilai yang diterima adalah rsync dan sftp. Default ke rsync.

copySourcesOptions.concurrentCopies: Jumlah salinan bersamaan yang digunakan selama sinkronisasi sumber ke sistem jarak jauh. Default ke 5.

copySourcesOptions.outputVerbosity: Tingkat verbositas operasi salinan sumber ke sistem jarak jauh. Tingkat yang diterima adalah Normal, Verbose, dan Diagnostic. Default ke Normal.
rsyncCommandArgs Daftar argumen baris perintah diteruskan ke rsync. Default ke [ "-t", "--delete", "--delete-excluded" ]. Opsi ini mendukung ekspansi makro dan diabaikan saat menargetkan WSL1.
copyBuildOutput Menentukan apakah akan menyalin output build dari sistem jarak jauh kembali ke Windows. Default ke false. Opsi ini diabaikan saat menargetkan WSL1.
copyOptimizations Objek opsi yang terkait dengan pengoptimalan salinan sumber. Opsi ini diabaikan saat menargetkan WSL1.

copyOptimizations.maxSmallChange: Jumlah maksimum file yang akan disalin menggunakan sftp alih-alih rsync. Default ke 10.

copyOptimizations.useOptimizations: Menentukan pengoptimalan salinan yang digunakan. Nilai yang diterima tidak ada pengoptimalan salinan (None), pengoptimalan rsync saja (RsyncOnly), atau pengoptimalan rsync dan sftp (RsyncAndSftp). Default ke RsyncAndSftp.

copyOptimizations.rsyncSingleDirectoryCommandArgs: Daftar argumen baris perintah yang diteruskan ke rsync saat menyalin konten direktori tunggal ke sistem jarak jauh. Default ke [ "-t", "-d" ]. Opsi ini mendukung ekspansi makro.
copyAdditionalIncludeDirectoriesList Daftar jalur ke direktori header jarak jauh yang akan disalin secara lokal untuk IntelliSense. Opsi ini mendukung ekspansi makro.
copyExcludeDirectoriesList Daftar jalur ke direktori header jarak jauh yang tidak akan disalin secara lokal untuk IntelliSense. Opsi ini mendukung ekspansi makro.
forceWSL1Toolset Jika true, Visual Studio akan selalu menggunakan toolset WSL1 saat menargetkan WSL dari Visual Studio. Toolset WSL1 menjalankan semua perintah secara lokal dan bergantung pada drive Windows yang dipasang di bawah /mnt folder untuk mengakses file sumber lokal dari WSL. Opsi ini mungkin lebih lambat dengan WSL2. Default ke false.

Toolset WSL1 akan selalu digunakan di Visual Studio 2019 versi 16.10. Opsi ini akan relevan setelah dukungan asli untuk WSL2 tersedia.

Peristiwa pra-build dan pasca-build jarak jauh

Opsi untuk remotePrebuildEvent dan remotePostbuildEvent telah ditolak dengan adopsi CMakePresets.json.

Enkode peristiwa pra-build, pra-tautan, dan pasca-build di Anda CMakeLists.txt menggunakan add_custom_command. Ini memastikan perilaku yang sama saat membangun dengan Visual Studio dan dari baris perintah.

Jika Anda memerlukan perilaku yang khusus untuk Visual Studio, Anda dapat menambahkan tugas jarak jauh kustom di tasks.vs.json. Untuk memulai, klik kanan pada akar CMakeLists.txt Anda di Penjelajah Solusi dari Tampilan Folder dan pilih Konfigurasikan Tugas. Anda kemudian dapat menambahkan tugas jarak jauh baru ke file Anda tasks.vs.json .

Tugas jarak jauh berikut membuat direktori yang disebut pengujian pada sistem Linux jarak jauh:

{
      "taskLabel": "mkdir",
      "appliesTo": "CMakeLists.txt",
      "type": "remote",
      "command": "mkdir test",
      "remoteMachineName": "localhost"
  }

Klik kanan pada apa pun CMakeLists.txt dan pilih opsi mkdir untuk menjalankan tugas ini.

Nilai remoteMachineName harus cocok dengan Nama Host koneksi di Pengelola Sambungan.

Makro vendor Microsoft

Dua peta vendor Microsoft, Visual Studio Settings dan Visual Studio Remote Settings, mendukung semua makro yang ditentukan oleh CMake. Peta vendor kami mendukung semua makro yang ditentukan oleh CMake. Untuk informasi selengkapnya, lihat Ekspansi Makro cmake-presets. Semua makro dan variabel lingkungan diperluas sebelum diteruskan ke CMake.

Visual Studio mendukung makro vendor dengan awalan ms. Makro vendor Microsoft hanya dapat digunakan di peta vendor Microsoft. CMake tidak dapat menggunakan preset yang memiliki makro vendor di luar peta vendor.

Makro Deskripsi
$ms{projectDirName} Mengevaluasi ke nama folder yang terbuka di Visual Studio. Makro ini digunakan untuk mengatur nilai sourceDir default dalam skenario salinan jarak jauh. Makro ini tidak didukung oleh Visual Studio Code. Gunakan ${sourceDirName} sebagai gantinya.

Variabel lingkungan

Makro Deskripsi
$env{<variable-name>}
$penv{<variable-name>}		 Mereferensikan variabel lingkungan menggunakan sintaks ini yang didukung oleh CMake. Untuk informasi selengkapnya, lihat Ekspansi Makro cmake-presets.

Makro yang tidak digunakan lagi

Beberapa makro yang didukung oleh CMakeSettings.json telah ditolak dengan adopsi CMakePresets.json.

Gunakan makro yang didukung oleh CMake untuk membuat jalur file Anda. Saat Anda menggunakan makro, itu memastikan bahwa file yang sama CMakePresets.json berfungsi di dalam Visual Studio dan dari baris perintah.

Makro yang tidak digunakan lagi Rekomendasi
${projectFile} ${sourceDir}/CMakeLists.txt
${thisFile} ${sourceDir}/CMakePresets.json

Sintaks shell yang diterima

Gunakan sintaks untuk $env{HOME} mereferensikan $HOME saat membuat jalur Linux di peta vendor Microsoft.