CMakeSettings.json referência de esquema

Os projetos CMake são suportados no Visual Studio 2017 e posterior.

O CMakeSettings.json arquivo contém informações que o Visual Studio usa para o IntelliSense e para construir os argumentos de linha de comando que ele passa para o CMake para um ambiente de configuração e compilador especificado. Uma configuração especifica propriedades que se aplicam a uma plataforma específica e a um tipo de compilação, por exemplo, x86-Debug ou Linux-Release. Cada configuração especifica um ambiente, que encapsula informações sobre o conjunto de ferramentas do compilador, por exemplo, MSVC, GCC ou Clang. CMake usa os argumentos de linha de comando para regenerar o arquivo raiz CMakeCache.txt e outros arquivos de projeto para o projeto. Os valores podem ser substituídos nos CMakeLists.txt arquivos.

Você pode adicionar ou remover configurações no IDE e, em seguida, editá-las diretamente no arquivo JSON ou usar o editor de configurações do CMake (Visual Studio 2019 e posterior). Você pode alternar entre as configurações facilmente no IDE para gerar os vários arquivos de projeto. Para obter mais informações, consulte Personalizar configurações de compilação do CMake no Visual Studio.

Configurações

A configurations matriz contém todas as configurações para um projeto CMake. Para obter mais informações sobre as configurações predefinidas, consulte Referência de configuração predefinida do CMake. Você pode adicionar qualquer número de configurações predefinidas ou personalizadas ao arquivo.

A configuration tem estas propriedades:

• addressSanitizerEnabled: If true, compila o programa usando AddressSanitizer. Em Linux, compile com -fno-omit-frame-pointer e o nível de otimização do compilador -Os ou -Oo para obter os melhores resultados.

• addressSanitizerRuntimeFlags: Os flags de execução passados para AddressSanitizer dentro da ASAN_OPTIONS variável de ambiente. Formato: flag1=value:flag2=value2.

• buildCommandArgs: Especifica as opções de compilação nativas passadas para o CMake após --build --. Por exemplo, passar -v ao usar o gerador Ninja força o Ninja a emitir linhas de comando. Para obter mais informações sobre comandos Ninja, consulte Argumentos de linha de comando Ninja.

• buildRoot: Especifica o diretório no qual o CMake gera scripts de construção para o gerador escolhido. Mapeia para -DCMAKE_BINARY_DIR alternar e especifica onde CMakeCache.txt é criado. Se a pasta não existir, ela será criada. As macros suportadas incluem ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, . ${env.VARIABLE}

• cacheGenerationCommand: Especifica uma ferramenta de linha de comando e argumentos, por exemplo gencache.bat debug , para gerar o cache. O comando é executado no shell a partir do ambiente especificado para a configuração quando o usuário solicita explicitamente a regeneração ou um arquivo CMakeLists.txt ou CMakeSettings.json é modificado.

• cacheRoot: Especifica o caminho para um cache CMake. Este diretório deve conter um arquivo existente CMakeCache.txt .

• clangTidyChecks: lista separada por vírgulas de avisos que é passada para clang-tidy; curingas são permitidos e um prefixo '-' remove verificações.

• cmakeCommandArgs: Especifica quaisquer opções de linha de comando extras a serem passadas para o CMake quando invocadas para gerar os arquivos de projeto.

• cmakeToolchain: Especifica o ficheiro da cadeia de ferramentas. É passado para o CMake usando -DCMAKE_TOOLCHAIN_FILE.

• codeAnalysisRuleset: Especifica o conjunto de regras a ser usado ao executar a análise de código. Você pode usar um caminho completo ou o nome do arquivo de um conjunto de regras instalado pelo Visual Studio.

• configurationType: Especifica a configuração do tipo de compilação para o gerador selecionado. Pode ser um dos seguintes:

  • Debug
  • Release
  • MinSizeRel
  • RelWithDebInfo

• ctestCommandArgs: Especifica quaisquer opções de linha de comando extra para passar para CTest ao executar os testes.

