CMakeSettings.json riferimento allo schema

  • Articolo

I progetti CMake sono supportati in Visual Studio 2017 e versioni successive.

Il CMakeSettings.json file contiene informazioni usate da Visual Studio per IntelliSense e per costruire gli argomenti della riga di comando passati a CMake per un ambiente di configurazione e compilatore specificato. Una configurazione specifica le proprietà che si applicano a una piattaforma specifica e a un tipo di compilazione, ad esempio x86-Debug o Linux-Release. Ogni configurazione specifica un ambiente, che incapsula informazioni sul set di strumenti del compilatore, ad esempio MSVC, GCC o Clang. CMake usa gli argomenti della riga di comando per rigenerare il file radice CMakeCache.txt e altri file di progetto per il progetto. È possibile eseguire l'override dei valori nei CMakeLists.txt file.

È possibile aggiungere o rimuovere configurazioni nell'IDE e modificarle direttamente nel file JSON o usare l'editor di Impostazioni CMake (Visual Studio 2019 e versioni successive). È possibile passare facilmente tra le configurazioni nell'IDE per generare i vari file di progetto. Per altre informazioni, vedere Personalizzare le impostazioni di compilazione di CMake in Visual Studio.

Configurazioni

La configurations matrice contiene tutte le configurazioni per un progetto CMake. Per altre informazioni sulle configurazioni predefinite, vedere Informazioni di riferimento sulla configurazione predefinita di CMake. È possibile aggiungere un numero qualsiasi di configurazioni predefinite o personalizzate al file.

configuration ha le proprietà seguenti:

  • addressSanitizerEnabled: se true, compila il programma usando AddressSanitizer. In Linux compilare con -fno-omit-frame-pointer il livello -Os di ottimizzazione del compilatore e -Oo per ottenere risultati ottimali.

  • addressSanitizerRuntimeFlags: flag di runtime passati a AddressSanitizer nella ASAN_OPTIONS variabile di ambiente. Formato: flag1=value:flag2=value2.

  • buildCommandArgs: specifica le opzioni di compilazione native passate a CMake dopo --build --. Ad esempio, passando -v quando si usa il generatore Ninja forza Ninja a restituire le righe di comando. Per altre informazioni sui comandi Ninja, vedere Argomenti della riga di comando Ninja.

  • buildRoot: specifica la directory in cui CMake genera script di compilazione per il generatore scelto. Mappe per -DCMAKE_BINARY_DIR cambiare e specifica dove CMakeCache.txt viene creato. Se la cartella non esiste, viene creata. Le macro supportate includono ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.

  • cacheGenerationCommand: specifica uno strumento da riga di comando e argomenti, ad esempio gencache.bat debug per generare la cache. Il comando viene eseguito dalla shell nell'ambiente specificato per la configurazione quando l'utente richiede esplicitamente la rigenerazione o viene modificato un CMakeLists.txt file o CMakeSettings.json .

  • cacheRoot: specifica il percorso di una cache CMake. Questa directory deve contenere un file esistente CMakeCache.txt .

  • clangTidyChecks: elenco delimitato da virgole di avvisi passati a clang-tidy; I caratteri jolly sono consentiti e un prefisso '-' rimuove i controlli.

  • cmakeCommandArgs: specifica le opzioni della riga di comando aggiuntive da passare a CMake quando viene richiamato per generare i file di progetto.

  • cmakeToolchain: specifica il file toolchain. Viene passato a CMake usando -DCMAKE_TOOLCHAIN_FILE.

  • codeAnalysisRuleset: specifica il set di regole da usare durante l'esecuzione dell'analisi del codice. È possibile usare un percorso completo o il nome file di un file del set di regole installato da Visual Studio.

  • configurationType: specifica la configurazione del tipo di compilazione per il generatore selezionato. Può essere uno dei seguenti:

    • Debug
    • Release
    • MinSizeRel
    • RelWithDebInfo

  • ctestCommandArgs: specifica le opzioni della riga di comando aggiuntive da passare a CTest durante l'esecuzione dei test.

  • description: descrizione di questa configurazione visualizzata nei menu.

  • enableClangTidyCodeAnalysis: usare Clang-Tidy per l'analisi del codice.

  • enableMicrosoftCodeAnalysis: usare gli strumenti di analisi del codice Microsoft per l'analisi del codice.

  • generator: specifica il generatore CMake da usare per questa configurazione. Può essere uno dei seguenti:

    Solo Visual Studio 2019:

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

    Visual Studio 2017 e versioni successive:

    • 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

