Bagikan melalui

CMakeSettings.json referensi skema

Proyek CMake didukung di Visual Studio 2017 dan yang lebih baru.

File CMakeSettings.json berisi informasi yang digunakan Visual Studio untuk IntelliSense dan untuk membangun argumen baris perintah yang diteruskannya ke CMake untuk konfigurasi dan lingkungan pengkompilasi tertentu. Konfigurasi menentukan properti yang berlaku untuk platform dan jenis build tertentu, misalnya, x86-Debug atau Linux-Release. Setiap konfigurasi menentukan lingkungan, yang merangkum informasi tentang toolset kompilator, misalnya MSVC, GCC, atau Clang. CMake menggunakan argumen baris perintah untuk menghasilkan kembali file akar CMakeCache.txt dan file proyek lainnya. Nilai dapat ditimpa pada CMakeLists.txt file.

Anda dapat menambahkan atau menghapus konfigurasi di IDE lalu mengeditnya langsung di file JSON atau menggunakan editor Pengaturan CMake (Visual Studio 2019 dan yang lebih baru). Anda dapat beralih di antara konfigurasi dengan mudah di IDE untuk menghasilkan berbagai file proyek. Untuk informasi selengkapnya, lihat Menyesuaikan pengaturan build CMake di Visual Studio.

Konfigurasi

Array configurations berisi semua konfigurasi untuk proyek CMake. Untuk informasi selengkapnya tentang konfigurasi yang telah ditentukan sebelumnya, lihat Referensi konfigurasi CMake yang telah ditentukan sebelumnya. Anda dapat menambahkan sejumlah konfigurasi yang telah ditentukan sebelumnya atau kustom ke file.

Sebuah configuration memiliki properti ini:

  • addressSanitizerEnabled: Jika true, kompilasi program menggunakan AddressSanitizer. Di Linux, kompilasikan dengan -fno-omit-frame-pointer dan tingkat pengoptimalan -Os atau -Oo untuk hasil terbaik.

  • addressSanitizerRuntimeFlags: Flag runtime yang diteruskan ke AddressSanitizer dalam variabel lingkunganASAN_OPTIONS. Format: flag1=value:flag2=value2.

  • buildCommandArgs: Menentukan opsi build bawaan yang diteruskan ke CMake setelah --build --. Misalnya, melewati -v saat menggunakan generator Ninja memaksa Ninja untuk menghasilkan baris perintah. Untuk informasi selengkapnya tentang perintah Ninja, lihat Argumen baris perintah Ninja.

  • buildRoot: Menentukan direktori tempat CMake menghasilkan skrip build untuk generator yang dipilih. Peta untuk -DCMAKE_BINARY_DIR beralih dan menentukan tempat CMakeCache.txt dibuat. Jika folder tidak ada, akan dibuat. Makro yang didukung meliputi ${workspaceRoot}, , ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}. ${env.VARIABLE}

  • cacheGenerationCommand: Menentukan alat dan argumen baris perintah, misalnya gencache.bat debug untuk menghasilkan cache. Perintah dijalankan dari shell di lingkungan yang ditentukan untuk konfigurasi ketika pengguna secara eksplisit meminta regenerasi, atau file CMakeLists.txt atau CMakeSettings.json dimodifikasi.

  • cacheRoot: Menentukan jalur ke cache CMake. Direktori ini harus berisi file yang ada CMakeCache.txt .

  • clangTidyChecks: "daftar peringatan" yang dipisahkan koma yang diteruskan ke clang-tidy; wildcard diizinkan dan awalan '-' menghapus cek.

  • cmakeCommandArgs: Menentukan opsi baris perintah tambahan untuk diteruskan ke CMake saat dipanggil untuk menghasilkan file proyek.

  • cmakeToolchain: Menentukan file toolchain. Ini diteruskan ke CMake menggunakan -DCMAKE_TOOLCHAIN_FILE.

  • codeAnalysisRuleset: Menentukan set aturan yang akan digunakan saat menjalankan analisis kode. Anda dapat menggunakan jalur lengkap atau nama file ruleset yang diinstal oleh Visual Studio.

  • configurationType: Menentukan konfigurasi jenis build untuk generator yang dipilih. Mungkin salah satu dari:

    • Debug
    • Release
    • MinSizeRel
    • RelWithDebInfo

  • ctestCommandArgs: Menentukan opsi baris perintah tambahan untuk diteruskan ke CTest saat menjalankan pengujian.

  • description: Deskripsi konfigurasi ini yang muncul di menu.

  • enableClangTidyCodeAnalysis: Gunakan Clang-Tidy untuk analisis kode.

  • enableMicrosoftCodeAnalysis: Gunakan alat analisis kode Microsoft untuk analisis kode.

  • generator: Menentukan generator CMake yang akan digunakan untuk konfigurasi ini. Mungkin salah satu dari:

    Hanya Visual Studio 2019:

    • Visual Studio 16 2019
    • Visual Studio 16 2019 Win64
    • Visual Studio 16 2019 ARM

    Visual Studio 2017 dan yang lebih baru:

    • Visual Studio 15 2017
    • Visual Studio 15 2017 Win64
    • Visual Studio 15 2017 ARM
    • Visual Studio 14 2015
    • Visual Studio 14 2015 Win64
    • Visual Studio 14 2015 ARM
    • Unix Makefiles
    • Ninja

