Mengonfigurasi dan membangun dengan CMake Presets di Visual Studio

Artikel
10/12/2023

CMake mendukung dua file yang memungkinkan pengguna menentukan opsi konfigurasi, build, dan pengujian umum dan membagikannya dengan orang lain: CMakePresets.json dan CMakeUserPresets.json. Gunakan file-file ini untuk mendorong CMake di Visual Studio dan Visual Studio Code, dalam alur integrasi berkelanjutan (CI), dan dari baris perintah.

CMakePresets.json adalah untuk menyimpan build di seluruh proyek. CMakeUserPresets.json adalah bagi pengembang untuk menyimpan build lokal mereka sendiri. Kedua file didukung di Visual Studio 2019 versi 16.10 atau yang lebih baru.

Artikel ini berisi informasi tentang CMakePresets.json integrasi dengan Visual Studio. Berikut adalah tautan bermanfaat:

Untuk informasi selengkapnya tentang format CMakePresets.json, lihat dokumentasi CMake resmi.
Untuk informasi selengkapnya tentang peta vendor Microsoft dan ekspansi makro, lihat CMakePresets.json dan CMakeUserPresets.json peta vendor Microsoft.
Untuk informasi selengkapnya tentang cara menggunakan CMakePresets.json di Visual Studio Code, lihat Mengonfigurasi dan membangun dengan CMake Presets.

Kami merekomendasikan CMakePresets.json sebagai alternatif untuk CMakeSettings.json. Visual Studio tidak pernah membaca dari dan CMakePresets.jsonCMakeSettings.json pada saat yang sama. Untuk mengaktifkan atau menonaktifkan CMakePresets.json integrasi di Visual Studio, lihat Mengaktifkan CMakePresets.json di Visual Studio 2019.

CMake dan `CMakePresets.json` versi yang didukung

Versi yang didukung CMakePresets.json dan CMakeUserPresets.json skema bergantung pada versi Visual Studio Anda:

Visual Studio 2019 versi 16.10 dan yang lebih baru mendukung skema versi 2 dan 3.
Visual Studio 2022 versi 17.4 pratinjau 1 menambahkan dukungan untuk skema versi 4.
Visual Studio 2022 versi 17.5 pratinjau 1 menambahkan dukungan untuk skema versi 5.

Anda dapat memperbarui versi dengan mengubah "version" bidang di objek akar. Untuk contoh dan informasi selengkapnya, lihat CMakePresets.json format.

CMake versi 3.20 atau yang lebih baru diperlukan saat Anda memanggil CMake dengan CMakePresets.json dari baris perintah. Namun, Visual Studio membaca dan mengevaluasi CMakePresets.json serta CMakeUserPresets.json dirinya sendiri dan tidak memanggil CMake secara langsung dengan opsi .--preset Jadi, CMake versi 3.20 atau yang lebih baru tidak diperlukan secara ketat saat Anda membangunnya di CMakePresets.json dalam Visual Studio.

Sebaiknya gunakan setidaknya CMake versi 3.14 atau yang lebih baru.

Mengaktifkan `CMakePresets.json` integrasi di Visual Studio

CMakePresets.json integrasi tidak diaktifkan secara default di Visual Studio. Anda dapat mengaktifkannya di Opsi>Alat>CMake>Umum:

Screenshot showing 'Always use CMakePresets.json' selected.

Penting

Tutup dan buka kembali folder di Visual Studio untuk mengaktifkan integrasi.

Di beberapa versi Visual Studio yang lebih lama, Opsi>Alat>CMake>General hanya memiliki satu opsi untuk mengaktifkan CMakePresets.json integrasi:

Screenshot of an older version of Visual Studio. There is a checkbox labeled 'Use C Make Presets .json to drive CMake configure, build, and test.'

Tabel berikut menunjukkan kapan CMakePresets.json digunakan alih-alih CMakeSettings.json untuk mendorong konfigurasi dan build CMake di Visual Studio 2022 dan Visual Studio 2019 versi 16.10 dan yang lebih baru. Jika tidak ada file konfigurasi, default Konfigurasikan Preset akan digunakan.

Dalam tabel, "Opsi Alat>diaktifkan" berarti Gunakan CMakePresets.json untuk mendorong CMake mengonfigurasi, membangun, dan menguji dipilih di Opsi>Alat>CMake>Umum.

File konfigurasi	Opsi Alat > dinonaktifkan	Opsi Alat > diaktifkan
Tidak ada file konfigurasi yang ada	`CMakeSettings.json`	`CMakePresets.json`
`CMakeSettings.json` Hadir	`CMakeSettings.json`	`CMakePresets.json`
`CMakePresets.json` Hadir	`CMakePresets.json`	`CMakePresets.json`
Kedua file konfigurasi ada	`CMakePresets.json`	`CMakePresets.json`