Poiché Ninja è progettato per velocità di compilazione veloci anziché flessibilità e funzione, viene impostato come predefinito. Tuttavia, alcuni progetti CMake potrebbero non essere in grado di eseguire una compilazione corretta usando Ninja. Se si verifica un errore di compilazione, è possibile indicare a CMake di generare progetti di Visual Studio.

Per specificare un generatore di Visual Studio in Visual Studio 2017, aprire l'editor delle impostazioni dal menu principale scegliendo CMake | Modificare il Impostazioni CMake. Eliminare "Ninja" e immettere "V". Questa modifica attiva IntelliSense, che consente di scegliere il generatore desiderato.

Per specificare un generatore di Visual Studio in Visual Studio 2019, fare clic con il pulsante destro del mouse sul file in Esplora soluzioni e scegliere CMake Impostazioni per il progetto Show Advanced Impostazioni CMake Generator.To specify a Visual Studio Generator in Visual Studio 2019, right-click on the CMakeLists.txt file in Esplora soluzioni and choose CMake Impostazioni for project>Show Advanced Impostazioni> CMake Generator.

Per impostazione predefinita, quando la configurazione attiva specifica un generatore di Visual Studio, richiama MSBuild con -m -v:minimal argomenti. Per personalizzare la compilazione, usare la buildCommandArgs proprietà all'interno del CMakeSettings.json file. Qui è possibile specificare gli argomenti della riga di comando di MSBuild da passare al sistema di compilazione:

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

  • installRoot: specifica la directory in cui CMake genera le destinazioni di installazione per il generatore scelto. Le macro supportate includono ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.

  • inheritEnvironments: specifica uno o più ambienti del compilatore da cui dipende questa configurazione. Può essere qualsiasi ambiente personalizzato oppure uno degli ambienti predefiniti. Per altre informazioni, vedere Ambienti.

  • intelliSenseMode: specifica la modalità usata per il calcolo delle informazioni intelliSense". Il valore può essere uno dei seguenti:

    • 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: assegna un nome alla configurazione. Per altre informazioni sulle configurazioni predefinite, vedere Informazioni di riferimento sulla configurazione predefinita di CMake.

  • wslPath: percorso dell'utilità di avvio di un'istanza di sottosistema Windows per Linux.

Impostazioni per i progetti CMake Linux

  • remoteMachineName: specifica il nome del computer Linux remoto che ospita CMake, compila e il debugger. Usare Gestione connessioni per aggiungere nuovi computer Linux. Le macro supportate includono ${defaultRemoteMachineName}.
  • remoteCopySourcesOutputVerbosity: specifica il livello di dettaglio dell'operazione di copia dell'origine nel computer remoto. Può essere uno di Normal, Verboseo Diagnostic.
  • remoteCopySourcesConcurrentCopies: specifica le copie simultanee da usare durante la sincronizzazione delle origini nel computer remoto (solo sftp).
  • remoteCopySourcesMethod: specifica il metodo per copiare i file nel computer remoto. Può essere rsync o sftp.
  • remoteCMakeListsRoot: specifica la directory nel computer remoto che contiene il progetto CMake. Le macro supportate includono ${workspaceRoot}, ${workspaceHash}, ${projectDir}${projectFile}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, e ${env.VARIABLE}.
  • remoteBuildRoot: specifica la directory nel computer remoto in cui CMake genera script di compilazione per il generatore scelto. Le macro supportate includono ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.
  • remoteInstallRoot: specifica la directory nel computer remoto in cui CMake genera le destinazioni di installazione per il generatore scelto. Le macro supportate includono ${workspaceRoot}, ${workspaceHash}, ${projectDir}${name}${projectFile}${thisFileDir}${generator}${thisFile}e ${env.VARIABLE}, dove VARIABLE è una variabile di ambiente definita a livello di sistema, utente o sessione.
  • remoteCopySourcesboolean: oggetto che specifica se Visual Studio deve copiare i file di origine nel computer remoto. Il valore predefinito è true. Impostare su false se la sincronizzazione dei file viene gestita in modo autonomo.
  • remoteCopyBuildOutputboolean: oggetto che specifica se copiare gli output di compilazione dal sistema remoto.
  • remoteCopyAdditionalIncludeDirectories: include anche le directory da copiare dal computer remoto per supportare IntelliSense. Formattare "/path1;/path2...".
  • remoteCopyExcludeDirectories: includere directory NON da copiare dal computer remoto. Formattare "/path1;/path2...".
  • remoteCopyUseCompilerDefaults: specifica se usare l'impostazione predefinita del compilatore definisce e include i percorsi per IntelliSense. Deve essere false solo se i compilatori in uso non supportano argomenti di tipo gcc.
  • rsyncCommandArgs: specifica un set di opzioni della riga di comando passate a rsync.
  • remoteCopySourcesExclusionListarray: che specifica un elenco di percorsi da escludere durante la copia dei file di origine: un percorso può essere il nome di un file/directory o un percorso relativo dalla radice della copia. I caratteri jolly * e ? possono essere usati per la corrispondenza dei criteri GLOB.
  • cmakeExecutable: specifica il percorso completo dell'eseguibile del programma CMake, incluso il nome e l'estensione del file.
  • remotePreGenerateCommand: specifica il comando da eseguire prima di eseguire CMake per analizzare il CMakeLists.txt file.
  • remotePrebuildCommand: specifica il comando da eseguire nel computer remoto prima della compilazione.
  • remotePostbuildCommand: specifica il comando da eseguire nel computer remoto dopo la compilazione.
  • variables: contiene una coppia nome-valore di variabili CMake che vengono passate come -D name=value a CMake. Se le istruzioni di compilazione del progetto CMake specificano l'aggiunta di qualsiasi variabile direttamente al CMakeCache.txt file, è consigliabile aggiungerle qui. Questo esempio illustra come specificare le coppie nome-valore per usare il set di strumenti 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"
    }
  ]

