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 meregenerasi file akar CMakeCache.txt dan file proyek lainnya untuk proyek. Nilai dapat ditimpa dalam 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.

memiliki configuration properti ini:

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

• addressSanitizerRuntimeFlags: Bendera runtime yang diteruskan ke AddressSanitizer dalam ASAN_OPTIONS variabel lingkungan. Format: flag1=value:flag2=value2.

• buildCommandArgs: Menentukan sakelar build asli 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, folder 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 CMakeLists.txt file 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-rapi; kartubebas diizinkan dan awalan '-' menghapus pemeriksaan.

• 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 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>Tingkat Lanjut CMake Generator.

Secara default, ketika konfigurasi aktif menentukan generator Visual Studio, ia memanggil MSBuild dengan -m -v:minimal argumen. Untuk menyesuaikan build, gunakan properti di buildCommandArgs CMakeSettings.json dalam file. 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: Menentukan 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 TIDAK untuk disalin dari komputer 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 untuk 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. Kartubebas * 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 nilai nama variabel CMake yang diteruskan ke -D name=value 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 nama-nilai untuk menggunakan toolset 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 diatur dalam prompt perintah pengembang untuk platform tertentu. Misalnya, msvc_x64_x64 lingkungan sama dengan menjalankan Prompt Perintah Pengembang untuk VS {version} dengan argumen -arch=amd64 -host_arch=amd64 . Anda dapat menggunakan sintaks untuk env.{<variable_name>} CMakeSettings.json mereferensikan variabel lingkungan individual, misalnya untuk membuat jalur ke folder. Lingkungan yang telah ditentukan sebelumnya berikut disediakan:

• linux_arm: Target ARM Linux dari jarak jauh.
• linux_x64: Target x64 Linux dari jarak jauh.
• linux_x86: Target x86 Linux 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: TargetKAN ARM64 Windows dengan pengkompilasi 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 pengkompilasi MSVC.
• msvc_x64_x64: Target x64 Windows dengan pengkompilasi MSVC 64-bit.
• msvc_x86: Target x86 Windows dengan pengkompilasi MSVC.
• msvc_x86_x64: Target x86 Windows dengan pengkompilasi MSVC 64-bit.

Mengakses variabel lingkungan dari CMakeLists.txt

CMakeLists.txt Dari file, 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 diwariskan nanti dalam inheritEnvironments entri.
• groupPriority: Bilangan bulat yang menentukan prioritas variabel ini saat mengevaluasinya. Item angka yang 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 mengambil alih nilai yang ditetapkan oleh properti BuildDir global sehingga BuildRoot mengevaluasi ke 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 untuk ruang kerja saat ini (misalnya, untuk digunakan di 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 CMakeSettings.json lengkap file
• ${name} – nama konfigurasi
• ${generator} – nama generator CMake yang digunakan dalam konfigurasi ini

Semua referensi ke makro dan variabel lingkungan di diperluas sebelum diteruskan CMakeSettings.json 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...]