Mengubah konfigurasi otomatis dan pemberitahuan cache

Secara default, Visual Studio secara otomatis memanggil configure setiap kali Sistem Target aktif atau Mengonfigurasi perubahan Prasetel. Anda dapat mengubah perilaku ini dengan memilih Jangan pernah menjalankan langkah konfigurasi secara otomatis di Opsi>Alat>CMake>Umum. Anda juga dapat menonaktifkan semua pemberitahuan cache CMake (bilah emas) dengan menghapus pemberitahuan Tampilkan cache CMake.

Preset Konfigurasi Default

Jika tidak ada CMakePresets.json atau CMakeUserPresets.json file ada, atau jika CMakePresets.json atau CMakeUserPresets.json tidak valid, Visual Studio akan kembali pada Default Konfigurasi Preset berikut:

Contoh Windows

{
  "name": "windows-default",
  "displayName": "Windows x64 Debug",
  "description": "Sets Ninja generator, compilers, x64 architecture, build and install directory, debug build type",
  "generator": "Ninja",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "architecture": {
    "value": "x64",
    "strategy": "external"
  },
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
  },
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": [ "Windows" ]
    }
  }
},

Contoh Linux

{
  "name": "linux-default",
  "displayName": "Linux Debug",
  "description": "Sets Ninja generator, compilers, build and install directory, debug build type",
  "generator": "Ninja",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
  },
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": [ "Linux" ]
    },
    "microsoft.com/VisualStudioRemoteSettings/CMake/1.0": {
      "sourceDir": "$env{HOME}/.vs/$ms{projectDirName}"
   }
  }
}

Jika Anda mencoba membuka atau memodifikasi CMakePresets.json file yang tidak ada, Visual Studio secara otomatis membuat CMakePresets.json file dengan Preset Konfigurasi default di akar proyek Anda.

Mengonfigurasi dan membangun

Pada toolbar Visual Studio, ada dropdown untuk Sistem Target, Konfigurasikan Preset, dan Build Preset saat CMakePresets.json integrasi diaktifkan:

Screenshot showing the dropdowns for target system set to Local Machine, configuration set to windows-arm64, and build preset set to default.

Pilih Sistem Target

Daftar dropdown di sebelah kiri menunjukkan Sistem Target aktif. Ini adalah sistem tempat CMake dipanggil untuk mengonfigurasi dan membangun proyek. Daftar dropdown ini mencakup komputer lokal Anda, semua koneksi SSH di Pengelola Sambungan berdasarkan nama host, dan semua penginstalan Subsistem Windows untuk Linux (WSL) yang dapat ditemukan Visual Studio:

Screenshot of the Target System dropdown list

Dalam contoh sebelumnya:

192.168.0.5 adalah sistem Linux jarak jauh yang ditambahkan ke Pengelola Sambungan.
ubuntu2004 dan debian adalah instalasi WSL.

Pilih Kelola Koneksi untuk membuka Pengelola Sambungan.

Pilih Prasetel Konfigurasi

Daftar dropdown di tengah menunjukkan Preset Konfigurasi aktif. Ini adalah configurePreset nilai yang digunakan saat CMake dipanggil untuk menghasilkan sistem build proyek. Daftar dropdown ini mencakup penyatuan Preset Konfigurasi yang tidak tersembunyi yang ditentukan dalam CMakePresets.json dan CMakeUserPresets.json.

Visual Studio menggunakan nilai hostOS dalam peta vendor Microsoft Visual Studio Pengaturan untuk menyembunyikan Konfigurasi Preset yang tidak berlaku untuk Sistem Target aktif. Untuk informasi selengkapnya, lihat entri untuk hostOS dalam tabel di bawah Visual Studio Pengaturan peta vendor.

Pilih Kelola Konfigurasi untuk membuka file yang CMakePresets.json terletak di akar proyek. CMakePresets.json dibuat jika belum ada.

Pilih Build Preset

Daftar dropdown di sebelah kanan menunjukkan Preset Build aktif. Ini adalah buildPreset nilai yang digunakan saat CMake dipanggil untuk membangun proyek. Daftar dropdown ini mencakup penyatuan Preset Build yang tidak tersembunyi yang ditentukan dalam CMakePresets.json dan CMakeUserPresets.json.

Semua Preset Build diperlukan untuk menentukan nilai terkait configurePreset . Visual Studio menyembunyikan Preset Build yang tidak berlaku untuk Preset Konfigurasi aktif. Untuk informasi selengkapnya, lihat daftar Build Presets.