Se non si definisce "type", il "STRING" tipo viene assunto per impostazione predefinita.

  • remoteCopyOptimizations: Proprietà di Visual Studio 2019 versione 16.5 o successive per controllare la copia del codice sorgente nella destinazione remota. Le ottimizzazioni sono abilitate per impostazione predefinita. Include remoteCopyUseOptimizations, rsyncSingleDirectoryCommandArgse remoteCopySourcesMaxSmallChange.

Ambienti

Un ambiente incapsula le variabili di ambiente impostate nel processo usato da Visual Studio per richiamare CMake. Per i progetti MSVC, acquisisce le variabili impostate in un prompt dei comandi per sviluppatori per una piattaforma specifica. Ad esempio, l'ambiente è uguale all'esecuzione msvc_x64_x64 del prompt dei comandi per gli sviluppatori per VS {version} con gli argomenti -arch=amd64 -host_arch=amd64. È possibile usare la env.{<variable_name>} sintassi in CMakeSettings.json per fare riferimento alle singole variabili di ambiente, ad esempio per costruire percorsi alle cartelle. Vengono forniti gli ambienti predefiniti seguenti:

  • linux_arm: specificare come destinazione ARM Linux in modalità remota.
  • linux_x64: destinazione x64 Linux in modalità remota.
  • linux_x86: destinazione x86 Linux in modalità remota.
  • msvc_arm: specificare come destinazione Windows ARM con il compilatore MSVC.
  • msvc_arm_x64: usare Windows ARM di destinazione con il compilatore MSVC a 64 bit.
  • msvc_arm64: destinazione ARM64 Windows con il compilatore MSVC.
  • msvc_arm64_x64: destinazione ARM64 Windows con il compilatore MSVC a 64 bit.
  • msvc_arm64ec: destinazione ARM64EC Windows con il compilatore MSVC.
  • msvc_arm64ec_x64: destinazione ARM64EC Windows con il compilatore MSVC a 64 bit.
  • msvc_x64: destinazione x64 Windows con il compilatore MSVC.
  • msvc_x64_x64: destinazione x64 Windows con il compilatore MSVC a 64 bit.
  • msvc_x86: destinazione x86 Windows con il compilatore MSVC.
  • msvc_x86_x64: destinazione x86 Windows con il compilatore MSVC a 64 bit.

Accesso alle variabili di ambiente da CMakeLists.txt

Da un CMakeLists.txt file, tutte le variabili di ambiente fanno riferimento alla sintassi $ENV{variable_name}. Per visualizzare le variabili disponibili per un ambiente, aprire il prompt dei comandi corrispondente e digitare SET. Alcune informazioni nelle variabili di ambiente sono disponibili anche tramite le variabili di introspezione del sistema CMake, ma potrebbe risultare più conveniente usare la variabile di ambiente. Ad esempio, è possibile recuperare facilmente la versione del compilatore MSVC o windows SDK tramite le variabili di ambiente.