• description: A descrição desta configuração que aparece nos menus.

• enableClangTidyCodeAnalysis: Use Clang-Tidy para análise de código.

• enableMicrosoftCodeAnalysis: Use ferramentas de análise de código da Microsoft para análise de código.

• generator: Especifica o gerador CMake a ser usado para esta configuração. Pode ser um dos seguintes:

  Somente Visual Studio 2019:

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

  Visual Studio 2017 e posterior:

  • 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

Como o Ninja foi projetado para velocidades de construção rápidas em vez de flexibilidade e função, ele é definido como padrão. No entanto, alguns projetos CMake podem ser incapazes de construir corretamente usando Ninja. Se ocorrer uma falha de compilação, você pode instruir o CMake para gerar projetos do Visual Studio.

Para especificar um gerador do Visual Studio no Visual Studio 2017, abra o editor de configurações no menu principal escolhendo CMake | Altere as configurações do CMake. Exclua "Ninja" e digite "V". Esta alteração ativa o IntelliSense, que lhe permite escolher o gerador que pretende.

Para especificar um gerador do Visual Studio no Visual Studio 2019, clique com o botão direito do mouse no arquivo no CMakeLists.txt e escolha Configurações do CMake para o projeto > MostrarGerador CMake de Configurações Avançadas>.

Por padrão, quando a configuração ativa especifica um gerador do Visual Studio, ele invoca o MSBuild com -m -v:minimal argumentos. Para personalizar a compilação, use a buildCommandArgs propriedade dentro do CMakeSettings.json arquivo. Aqui, você pode especificar argumentos de linha de comando do MSBuild para passar para o sistema de compilação:

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

• installRoot: Especifica o diretório no qual o CMake gera destinos de instalação para o gerador escolhido. As macros suportadas incluem ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, . ${env.VARIABLE}

• inheritEnvironments: Especifica um ou mais ambientes de compilador dos quais essa configuração depende. Pode ser qualquer ambiente personalizado ou um dos ambientes predefinidos. Para obter mais informações, consulte Ambientes.

• intelliSenseMode: Especifica o modo usado para obter informações IntelliSense". O valor pode ser um dos seguintes:

  • 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: nomeia a configuração. Para obter mais informações sobre as configurações predefinidas, consulte Referência de configuração predefinida do CMake.

• wslPath: o caminho para o lançador de uma instância do Subsistema Windows para Linux.

Configurações para projetos CMake Linux