Jika tidak ada Preset Build yang terkait dengan Preset Konfigurasi aktif, Visual Studio mencantumkan Build Preset default. Preset Build default setara dengan meneruskan cmake --build tanpa argumen lain dari baris perintah.

Mengonfigurasi

Visual Studio secara otomatis mencoba mengonfigurasi proyek saat mendeteksi bahwa cache CMake sudah kedaluarsa. Untuk memanggil konfigurasi secara manual, pilih Project>Configure <project-name> dari menu utama. Ini sama dengan berjalan cmake --preset <configurePreset> dari baris perintah, di mana <configurePreset> adalah nama Preset Konfigurasi aktif.

Untuk menonaktifkan pembuatan cache otomatis, lihat Konfigurasi otomatis dan pemberitahuan cache.

Bangun

Untuk membangun seluruh proyek, pilih Build>All dari menu utama. Ini sama dengan berjalan cmake --build --preset <buildPreset> dari baris perintah, di mana <buildPreset> adalah nama Preset Build aktif.

Untuk membuat satu target, beralihlah ke Tampilan Target CMake di Penjelajah Solusi. Kemudian klik kanan target apa pun dan pilih Bangun dari menu pintasan.

Catatan

Visual Studio 2019 tidak mendukung buildPresets.targets opsi untuk membangun subset target yang ditentukan dalam CMakePresets.json.

Jalankan CTest

CMakePresets.json mendukung dua opsi menu di Visual Studio 2019:

Uji>Jalankan CTests untuk <nama> proyek memanggil CTest dan menjalankan semua pengujian yang terkait dengan Preset Konfigurasi dan Build Preset aktif, tanpa argumen lain yang diteruskan ke CTest.
Uji>Coba Uji Prasetel untuk <konfigurasiPreset> diperluas untuk menampilkan semua Preset Pengujian yang terkait dengan Preset Konfigurasi aktif. Memilih Satu Preset Pengujian sama dengan berjalan ctest --preset <testPreset> dari baris perintah, di mana <testPreset> adalah nama Preset Pengujian yang dipilih. Opsi ini tidak tersedia jika tidak ada Preset Pengujian yang ditentukan untuk Preset Konfigurasi aktif.

Di Visual Studio 2019, Test Explorer tidak terintegrasi dengan CMakePresets.json.

Menambahkan prasetel baru

Di Visual Studio 2019, semua perintah dan templat prasetel memodifikasi CMakePresets.json. Anda dapat menambahkan preset tingkat pengguna baru dengan langsung mengedit CMakeUserPresets.json.

Gunakan garis miring (/) untuk jalur di CMakePresets.json dan CMakeUserPresets.json.

Menambahkan Prasetel Konfigurasi baru

Untuk menambahkan Preset Konfigurasi baru ke CMakePresets.json, dari Penjelajah Solusi, klik CMakePresets.json kanan dari Tampilan Folder dan pilih Tambahkan Konfigurasi dari menu pintasan. Dialog untuk memilih templat KonfigurasiKan Prasetel muncul:

Screenshot of the Add Configure Preset to the JSON file dialog. It contains entries such as Linux Debug, macOS Debug, x64 Debug, and so on.

Pilih templat Windows x64 Debug untuk dikonfigurasi pada sistem Windows. Pilih templat Linux Debug untuk dikonfigurasi pada WSL dan sistem Linux jarak jauh. Untuk informasi selengkapnya tentang pengeditan CMakePresets.json, lihat Mengedit prasetel.

Templat yang dipilih ditambahkan ke CMakePresets.json jika ada. Jika tidak, templat disalin ke dalam file baru CMakePresets.json .

Menambahkan Preset Build dan Preset Pengujian baru

Visual Studio 2019 tidak menawarkan templat untuk Preset Build dan Preset Pengujian baru. Anda dapat menambahkan Build Presets dan Test Presets dengan langsung mengedit CMakePresets.json. Untuk informasi selengkapnya, lihat daftar Preset Build, daftar Preset Pengujian, atau file contohCMakePresets.json.

Mengedit prasetel

Dokumentasi CMake resmi adalah sumber daya terbaik untuk mengedit Mengonfigurasi Preset, Build Presets, dan Test Presets. Informasi berikut adalah subset dokumentasi CMake yang sangat relevan dengan pengembang Visual Studio.

Pilih pengkompilasi Anda