Variabili di ambiente personalizzate

In CMakeSettings.jsonè possibile definire variabili di ambiente personalizzate a livello globale o per configurazione nella environments matrice. Un ambiente personalizzato è un modo pratico per raggruppare un set di proprietà. È possibile usarlo al posto di un ambiente predefinito oppure per estendere o modificare un ambiente predefinito. Ogni elemento nella matrice environments è costituito da:

  • namespace: assegna un nome all'ambiente in modo che le relative variabili possano essere referenziate da una configurazione nel formato namespace.variable. L'oggetto ambiente predefinito è denominato env ed è popolato con determinate variabili di ambiente di sistema tra cui %USERPROFILE%.
  • environment: identifica in modo univoco questo gruppo di variabili. Consente al gruppo di essere ereditato successivamente in una voce inheritEnvironments.
  • groupPriority: numero intero che specifica la priorità di queste variabili durante la valutazione. Gli elementi con il numero più elevato vengono valutati per primi.
  • inheritEnvironments: matrice di valori che specificano il set di ambienti ereditati da questo gruppo. Questa funzionalità consente di ereditare gli ambienti predefiniti e creare variabili di ambiente personalizzate da passare a CMake durante l'esecuzione.

Visual Studio 2019 versione 16.4 e successive: le destinazioni di debug vengono avviate automaticamente con l'ambiente specificato in CMakeSettings.json. È possibile eseguire l'override o aggiungere variabili di ambiente per ogni destinazione o per ogni attività in launch.vs.json e tasks.vs.json.

L'esempio seguente definisce una variabile globale, BuildDir, ereditata sia nelle configurazioni x86-Debug che x64-Debug. Ogni configurazione usa la variabile per specificare il valore per la buildRoot proprietà per tale configurazione. Si noti anche come ogni configurazione usi la inheritEnvironments proprietà per specificare una variabile che si applica solo a tale configurazione.

{
  // 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}"
    }
  ]
}

Nell'esempio seguente la configurazione x86-Debug definisce il proprio valore per la proprietà BuildDir. Questo valore sostituisce il valore impostato dalla proprietà BuildDir globale in modo che BuildRoot restituisca 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}"
    }
  ]
}

Macro

Le macro seguenti possono essere usate in CMakeSettings.json:

  • ${workspaceRoot} : percorso completo della cartella dell'area di lavoro
  • ${workspaceHash} – hash della posizione dell'area di lavoro; utile per creare un identificatore univoco per l'area di lavoro corrente (ad esempio, da usare nei percorsi delle cartelle)
  • ${projectFile}: percorso completo del file radice CMakeLists.txt
  • ${projectDir}: percorso completo della cartella contenente il file radice CMakeLists.txt
  • ${projectDirName}: nome della cartella contenente il file radice CMakeLists.txt
  • ${thisFile} – percorso completo del CMakeSettings.json file
  • ${name} – nome della configurazione
  • ${generator} – nome del generatore CMake usato in questa configurazione

Tutti i riferimenti alle macro e alle variabili di ambiente in CMakeSettings.json vengono espansi prima di essere passati alla riga di comando di CMake.

Argomenti della riga di comando Ninja

Se le destinazioni non sono specificate, Ninja compila la destinazione "predefinita".

C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise>ninja -?
ninja: invalid option -- `-?'
usage: ninja [options] [targets...]
Opzione Descrizione
--version Stampare la versione ninja ("1.7.1")
-C DIR Passare a DIR prima di eseguire qualsiasi altra operazione
-f FILE Specificare il file di compilazione di input (default=build.ninja)
-j N Eseguire processi N in parallelo (default=14, derivato dalle CPU disponibili)
-k N Continuare fino a quando N i processi non riescono (valore predefinito=1)
-l N Non avviare nuovi processi se la media del carico è maggiore di N
-n Esecuzione asciutta (non eseguire comandi ma agire come se avessero avuto esito positivo)
-v Mostra tutte le righe di comando durante la compilazione
-d MODE Abilitare il debug (usare -d list per elencare le modalità)
-t TOOL Eseguire uno strumento secondario (usare -t list per elencare gli strumenti secondari). Termina tutte le opzioni di primo livello; altri flag vengono passati allo strumento
-w FLAG Modificare gli avvisi (usare -w list per elencare gli avvisi)