• remoteMachineName: Especifica o nome da máquina Linux remota que hospeda o CMake, compila e o depurador. Use o Connection Manager para adicionar novas máquinas Linux. As macros suportadas incluem ${defaultRemoteMachineName}.
• remoteCopySourcesOutputVerbosity: Especifica o nível de verbosidade da operação de cópia do código-fonte para a máquina remota. Pode ser um de Normal, Verboseou Diagnostic.
• remoteCopySourcesConcurrentCopies: Especifica as cópias simultâneas a serem usadas durante a sincronização dos códigos-fonte com a máquina remota (somente sftp).
• remoteCopySourcesMethod: Especifica o método para copiar arquivos para a máquina remota. Pode ser rsync ou sftp.
• remoteCMakeListsRoot: Especifica o diretório na máquina remota que contém o projeto CMake. As macros suportadas incluem ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}e ${env.VARIABLE}.
• remoteBuildRoot: Especifica o diretório na máquina remota na qual o CMake gera scripts de construção para o gerador escolhido. As macros suportadas incluem ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, . ${env.VARIABLE}
• remoteInstallRoot: Especifica o diretório na máquina remota na qual o CMake gera destinos de instalação para o gerador escolhido. As macros suportadas incluem ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}${generator}, , e ${env.VARIABLE}, onde VARIABLE é uma variável de ambiente que foi definida no nível do sistema, usuário ou sessão.
• remoteCopySources: A boolean que especifica se o Visual Studio deve copiar arquivos de origem para a máquina remota. O padrão é verdadeiro. Defina como _false_ se gerir pessoalmente a sincronização de arquivos.
• remoteCopyBuildOutput: A boolean que especifica se as saídas de compilação do sistema remoto devem ser copiadas.
• remoteCopyAdditionalIncludeDirectories: Adicionais incluem diretórios a serem copiados da máquina remota para suportar o IntelliSense. Formate como "/path1;/path2...".
• remoteCopyExcludeDirectories: Incluir diretórios que NÃO devem ser copiados da máquina remota. Formate como "/path1;/path2...".
• remoteCopyUseCompilerDefaults: Especifica se deve usar os defines padrão do compilador e incluir caminhos padrão para o IntelliSense. Só deve ser false se os compiladores em uso não suportarem argumentos no estilo gcc.
• rsyncCommandArgs: Especifica um conjunto de opções de linha de comando passadas para rsync.
• remoteCopySourcesExclusionList: Um array que especifica uma lista de caminhos a serem excluídos ao copiar arquivos de origem: um caminho pode ser o nome de um arquivo/diretório ou um caminho relativo da raiz da cópia. Curingas * e ? podem ser usados para correspondência de padrões glob.
• cmakeExecutable: Especifica o caminho completo para o executável do programa CMake, incluindo o nome do arquivo e a extensão.
• remotePreGenerateCommand: Especifica o comando a ser executado antes de executar o CMake para analisar o CMakeLists.txt arquivo.
• remotePrebuildCommand: Especifica o comando a ser executado na máquina remota antes da compilação.
• remotePostbuildCommand: Especifica o comando a ser executado na máquina remota após a compilação.
• variables: Contém um par nome-valor de variáveis CMake que são passadas como -D name=value para CMake. Se as instruções de construção do seu projeto CMake especificarem a adição de quaisquer variáveis diretamente ao CMakeCache.txt arquivo, recomendamos que você as adicione aqui. Este exemplo mostra como especificar os pares nome-valor para usar as Ferramentas de Compilação 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 não definir o "type", o tipo "STRING" será assumido por padrão.

• remoteCopyOptimizations: Visual Studio 2019 versão 16.5 ou posterior propriedades para controlar a cópia de origem para um destino remoto. As otimizações são ativadas por padrão. Inclui remoteCopyUseOptimizations, rsyncSingleDirectoryCommandArgs, e remoteCopySourcesMaxSmallChange.

Ambientes

Um ambiente encapsula as variáveis de ambiente definidas no processo que o Visual Studio usa para invocar o CMake. Para projetos MSVC, ele captura as variáveis definidas em um prompt de comando do desenvolvedor para uma plataforma específica. Por exemplo, o msvc_x64_x64 ambiente é o mesmo que executar o Prompt de Comando do Desenvolvedor para VS {version} com os argumentos -arch=amd64 -host_arch=amd64. Você pode usar a env.{<variable_name>} sintaxe em CMakeSettings.json para fazer referência às variáveis de ambiente individuais, por exemplo, para construir caminhos para pastas. Os seguintes ambientes predefinidos são fornecidos:

• linux_arm: Configure ARM Linux remotamente.
• linux_x64: Target x64 Linux remotamente.
• linux_x86: Target x86 Linux remotamente.
• msvc_arm: Target ARM Windows com o compilador MSVC.
• msvc_arm_x64: Windows ARM de destino com o compilador MSVC de 64 bits.
• msvc_arm64: Target ARM64 Windows com o compilador MSVC.
• msvc_arm64_x64: Direcionar o Windows ARM64 com o compilador MSVC de 64 bits.
• msvc_arm64ec: Destino ARM64EC Windows com o compilador MSVC.
• msvc_arm64ec_x64: Alveje o Windows ARM64EC com o compilador MSVC de 64 bits.
• msvc_x64: Alveje x64 Windows com o compilador MSVC.
• msvc_x64_x64: Windows x64 de destino com o compilador MSVC de 64 bits.
• msvc_x86: Dirigir para Windows x86 com o compilador MSVC.
• msvc_x86_x64: Alveje o Windows x86 com o compilador MSVC de 64 bits.