Karena Ninja dirancang untuk kecepatan build cepat alih-alih fleksibilitas dan fungsi, ini ditetapkan sebagai default. Namun, beberapa proyek CMake mungkin tidak dapat membangun dengan benar menggunakan Ninja. Jika kegagalan build terjadi, Anda dapat menginstruksikan CMake untuk menghasilkan proyek Visual Studio sebagai gantinya.

Untuk menentukan generator Visual Studio di Visual Studio 2017, buka editor pengaturan dari menu utama dengan memilih CMake | Ubah Pengaturan CMake. Hapus "Ninja" dan masukkan "V". Perubahan ini mengaktifkan IntelliSense, yang memungkinkan Anda memilih generator yang Anda inginkan.

Untuk menentukan generator Visual Studio di Visual Studio 2019, klik CMakeLists.txt kanan pada file di Penjelajah Solusi dan pilih Pengaturan CMake untuk proyek>Tampilkan Pengaturan Lanjutan>Generator CMake.

Secara default, ketika konfigurasi aktif menentukan generator Visual Studio, ia memanggil MSBuild dengan -m -v:minimal argumen. Untuk menyesuaikan build, gunakan properti buildCommandArgs di dalam file CMakeSettings.json. Di sini, Anda dapat menentukan argumen baris perintah MSBuild untuk diteruskan ke sistem build:

"buildCommandArgs": "-m:8 -v:minimal -p:PreferredToolArchitecture=x64"

  • installRoot: Menentukan direktori tempat CMake menghasilkan target penginstalan untuk generator yang dipilih. Makro yang didukung meliputi ${workspaceRoot}, , ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}. ${env.VARIABLE}

  • inheritEnvironments: Menentukan satu atau beberapa lingkungan pengkompilasi yang bergantung pada konfigurasi ini. Mungkin lingkungan kustom apa pun atau salah satu lingkungan yang telah ditentukan sebelumnya. Untuk informasi selengkapnya, lihat Lingkungan.

  • intelliSenseMode: Menetapkan mode yang digunakan untuk menghitung informasi intellisense. Nilainya mungkin salah satu dari:

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

  • name: menamai konfigurasi. Untuk informasi selengkapnya tentang konfigurasi yang telah ditentukan sebelumnya, lihat Referensi konfigurasi CMake yang telah ditentukan sebelumnya.

  • wslPath: jalur ke peluncur instans Subsistem Windows untuk Linux.