Anda dapat mengatur pengkompilasi C dan C++ dengan menggunakan cacheVariables.CMAKE_C_COMPILER dan cacheVariables.CMAKE_CXX_COMPILER dalam Prasetel Konfigurasi. Ini setara dengan meneruskan -D CMAKE_C_COMPILER=<value> dan -D CMAKE_CXX_COMPILER=<value> ke CMake dari baris perintah. Untuk informasi selengkapnya, lihat CMAKE_<LANG>_COMPILER .

Gunakan contoh berikut untuk membangun dengan cl.exe dan clang-cl.exe dari Visual Studio. Alat C++ Clang untuk komponen Windows harus diinstal agar Anda dapat membangun dengan clang-cl.

Bangun dengan cl.exe:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "cl",
  "CMAKE_CXX_COMPILER": "cl"
},

Bangun dengan clang:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "clang-cl",
  "CMAKE_CXX_COMPILER": "clang-cl"
},

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
  }
}

Jika Anda menggunakan salah satu Visual Studio 16 2019 atau Visual Studio 17 2022 sebagai generator, Anda dapat menggunakan toolset Preset Konfigurasi untuk menentukan toolset ClangCL :

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
},

"toolset": "ClangCL",

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
  }
}

Untuk informasi selengkapnya tentang generator yang mendukung toolset spesifikasi, lihat CMAKE_GENERATOR_TOOLSET dalam dokumentasi CMake.

Penting

Di Visual Studio 2019, Anda harus secara eksplisit menentukan mode Clang IntelliSense saat membangun dengan clang atau clang-cl.

Untuk mereproduksi build ini di luar Visual Studio, lihat Menjalankan CMake dari baris perintah atau alur CI.

Untuk membangun di Linux atau tanpa toolset Visual C++, tentukan nama pengkompilasi pada instans Anda PATH , atau variabel lingkungan yang mengevaluasi ke jalur lengkap pengkompilasi. Jalur lengkap tidak disarankan sehingga file dapat tetap dapat dibagikan. Prasetel yang dibuat dengan GCC versi 8 mungkin terlihat seperti ini:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "gcc-8",
  "CMAKE_CXX_COMPILER": "g++-8"
},

Anda juga dapat mengatur pengkompilasi dengan file toolchain CMake. File toolchain dapat diatur dengan , yang setara dengan cacheVariables.CMAKE_TOOLCHAIN_FILEmeneruskan -D CMAKE_TOOLCHAIN_FILE=<value> ke CMake dari baris perintah. File toolchain CMake paling sering digunakan untuk kompilasi silang. Untuk informasi selengkapnya tentang penulisan file toolchain CMake, lihat Toolchain CMake.

Pilih generator Anda

Templat Windows dan Linux Configure Preset menentukan Ninja sebagai generator default. Generator umum lainnya adalah Generator Visual Studio di Windows dan Unix Makefiles di Linux dan macOS. Anda dapat menentukan generator baru dengan generator opsi dalam Prasetel Konfigurasi. Setara dengan meneruskan -G ke CMake dari baris perintah.

Atur architecture.strategy dan toolset.strategy ke set saat Anda membangun dengan Visual Studio Generator. Untuk informasi selengkapnya, lihat Generator CMake.

Pilih jenis konfigurasi Anda

Anda dapat mengatur jenis konfigurasi (Debug atau Release) untuk generator konfigurasi tunggal dengan menggunakan cacheVariables.CMAKE_BUILD_TYPE. Setara dengan meneruskan -D CMAKE_BUILD_TYPE=<value> ke CMake dari baris perintah. Untuk informasi selengkapnya, lihat CMAKE_BUILD_TYPE .

Pilih arsitektur target dan host Anda saat membangun dengan toolset Visual C++

Anda dapat mengatur arsitektur target (x64, Win32, ARM64, atau ARM) dengan menggunakan architecture.value. Setara dengan meneruskan -A ke CMake dari baris perintah. Untuk informasi selengkapnya, lihat Pemilihan Platform.

Catatan

Saat ini, Visual Studio Generators mengharapkan sintaks Win32 dan generator baris perintah (seperti Ninja) mengharapkan sintaks x86 saat Anda membangun untuk x86.

Anda dapat mengatur arsitektur host (x64 atau x86) dan toolset dengan menggunakan toolset.value. Setara dengan meneruskan -T ke CMake dari baris perintah. Untuk informasi selengkapnya, lihat Pilihan Toolset.

Nilai architecture.strategy dan toolset.strategy memberi tahu CMake cara menangani bidang arsitektur dan toolset. set berarti CMake menetapkan nilai masing-masing, dan external berarti CMake tidak akan menetapkan nilai masing-masing.

