Referência de esquema CMakeSettings.json

  • Artigo

Os projetos do CMake são compatíveis no Visual Studio 2017 e posterior.

O arquivo CMakeSettings.json 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 compilador e configuração específica. Uma configuração especifica propriedades que se aplicam a uma plataforma específica e tipo de build, 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. O 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 arquivos CMakeLists.txt.

Você pode adicionar ou remover configurações no IDE e 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, confira Personalizar as configurações de build do CMake no Visual Studio.

Configurações

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

Um configuration tem estas propriedades:

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

  • addressSanitizerRuntimeFlags: os sinalizadores de runtime passados para AddressSanitizer na variável de ambiente ASAN_OPTIONS. Formato: flag1=value:flag2=value2.

  • buildCommandArgs: especifica as opções de build 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 de saída. Para obter mais informações sobre os comandos do Ninja, confira Argumentos de linha de comando do Ninja.

  • buildRoot: especifica o diretório no qual o CMake gera scripts de build para o gerador escolhido. É mapeado para a opção -DCMAKE_BINARY_DIR e especifica a localização em que CMakeCache.txt será criado. Se a pasta não existir, ela será criada. Macros com suporte 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 no 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 do CMake. Esse diretório deve conter um arquivo CMakeCache.txt existente.

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

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

  • cmakeToolchain: especifica o arquivo de cadeia de ferramentas. Ele é passado para o CMake usando -DCMAKE_TOOLCHAIN_FILE.

  • codeAnalysisRuleset: especifica o conjunto de regras para usar ao executar a análise de código. É possível 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 build para o gerador selecionado. Pode ser um destes:

    • Debug
    • Release
    • MinSizeRel
    • RelWithDebInfo

  • ctestCommandArgs: especifica as opções de linha de comando extras a serem passadas ao CTest ao executar os testes.

  • description: a descrição dessa configuração que será exibida nos menus.

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

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

  • generator: especifica o gerador do CMake a ser usado para essa configuração. Pode ser um destes:

    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 é criado para velocidades rápidas de builds em vez de flexibilidade e função, ele está definido como padrão. No entanto, alguns projetos do CMake podem não conseguir executar o build corretamente usando o Ninja. Se ocorrer uma falha de build, instrua o CMake a gerar projetos do Visual Studio em vez disso.

Para especificar um gerador do Visual Studio no Visual Studio 2017, abra o editor de configurações no menu principal escolhendo CMake | Alterar Configurações do CMake. Exclua "Ninja" e insira "V". Essa alteração ativa o IntelliSense, que permite escolher o gerador desejado.

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

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

"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. Macros com suporte incluem ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.

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

  • intelliSenseMode: especifica o modo usado para computar informações do IntelliSense. O valor pode ser um de:

    • 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: dá um nome à configuração. Para obter mais informações sobre as configurações predefinidas, confira Referência de configuração predefinida do CMake.

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

Configurações para projetos do CMake do Linux

  • remoteMachineName: especifica o nome do computador Linux remoto que hospeda o CMake, os builds e o depurador. Use o Gerenciador de Conexões para a adição de novos computadores Linux. Macros com suporte incluem ${defaultRemoteMachineName}.
  • remoteCopySourcesOutputVerbosity: especifica o nível de detalhamento da fonte que copia a operação no computador remoto. Pode ser um de Normal, Verbose ou Diagnostic.
  • remoteCopySourcesConcurrentCopies: especifica as cópias simultâneas usadas durante a sincronização das fontes com o computador remoto (somente sftp).
  • remoteCopySourcesMethod: especifica o método para copiar os arquivos para o computador remoto. Pode ser rsync ou sftp.
  • remoteCMakeListsRoot: especifica o diretório no computador remoto que contém o projeto do CMake. As macros com suporte incluem ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator} e ${env.VARIABLE}.
  • remoteBuildRoot: especifica o diretório no computador remoto no qual o CMake gera scripts de build para o gerador escolhido. Macros com suporte incluem ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.
  • remoteInstallRoot: especifica o diretório no computador remoto no qual o CMake gera destinos de instalação para o gerador escolhido. As macros com suporte incluem ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator} e ${env.VARIABLE}, em que VARIABLE é uma variável de ambiente definida no nível do sistema, do usuário ou da sessão.
  • remoteCopySources: um boolean que especifica se o Visual Studio deve copiar arquivos de origem no computador remoto. O padrão é true. Defina como false se você mesmo gerenciar a sincronização de arquivos.
  • remoteCopyBuildOutput: um boolean que especifica se é preciso copiar as saídas de build do sistema remoto.
  • remoteCopyAdditionalIncludeDirectories: os diretórios de inclusão adicionais a serem copiados do computador remoto para dar suporte ao IntelliSense. Usar formato como "/path1;/path2...".
  • remoteCopyExcludeDirectories: inclui diretórios que NÃO serão copiados do computador remoto. Usar formato como "/path1;/path2...".
  • remoteCopyUseCompilerDefaults: especifica se é necessário usar os caminhos de inclusão e definição padrão do compilador para o IntelliSense. Só deverá ser falso se os compiladores em uso não derem suporte a 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 ter o nome de um arquivo/diretório ou um caminho relativo à raiz da cópia. Os curingas * e ? podem ser usados para correspondência de padrão glob.
  • cmakeExecutable: especifica o caminho completo para o executável do programa do CMake, incluindo o nome e a extensão do arquivo.
  • remotePreGenerateCommand: especifica o comando a ser executado antes da execução do CMake para analisar o arquivo CMakeLists.txt.
  • remotePrebuildCommand: especifica o comando a ser executado no computador remoto antes da compilação.
  • remotePostbuildCommand: especifica o comando a ser executado no computador remoto após a compilação.
  • variables: contém um par nome-valor das variáveis do CMake que serão passadas como -D name=value para o CMake. Se as instruções de build do projeto do CMake especificam a adição de variáveis diretamente ao arquivo CMakeCache.txt, é recomendável que você as adicione aqui. Esse exemplo mostra como especificar os pares nome-valor para usar o conjunto de ferramentas 14.14.26428 do MSVC:
"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 você não definir o "type", o tipo "STRING" será assumido por padrão.

  • remoteCopyOptimizations: as propriedades do Visual Studio 2019 versão 16.5 ou posteriores para controlar a cópia de origem para o destino remoto. As otimizações são habilitadas por padrão. Inclui remoteCopyUseOptimizations, rsyncSingleDirectoryCommandArgse 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 ambiente é o mesmo que executar o msvc_x64_x64 prompt de comando do desenvolvedor para VS {version} com os argumentos -arch=amd64 -host_arch=amd64 . Você pode usar a sintaxe env.{<variable_name>} 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: direcione o Linux ARM remotamente.
  • linux_x64: direcione o Linux x64 remotamente.
  • linux_x86: direcione o Linux x86 remotamente.
  • msvc_arm: direcione o Windows ARM com o compilador do MSVC.
  • msvc_arm_x64: direcione o Windows ARM com o compilador do MSVC de 64 bits.
  • msvc_arm64: direcione o Windows ARM64 com o compilador do MSVC.
  • msvc_arm64_x64: direcione o Windows ARM64 com o compilador do MSVC de 64 bits.
  • msvc_arm64ec: direcione o Windows ARM64EC com o compilador do MSVC.
  • msvc_arm64ec_x64: direcione o Windows ARM64EC com o compilador do MSVC de 64 bits.
  • msvc_x64: direcione o Windows x64 com o compilador do MSVC.
  • msvc_x64_x64: direcione o Windows x64 com o compilador do MSVC de 64 bits.
  • msvc_x86: direcione o Windows x86 com o compilador do MSVC.
  • msvc_x86_x64: direcione o Windows x86 com o compilador do MSVC de 64 bits.

Acessar variáveis de ambiente de CMakeLists.txt

Em um arquivo CMakeLists.txt, 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 por meio de variáveis de introspecçã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 do MSVC ou a versão do SDK do Windows por meio das variáveis de ambiente.

Variáveis de ambiente personalizadas

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

  • namespace: dá um nome ao ambiente de modo que suas variáveis possam ser referenciadas de uma configuração no formato 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 esse grupo de variáveis. Permite que o grupo seja herdado posteriormente em uma 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 especificam o conjunto de ambientes herdados por esse grupo. Esse recurso permite que você herde ambientes padrão e crie variáveis de ambiente personalizadas que são passadas para o CMake quando ele é executado.

Visual Studio 2019 versão 16.4 e posterior: os destinos de depuração são iniciados automaticamente com o ambiente especificado em 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 para a propriedade buildRoot dessa configuração. Também observe como cada configuração usa a propriedade inheritEnvironments para especificar uma variável que só se aplica 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 exemplo a seguir, a configuração de Depuração x86 define seu próprio valor para a propriedade BuildDir. Esse valor substitui o valor definido pela propriedade BuildDir global de modo que BuildRoot seja avaliada 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 para a pasta de workspace
  • ${workspaceHash} – hash do local do workspace; útil para criação de um identificador exclusivo para o workspace atual (por exemplo, para uso em caminhos de pasta)
  • ${projectFile}: o caminho completo para o arquivo raiz CMakeLists.txt
  • ${projectDir}: o caminho completo para a 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 arquivo CMakeSettings.json
  • ${name} – o nome da configuração
  • ${generator} – o nome do gerador do CMake usado nessa configuração

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

Argumentos de linha de comando do Ninja

Se os destinos não estão especificados, o Ninja cria o destino 'padrão'.

C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise>ninja -?
ninja: invalid option -- `-?'
usage: ninja [options] [targets...]
Opção Descrição
--version Imprimir a versão do Ninja ("1.7.1")
-C DIR Alterar para DIR antes de qualquer outra ação
-f FILE Especificar o arquivo de build de entrada (default=build.ninja)
-j N Executar N trabalhos em paralelo (default=14, derivado das CPUs disponíveis)
-k N Continuar até N trabalhos falharem (default=1)
-l N Não iniciar novos trabalhos se a média de carga for maior que N
-n Simular (não executa comandos, mas se comporta como se eles tiveram êxito)
-v Mostrar todas as linhas de comando durante o build
-d MODE Habilitar a depuração (usar -d list para listar os modos)
-t TOOL Executar uma subferramenta (usar -t list para listar as subferramentas). Encerra as opções de nível superior; outros sinalizadores são passados para a ferramenta
-w FLAG Ajustar os avisos (usar -w list para listar os avisos)