Pengaturan untuk proyek CMake Linux

  • remoteMachineName: Menentukan nama komputer Linux jarak jauh yang menghosting CMake, build, dan debugger. Gunakan Pengelola Sambungan untuk menambahkan komputer Linux baru. Makro yang didukung meliputi ${defaultRemoteMachineName}.
  • remoteCopySourcesOutputVerbosity: Menentukan tingkat verbositas operasi penyalinan sumber ke komputer jarak jauh. Mungkin salah satu dari Normal, Verbose, atau Diagnostic.
  • remoteCopySourcesConcurrentCopies: Menentukan salinan bersamaan yang akan digunakan selama sinkronisasi sumber ke komputer jarak jauh (hanya sftp).
  • remoteCopySourcesMethod: Menentukan metode untuk menyalin file ke komputer jarak jauh. Mungkin rsync atau sftp.
  • remoteCMakeListsRoot: Menentukan direktori pada komputer jarak jauh yang berisi proyek CMake. Makro yang didukung meliputi ${workspaceRoot}, , ${workspaceHash}, ${projectFile}${projectDir}, , ${thisFile}, ${thisFileDir}, ${name}, ${generator}, dan ${env.VARIABLE}.
  • remoteBuildRoot: Menentukan direktori pada komputer jarak jauh tempat CMake menghasilkan skrip build untuk generator yang dipilih. Makro yang didukung meliputi ${workspaceRoot}, , ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}. ${env.VARIABLE}
  • remoteInstallRoot: Menentukan direktori pada komputer jarak jauh tempat CMake menghasilkan target penginstalan untuk generator yang dipilih. Makro yang didukung meliputi ${workspaceRoot}, , ${workspaceHash}${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, dan ${env.VARIABLE}, di mana VARIABLE adalah variabel lingkungan yang telah ditentukan pada tingkat sistem, pengguna, atau sesi.
  • remoteCopySources: Yang boolean menentukan apakah Visual Studio harus menyalin file sumber ke komputer jarak jauh. Defaultnya adalah true. Atur ke false jika Anda mengelola sinkronisasi file sendiri.
  • remoteCopyBuildOutput: A boolean yang menentukan apakah akan menyalin output build dari sistem jarak jauh.
  • remoteCopyAdditionalIncludeDirectories: Tambahan termasuk direktori yang akan disalin dari komputer jarak jauh untuk mendukung IntelliSense. Format sebagai "/path1;/path2...".
  • remoteCopyExcludeDirectories: Sertakan direktori yang TIDAK untuk disalin dari mesin jarak jauh. Format sebagai "/path1;/path2...".
  • remoteCopyUseCompilerDefaults: Menentukan apakah akan menggunakan default kompilator menentukan dan menyertakan jalur untuk IntelliSense. Seharusnya hanya salah jika pengkompilasi yang digunakan tidak mendukung argumen gaya gcc.
  • rsyncCommandArgs: Menentukan sekumpulan opsi baris perintah yang diteruskan ke rsync.
  • remoteCopySourcesExclusionList: Yang array menentukan daftar jalur yang akan dikecualikan saat menyalin file sumber: jalur dapat menjadi nama file/direktori, atau jalur relatif dari akar salinan. Wildcard * dan ? dapat digunakan untuk pencocokan pola glob.
  • cmakeExecutable: Menentukan jalur lengkap ke program CMake yang dapat dieksekusi, termasuk nama file dan ekstensi.
  • remotePreGenerateCommand: Menentukan perintah yang akan dijalankan sebelum menjalankan CMake untuk mengurai CMakeLists.txt file.
  • remotePrebuildCommand: Menentukan perintah untuk dijalankan pada komputer jarak jauh sebelum membangun.
  • remotePostbuildCommand: Menentukan perintah untuk dijalankan pada komputer jarak jauh setelah membangun.
  • variables: Berisi pasangan nama-nilai dari variabel-variabel CMake yang diteruskan sebagai -D name=value ke CMake. Jika instruksi build proyek CMake Anda menentukan penambahan variabel apa pun langsung ke CMakeCache.txt file, kami sarankan Anda menambahkannya di sini sebagai gantinya. Contoh ini menunjukkan cara menentukan pasangan nilai nama untuk menggunakan Alat Build MSVC 14.14.26428:
"variables": [
    {
      "name": "CMAKE_CXX_COMPILER",
      "value": "C:/Program Files (x86)/Microsoft Visual Studio/157/Enterprise/VC/Tools/MSVC/14.14.26428/bin/HostX86/x86/cl.exe",
      "type": "FILEPATH"
    },
    {
      "name": "CMAKE_C_COMPILER",
      "value": "C:/Program Files (x86)/Microsoft Visual Studio/157/Enterprise/VC/Tools/MSVC/14.14.26428/bin/HostX86/x86/cl.exe",
      "type": "FILEPATH"
    }
  ]

Jika Anda tidak menentukan "type", jenisnya "STRING" diasumsikan secara default.

  • remoteCopyOptimizations: Properti Visual Studio 2019 versi 16.5 atau yang lebih baru untuk mengontrol salinan sumber ke target jarak jauh. Pengoptimalan diaktifkan secara default. Termasuk remoteCopyUseOptimizations, rsyncSingleDirectoryCommandArgs, dan remoteCopySourcesMaxSmallChange.

Lingkungan

Lingkungan merangkum variabel lingkungan yang diatur dalam proses yang digunakan Visual Studio untuk memanggil CMake. Untuk proyek MSVC, ia menangkap variabel yang diset dalam command prompt pengembang untuk platform tertentu. Misalnya, msvc_x64_x64 lingkungan sama dengan menjalankan Prompt Perintah untuk Pengembang VS {version} menggunakan argumen -arch=amd64 -host_arch=amd64. Anda dapat menggunakan sintaks env.{<variable_name>} di CMakeSettings.json untuk mereferensikan variabel lingkungan individual, misalnya menyusun jalur menuju folder. Lingkungan yang telah ditentukan sebelumnya berikut disediakan:

  • linux_arm: Menargetkan ARM Linux secara remote.
  • linux_x64: Menargetkan sistem x64 Linux dari jarak jauh.
  • linux_x86: Menargetkan Linux x86 dari jarak jauh.
  • msvc_arm: Targetkan ARM Windows dengan pengkompilasi MSVC.
  • msvc_arm_x64: Targetkan ARM Windows dengan pengkompilasi MSVC 64-bit.
  • msvc_arm64: Targetkan ARM64 Windows dengan pengkompilasi MSVC.
  • msvc_arm64_x64: Target ARM64 Windows dengan kompilator MSVC 64-bit.
  • msvc_arm64ec: Targetkan ARM64EC Windows dengan pengkompilasi MSVC.
  • msvc_arm64ec_x64: Targetkan ARM64EC Windows dengan pengkompilasi MSVC 64-bit.
  • msvc_x64: Target x64 Windows dengan kompiler MSVC.
  • msvc_x64_x64: Menargetkan Windows x64 dengan pengkompilasi 64-bit MSVC.
  • msvc_x86: Target x86 Windows dengan kompiler MSVC.
  • msvc_x86_x64: Targetkan x86 Windows dengan kompiler MSVC 64-bit.

Mengakses variabel lingkungan dari CMakeLists.txt

Dari sebuah file CMakeLists.txt, semua variabel lingkungan dirujuk oleh sintaks $ENV{variable_name}. Untuk melihat variabel yang tersedia untuk lingkungan, buka prompt perintah yang sesuai dan ketik SET. Beberapa informasi dalam variabel lingkungan juga tersedia melalui variabel introspeksi sistem CMake, tetapi Anda mungkin merasa lebih nyaman untuk menggunakan variabel lingkungan. Misalnya, Anda dapat dengan mudah mengambil versi kompilator MSVC atau versi Windows SDK melalui variabel lingkungan.

Variabel lingkungan kustom

Dalam CMakeSettings.json, Anda dapat menentukan variabel lingkungan kustom secara global atau per konfigurasi dalam environments array. Lingkungan kustom adalah cara mudah untuk mengelompokkan sekumpulan properti. Anda dapat menggunakannya sebagai pengganti lingkungan yang telah ditentukan sebelumnya, atau untuk memperluas atau memodifikasi lingkungan yang telah ditentukan sebelumnya. Setiap item dalam environments array terdiri dari:

  • namespace: Menamai lingkungan sehingga variabelnya dapat dirujuk dari konfigurasi dalam bentuk namespace.variable. Objek lingkungan default disebut env dan diisi dengan variabel lingkungan sistem tertentu termasuk %USERPROFILE%.
  • environment: Secara unik mengidentifikasi grup variabel ini. Memungkinkan grup diambil alih nanti dalam entri inheritEnvironments.
  • groupPriority: Bilangan bulat yang menentukan prioritas variabel ini saat mengevaluasinya. Item dengan angka lebih tinggi dievaluasi terlebih dahulu.
  • inheritEnvironments: Array nilai yang menentukan sekumpulan lingkungan yang diwariskan oleh grup ini. Fitur ini memungkinkan Anda mewarisi lingkungan default dan membuat variabel lingkungan kustom untuk diteruskan ke CMake saat berjalan.

Visual Studio 2019 versi 16.4 dan yang lebih baru: Target debug secara otomatis diluncurkan dengan lingkungan yang Anda tentukan di CMakeSettings.json. Anda dapat mengambil alih atau menambahkan variabel lingkungan berdasarkan per target atau per tugas di launch.vs.json dan tasks.vs.json.

Contoh berikut mendefinisikan satu variabel global, BuildDir, yang diwarisi dalam konfigurasi x86-Debug dan x64-Debug. Setiap konfigurasi menggunakan variabel untuk menentukan nilai properti untuk konfigurasi tersebut buildRoot . Perhatikan juga bagaimana setiap konfigurasi menggunakan properti untuk menentukan variabel yang hanya berlaku untuk konfigurasi tersebut inheritEnvironments .

{
  // The "environments" property is an array of key-value pairs of the form
  // { "EnvVar1": "Value1", "EnvVar2": "Value2" }
  "environments": [
    {
      "BuildDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build",
    }
  ],

  "configurations": [
    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      // Inherit the defaults for using the MSVC x86 compiler.
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.BuildDir}\\${name}"    },
    {
      "name": "x64-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      // Inherit the defaults for using the MSVC x64 compiler.
      "inheritEnvironments": [ "msvc_x64" ],
      "buildRoot": "${env.BuildDir}\\${name}"
    }
  ]
}