Acesso a variáveis de ambiente a partir de CMakeLists.txt

A partir de um CMakeLists.txt arquivo, todas as variáveis de ambiente são referenciadas pela sintaxe $ENV{variable_name}. Para ver as variáveis disponíveis para um ambiente, abra o prompt de comando correspondente e digite SET. Algumas das informações em variáveis de ambiente também estão disponíveis através de variáveis de introspeção do sistema CMake, mas você pode achar mais conveniente usar a variável de ambiente. Por exemplo, você pode recuperar facilmente a versão do compilador MSVC ou a versão do SDK do Windows por meio das variáveis de ambiente.

Variáveis de ambiente personalizadas

No CMakeSettings.json, você pode definir variáveis de ambiente personalizadas globalmente ou por configuração na environments matriz. Um ambiente personalizado é uma maneira conveniente de agrupar um conjunto de propriedades. Você pode usá-lo no lugar de um ambiente predefinido ou para estender ou modificar um ambiente predefinido. Cada item na environments matriz consiste em:

• namespace: Nomeia o ambiente para que suas variáveis possam ser referenciadas a partir de uma configuração no formulário namespace.variable. O objeto de ambiente padrão é chamado env e é preenchido com determinadas variáveis de ambiente do sistema, incluindo %USERPROFILE%.
• environment: Identifica exclusivamente este grupo de variáveis. Permite que o grupo seja posteriormente herdado numa entrada inheritEnvironments.
• groupPriority: Um inteiro que especifica a prioridade dessas variáveis ao avaliá-las. Itens de maior número são avaliados primeiro.
• inheritEnvironments: Uma matriz de valores que especifica o conjunto de ambientes que são herdados por este grupo. Esse recurso permite herdar ambientes padrão e criar variáveis de ambiente personalizadas para passar para o CMake quando ele for executado.

Visual Studio 2019 versão 16.4 e posterior: Os alvos de depuração são executados automaticamente com o ambiente que especificar no CMakeSettings.json. Você pode substituir ou adicionar variáveis de ambiente por destino ou por tarefa em launch.vs.json e tasks.vs.json.

O exemplo a seguir define uma variável global, BuildDir, que é herdada nas configurações x86-Debug e x64-Debug. Cada configuração usa a variável para especificar o valor da buildRoot propriedade para essa configuração. Observe também como cada configuração usa a inheritEnvironments propriedade para especificar uma variável que se aplica somente a essa configuração.

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

No próximo exemplo, a configuração x86-Debug define seu próprio valor para a propriedade BuildDir . Esse valor substitui o valor definido pela propriedade global BuildDir para que BuildRoot seja avaliado como 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}"
    }
  ]
}

Macros

As seguintes macros podem ser usadas em CMakeSettings.json:

• ${workspaceRoot} – o caminho completo da pasta de espaço de trabalho
• ${workspaceHash} – hash da localização do espaço de trabalho; útil para criar um identificador exclusivo para o espaço de trabalho atual (por exemplo, para usar em caminhos de pasta)
• ${projectFile}– o caminho completo do arquivo raiz CMakeLists.txt
• ${projectDir}– o caminho completo da pasta que contém o arquivo raiz CMakeLists.txt
• ${projectDirName}– o nome da pasta que contém o arquivo raiz CMakeLists.txt
• ${thisFile} – o caminho completo do CMakeSettings.json ficheiro
• ${name} – o nome da configuração
• ${generator} – o nome do gerador CMake usado nesta configuração

Todas as referências a macros e variáveis de ambiente em CMakeSettings.json são expandidas antes de serem passadas para a linha de comando do CMake.

Argumentos de linha de comando Ninja

Se os alvos não forem especificados, o Ninja criará o alvo 'padrão'.

C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise>ninja -?
ninja: invalid option -- `-?'
usage: ninja [options] [targets...]