Sebaiknya gunakan set dengan generator IDE seperti Visual Studio Generator. Gunakan external dengan generator baris perintah seperti Ninja. Nilai-nilai ini memungkinkan vendor seperti Visual Studio untuk menyediakan lingkungan yang diperlukan sebelum CMake dipanggil. Untuk informasi selengkapnya tentang bidang arsitektur dan toolset, lihat daftar Mengonfigurasi Preset.

Jika Anda tidak ingin sumber lingkungan, Anda dapat mengatur architecture.strategy ke external dan architecture.value ke unspecified. Anda mungkin merasa berguna untuk tidak sumber lingkungan karena salah satu alasan berikut:

Anda menggunakan toolset selain MSVC.
Anda menggunakan toolchain kustom, seperti dalam skenario yang disematkan.
Anda tidak memerlukan lingkungan tertentu untuk membangun.

Untuk daftar lengkap generator IDE yang mendukung bidang arsitektur, lihat CMAKE_GENERATOR_PLATFORM. Untuk daftar lengkap generator IDE yang mendukung bidang toolset, lihat CMAKE_GENERATOR_TOOLSET.

Gunakan contoh berikut untuk menargetkan ARM64 dengan generator Ninja, atau untuk menargetkan Win32 (x86) dengan generator Visual Studio 16 2019:

"generator": "Ninja",
"architecture": {
    "strategy": "external",
    "value": "arm64"
},

"generator": "Visual Studio 16 2019",
"architecture": {
    "strategy": "set",
     "value": "Win32"
},

Mengatur dan mereferensikan variabel lingkungan

Anda dapat mengatur variabel lingkungan dengan menggunakan peta lingkungan. Variabel lingkungan diwariskan melalui inherits bidang , tetapi Anda dapat mengambil alihnya sesuai keinginan Anda.

Lingkungan prasetel adalah persatuan lingkungannya sendiri dan lingkungan dari semua orang tuanya. Jika beberapa inherits prasetel memberikan nilai yang bertentangan untuk variabel yang sama, preset sebelumnya dalam inherits daftar lebih disukai. Anda dapat membatalkan set variabel yang diwarisi dari preset lain dengan mengaturnya ke null.

Variabel lingkungan yang diatur dalam Preset Konfigurasi juga secara otomatis mengalir ke Preset Build dan Preset Pengujian terkait, kecuali inheritConfigureEnvironment diatur ke false. Untuk informasi selengkapnya, lihat daftar Konfigurasi Preset.

Anda dapat mereferensikan variabel lingkungan dengan menggunakan $env{<variable-name>} sintaks dan $penv{<variable-name>} . Untuk informasi selengkapnya, lihat Ekspansi Makro.

Mengonfigurasi IntelliSense untuk pengkompilasi silang

Secara default, Visual Studio menggunakan mode IntelliSense yang cocok dengan set alat dan arsitektur target yang Anda tentukan. Jika Anda mengkompilasi silang, Anda mungkin perlu menentukan mode IntelliSense yang benar secara manual dengan menggunakan intelliSenseMode opsi di peta vendor Visual Studio Pengaturan. Untuk informasi selengkapnya, lihat entri untuk intelliSenseMode dalam tabel di bawah Visual Studio Pengaturan peta vendor.

Mengonfigurasi dan membangun pada sistem jarak jauh atau Subsistem Windows untuk Linux

Dengan CMakePresets.json dukungan di Visual Studio, Anda dapat dengan mudah mengonfigurasi dan membangun proyek Anda di Windows, WSL, dan sistem jarak jauh. Langkah-langkah untuk mengonfigurasi dan membangun proyek Anda di Windows, sistem jarak jauh, atau WSL sama. Namun, beberapa perilaku khusus untuk pengembangan jarak jauh.

`${sourceDir}` perilaku dalam skenario penyalinan jarak jauh

Dalam skenario lokal (termasuk WSL1), ${sourceDir} mengevaluasi ke jalur ke direktori sumber proyek yang terbuka di Visual Studio. Dalam skenario salinan jarak jauh, ${sourceDir} mengevaluasi ke jalur ke direktori sumber proyek pada Sistem Target dan bukan direktori sumber proyek pada komputer lokal.

Nilai sourceDir dalam peta vendor Visual Studio Remote Pengaturan menentukan direktori sumber proyek pada Sistem Target (default ke $env{HOME}/.vs/$ms{projectDirName}). Untuk informasi selengkapnya, lihat entri untuk sourceDir dalam tabel di bawah Visual Studio Pengaturan peta vendor.

Folder lokal untuk output jarak jauh