Dalam contoh berikutnya, konfigurasi x86-Debug menentukan nilainya sendiri untuk properti BuildDir . Nilai ini menggantikan nilai yang ditetapkan oleh properti BuildDir global sehingga BuildRoot menjadi D:\custom-builddir\x86-Debug.

{
  "environments": [
    {
      "BuildDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}",
    }
  ],

  "configurations": [
    {
      "name": "x86-Debug",

      // The syntax for this property is the same as the global one above.
      "environments": [
        {
          // Replace the global property entirely.
          "BuildDir": "D:\\custom-builddir"
          // This environment does not specify a namespace, hence by default "env" is assumed.
          // "namespace" : "name" would require that this variable be referenced with "${name.BuildDir}".
        }
      ],

      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      // Evaluates to "D:\custom-builddir\x86-Debug"
      "buildRoot": "${env.BuildDir}\\${name}"
    },
    {
      "name": "x64-Debug",

      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x64" ],
      // Since this configuration doesn't modify BuildDir, it inherits
      // from the one defined globally.
      "buildRoot": "${env.BuildDir}\\${name}"
    }
  ]
}

Makro

Makro berikut dapat digunakan dalam CMakeSettings.json:

  • ${workspaceRoot} – jalur lengkap folder ruang kerja
  • ${workspaceHash} – hash lokasi ruang kerja; berguna untuk membuat pengidentifikasi unik bagi ruang kerja saat ini (contohnya, untuk digunakan dalam jalur folder)
  • ${projectFile}– jalur lengkap file akar CMakeLists.txt
  • ${projectDir}– jalur lengkap folder yang berisi file akar CMakeLists.txt
  • ${projectDirName}– nama folder yang berisi file akar CMakeLists.txt
  • ${thisFile} – jalur lengkap dari file CMakeSettings.json
  • ${name} – nama konfigurasi
  • ${generator} – nama generator CMake yang digunakan dalam konfigurasi ini