Skenario salinan jarak jauh memerlukan direktori lokal untuk menyalin beberapa file jarak jauh seperti file respons CMake File API atau file build jika copyBuildOutput di peta vendor Visual Studio Remote Pengaturan diatur ke true. File-file ini secara otomatis disalin ke <local-source-directory>/out/<remote-connection-ID>/build/${presetName}.

Memanggil Prasetel Konfigurasi yang sama pada Windows dan WSL1

Anda akan melihat kesalahan jika mencoba menggunakan Konfigurasi Preset yang sama di Windows dan WSL1. Windows dan WSL1 keduanya menggunakan sistem file Windows, sehingga CMake akan mencoba menggunakan direktori output yang sama (binaryDir) untuk pohon build Windows dan WSL1.

Jika Anda ingin menggunakan Preset Konfigurasi yang sama dengan Windows dan toolset WSL1, buat Preset Konfigurasi kedua yang mewarisi dari preset asli dan menentukan nilai baru binaryDir . Dalam contoh berikut, windows-preset dapat digunakan pada Windows dan base-preset dapat digunakan pada WSL1:

{
  "name": "windows-preset",
  "inherits": "base-preset",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": "Windows"
    }
  }
}

Catatan

Di Visual Studio 2019, hanya toolset WSL1 yang didukung. Anda akan melihat perilaku ini setiap kali Anda memanggil configure di Windows dan WSL.

Mengaktifkan integrasi vcpkg

Vcpkg membantu Anda mengelola pustaka C dan C++ di Windows, Linux, dan macOS. File toolchain vcpkg (vcpkg.cmake) harus diteruskan ke CMake untuk mengaktifkan integrasi vcpkg. Untuk informasi selengkapnya, lihat dokumentasi vcpkg.

Visual Studio tidak lagi meneruskan file toolchain vcpkg Anda ke CMake secara otomatis saat CMakePresets.json integrasi diaktifkan. Perubahan ini menghilangkan perilaku khusus Visual Studio dan memastikan bahwa Anda dapat mereproduksi build dari baris perintah.

Sebagai gantinya, atur jalur ke vcpkg.cmake dengan menggunakan VCPKG_ROOT variabel lingkungan di CMakePresets.json:

"cacheVariables": {
   "CMAKE_TOOLCHAIN_FILE": {
      "value": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
       "type": "FILEPATH"
    }
 },

VCPKG_ROOT harus diatur ke akar penginstalan vcpkg Anda. Untuk informasi selengkapnya, lihat variabel lingkungan vcpkg.

Jika Anda sudah menggunakan file toolchain CMake dan ingin mengaktifkan integrasi vcpkg, lihat Menggunakan beberapa file toolchain. Ikuti instruksi tersebut untuk menggunakan file toolchain eksternal dengan proyek dengan menggunakan vcpkg.

Substitusi variabel dalam `launch.vs.json` dan `tasks.vs.json`

CMakePresets.json mendukung substitusi variabel di launch.vs.json dan tasks.vs.json. Berikut adalah beberapa pertimbangan:

Variabel lingkungan yang diatur dalam Konfigurasi Preset aktif secara otomatis mengalir melalui ke launch.vs.json dan tasks.vs.json konfigurasi. Anda dapat membatalkan pengaturan variabel lingkungan individual di dan launch.vs.jsontasks.vs.json dengan mengaturnya ke null. Contoh berikut mengatur variabel DEBUG_LOGGING_LEVEL ke null dalam launch.vs.json: "env": { "DEBUG_LOGGING_LEVEL": null }.
Nilai kunci yang diatur dalam Preset Konfigurasi aktif tersedia untuk dikonsumsi di launch.vs.json dan tasks.vs.json dengan sintaks ${cmake.<KEY-NAME>}. Misalnya, gunakan ${cmake.binaryDir} untuk mereferensikan direktori output dari Preset Konfigurasi aktif.
Variabel lingkungan individual yang diatur dalam peta lingkungan Dari Preset Konfigurasi aktif tersedia untuk dikonsumsi di launch.vs.json dan tasks.vs.json melalui sintaks ${env.<VARIABLE-NAME>}.

Perbarui file dan task.vs.json Anda launch.vs.json ke sintaks referensi CMakePresets.json alih-alih CMakeSettings.json sintaks. Makro yang mereferensikan sintaks lama CMakeSettings.json ketika CMakePresets.json file konfigurasi aktif dijadwalkan untuk penghentian dalam rilis mendatang. Misalnya, referensikan direktori output dari Preset Konfigurasi aktif dengan ${cmake.binaryDir} alih-alih ${cmake.buildRoot}, karena CMakePresets.json menggunakan binaryDir sintaks.

Pemecahan Masalah

Jika semuanya tidak berfungsi seperti yang diharapkan, Anda dapat mencoba beberapa langkah pemecahan masalah.

Jika salah satu CMakePresets.json atau CMakeUserPresets.json tidak valid, Visual Studio akan kembali pada perilaku defaultnya dan hanya menampilkan Preset Konfigurasi default. Visual Studio IntelliSense dapat membantu Anda menangkap banyak kesalahan JSON ini, tetapi tidak akan tahu apakah Anda mereferensikan prasetel dengan atau configurePreset dengan inherits nama yang salah.

Untuk memeriksa apakah file prasetel Anda valid, jalankan cmake --list-presets dari baris perintah di akar direktori proyek Anda. (CMake 3.20 atau yang lebih baru diperlukan.) Jika salah satu file tidak valid, Anda akan melihat kesalahan berikut:

CMake Error: Could not read presets from
C:/Users/<user>/source/repos/<project-name>: JSON parse error

Langkah-langkah pemecahan masalah lainnya meliputi:

Hapus cache dan konfigurasi ulang proyek (CMake: Hapus Cache dan Project>Configure <project-name).>
Tutup dan buka kembali folder di Visual Studio (File>Close Folder).
.vs Hapus folder di akar proyek Anda.

Jika Anda telah mengidentifikasi masalah, cara terbaik untuk melaporkannya adalah dengan memilih tombol Kirim Umpan Balik di sudut kanan atas Visual Studio.

Aktifkan pengelogan untuk koneksi jarak jauh

Anda dapat mengaktifkan pengelogan untuk koneksi jarak jauh jika Anda mengalami masalah saat menyambungkan atau menyalin file ke sistem jarak jauh. Untuk informasi selengkapnya, lihat Pengelogan untuk koneksi jarak jauh.

Mengaktifkan AddressSanitizer untuk Windows dan Linux

Visual Studio mendukung AddressSanitizer (ASAN), detektor kesalahan memori runtime C dan C++, untuk pengembangan Windows dan Linux. Opsi addressSanitizerEnabled dalam CMakeSettings.json mengaktifkan AddressSanitizer. CMakePresets.json tidak mendukung perilaku ini.

Sebagai gantinya, aktifkan dan nonaktifkan AddressSanitizer dengan mengatur sendiri bendera pengkompilasi dan linker yang diperlukan. Mengaturnya menghapus perilaku khusus Visual Studio dan memastikan bahwa file yang sama CMakePresets.json dapat mereproduksi build Anda dari baris perintah.

Anda dapat menambahkan sampel berikut untuk CMakeLists.txt mengaktifkan atau menonaktifkan AddressSanitizer untuk target:

option(ASAN_ENABLED "Build this target with AddressSanitizer" ON)

if(ASAN_ENABLED)
  if(MSVC)
    target_compile_options(<target> PUBLIC /fsanitize=address)
  else()
    target_compile_options(<target> PUBLIC -fsanitize=address <additional-options>)
    target_link_options(<target> PUBLIC -fsanitize=address)
  endif()
endif()

Bagian ini <additional-options> mencantumkan bendera kompilasi lainnya, seperti "-fno-omit-frame-pointer". Untuk informasi selengkapnya tentang AddressSanitizer untuk Linux, lihat Menggunakan AddressSanitizer. Untuk informasi selengkapnya tentang menggunakan AddressSanitizer dengan MSVC, lihat Menggunakan AddressSanitizer dari prompt perintah pengembang.

Teruskan bendera runtime ke AddressSanitizer dengan menggunakan ASAN_OPTIONS bidang di launch.vs.json. ASAN_OPTIONS default ke detect_leaks=0 ketika tidak ada opsi runtime lain yang ditentukan karena LeakSanitizer tidak didukung di Visual Studio.

Jalankan CMake dari baris perintah atau alur CI

Anda dapat menggunakan file dan CMakeUserPresets.json yang sama CMakePresets.json untuk memanggil CMake di Visual Studio dan dari baris perintah. Dokumentasi CMake dan CTest adalah sumber daya terbaik untuk memanggil CMake dan CTest dengan --preset. CMake versi 3.20 atau yang lebih baru diperlukan.

Sumber lingkungan saat membangun dengan generator baris perintah di Windows

Terserah pengguna untuk mengonfigurasi lingkungan sebelum CMake dipanggil dalam membangun dengan generator baris perintah. Jika Anda membangun dengan Ninja dan toolset Visual C++ di Windows, atur lingkungan sebelum CMake dipanggil untuk menghasilkan sistem build. Anda dapat melakukannya dengan memanggil vcvarsall.bat dengan architecture argumen . Argumen architecture menentukan arsitektur host dan target yang akan digunakan. Untuk informasi selengkapnya, lihat vcvarsall sintaks. Jika Anda membangun di Linux atau di Windows dengan Visual Studio Generator, Anda tidak perlu mengambil langkah ini.