Semua referensi ke makro dan variabel lingkungan di CMakeSettings.json diperluas sebelum diteruskan ke baris perintah CMake.

Argumen baris perintah Ninja

Jika target tidak ditentukan, Ninja membangun target 'default'.

C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise>ninja -?
ninja: invalid option -- `-?'
usage: ninja [options] [targets...]
Opsi Deskripsi
--version Cetak versi Ninja ("1.7.1")
-C DIR Ubah ke DIR sebelum melakukan hal lain
-f FILE Tentukan file build masukan (default=build.ninja)
-j N Menjalankan N pekerjaan secara paralel (default=14, berasal dari CPU yang tersedia)
-k N Lanjutkan sampai N pekerjaan gagal (default=1)
-l N Jangan memulai pekerjaan baru jika rata-rata beban lebih besar dari N
-n Eksekusi kering (jangan jalankan perintah tetapi bertindak seperti berhasil)
-v Perlihatkan semua baris perintah saat membangun
-d MODE Aktifkan penelusuran kesalahan (gunakan -d list untuk mencantumkan mode)
-t TOOL Jalankan subtool (gunakan -t list untuk mencantumkan subtool). Mengakhiri opsi tingkat atas mana pun; parameter selanjutnya diteruskan ke alat
-w FLAG Menyesuaikan peringatan (gunakan -w list untuk mencantumkan peringatan)
  • Last updated on