Ini adalah langkah yang sama dengan yang diambil Visual Studio untuk Anda ketika IDE memanggil CMake. Visual Studio menguraikan Preset Konfigurasi aktif untuk arsitektur host dan target yang ditentukan oleh toolset dan architecture. Visual Studio kemudian sumber lingkungan yang ditentukan dari vcvarsall.bat. Ketika Anda membangun dari baris perintah Windows dengan Ninja, Anda harus mengambil langkah ini sendiri.

vcvarsall.bat diinstal dengan Alat Build untuk Visual Studio. Secara default, vcvarsall.bat diinstal di C:\Program Files (x86)\Microsoft Visual Studio\2019\<edition>\VC\Auxiliary\Build. Anda dapat menambahkan vcvarsall.bat ke PATH jika Anda sering menggunakan alur kerja baris perintah.

Contoh alur kerja baris perintah

Anda dapat menggunakan perintah berikut untuk mengonfigurasi dan membangun proyek CMake yang menggunakan Ninja untuk menargetkan ARM64 dengan alat build x64. CMake versi 3.20 atau yang lebih baru diperlukan. Jalankan perintah ini dari direktori tempat file Anda CMakePresets.json berada:

/path/to/vcvarsall.bat x64_arm64 
cmake --list-presets=all .
cmake --preset <configurePreset-name>
cmake --build --preset <buildPreset-name>

Contoh `CMakePresets.json` file

File CMakePresets.json dalam box2d-lite berisi contoh Konfigurasi Preset, Build Presets, dan Test Presets. Untuk informasi selengkapnya tentang contoh ini, lihat presentasi Pengantar CMakePresets.json. Anda dapat melihat contoh lain dalam proyek DirectXTK , yang menunjukkan banyak target build di bagiannya configurePresets .

Langkah berikutnya

Pelajari selengkapnya tentang mengonfigurasi dan men-debug proyek CMake di Visual Studio:

Proyek CMake di Visual Studio
Menyesuaikan pengaturan build CMake
Mengonfigurasi sesi penelusuran kesalahan CMake
Referensi konfigurasi CMake yang telah ditentukan sebelumnya

Share via

Mengonfigurasi dan membangun dengan CMake Presets di Visual Studio

CMake dan CMakePresets.json versi yang didukung

Mengaktifkan CMakePresets.json integrasi di Visual Studio

Mengubah konfigurasi otomatis dan pemberitahuan cache

Preset Konfigurasi Default

Contoh Windows

Contoh Linux

Mengonfigurasi dan membangun

Pilih Sistem Target

Pilih Prasetel Konfigurasi

Pilih Build Preset

Mengonfigurasi

Bangun

Jalankan CTest

Menambahkan prasetel baru

Menambahkan Prasetel Konfigurasi baru

Menambahkan Preset Build dan Preset Pengujian baru

Mengedit prasetel

Pilih pengkompilasi Anda

Pilih generator Anda

Pilih jenis konfigurasi Anda

Pilih arsitektur target dan host Anda saat membangun dengan toolset Visual C++

Mengatur dan mereferensikan variabel lingkungan

Mengonfigurasi IntelliSense untuk pengkompilasi silang

Mengonfigurasi dan membangun pada sistem jarak jauh atau Subsistem Windows untuk Linux

${sourceDir} perilaku dalam skenario penyalinan jarak jauh

Folder lokal untuk output jarak jauh

Memanggil Prasetel Konfigurasi yang sama pada Windows dan WSL1

Mengaktifkan integrasi vcpkg

Substitusi variabel dalam launch.vs.json dan tasks.vs.json

Pemecahan Masalah

Aktifkan pengelogan untuk koneksi jarak jauh

Mengaktifkan AddressSanitizer untuk Windows dan Linux

Jalankan CMake dari baris perintah atau alur CI

Sumber lingkungan saat membangun dengan generator baris perintah di Windows

Contoh alur kerja baris perintah

Contoh CMakePresets.json file

Langkah berikutnya

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan:

CMake dan `CMakePresets.json` versi yang didukung

Mengaktifkan `CMakePresets.json` integrasi di Visual Studio

`${sourceDir}` perilaku dalam skenario penyalinan jarak jauh

Substitusi variabel dalam `launch.vs.json` dan `tasks.vs.json`

Contoh `CMakePresets.json` file