Compartilhar via

Mapas de fornecedores da Microsoft CMakePresets.json e CMakeUserPresets.json Microsoft

  • Artigo

CMake dá suporte a dois arquivos, CMakePresets.json e CMakeUserPresets.json, que permitem aos usuários especificar as opções comuns de configuração, construção e teste e compartilhá-las com outras pessoas.

CMakePresets.json e CMakeUserPresets.json podem ser usados para conduzir o CMake no Visual Studio, no Visual Studio Code, em um pipeline de CI (Integração Contínua) e a partir da linha de comando.

CMakePresets.json destina-se a salvar builds em todo o projeto e CMakeUserPresets.json é destinado a desenvolvedores para salvar os próprios builds locais. O esquema para ambos os arquivos é idêntico.

CMakePresets.json e CMakeUserPresets.json dão suporte a mapas de fornecedores para armazenar informações específicas de fornecedores. A Microsoft mantém dois mapas de fornecedores com opções específicas para Visual Studio e Visual Studio Code. Aqui documentamos dois mapas de fornecedores da Microsoft e macros de fornecedores. Para obter mais informações sobre o restante do esquema, consulte a Documentação oficial do CMake. Isso inclui informações sobre Predefinições de Configuração, Predefinições de Build e Predefinições de Teste.

Para obter mais informações sobre como usar CMakePresets.json no Visual Studio, consulte Configurar e compilar com Predefinições do CMake no Visual Studio

Para obter mais informações sobre como usar CMakePresets.json no Visual Studio Code, consulte Configurar e compilar com Predefinições do CMake no VS Code

Mapa de fornecedores de configurações do Visual Studio

Um mapa de fornecedor com o URI de fornecedor microsoft.com/VisualStudioSettings/CMake/<version> é permitido por Predefinição de Configuração e contém as opções específicas para a integração do CMake no Visual Studio e no Visual Studio Code. Todas as opções no mapa do fornecedor se aplicam ao Visual Studio. As opções que se aplicam ao Visual Studio e ao Visual Studio Code foram marcadas explicitamente.

Todas as configurações no mapa de fornecedores de Configurações do Visual Studio são opcionais e herdadas das Predefinições de Configuração especificadas pela chave inherits. Somente as opções que foram modificadas serão gravadas no arquivo. O Mapa de fornecedores de configurações do Visual Studio é compatível com ambos CMakePresets.json e CMakeUserPresets.json.

As opções no Mapa de fornecedores de configurações do Visual Studio não afetam a construção da linha de comando do CMake ou do CTest. É assim que o mesmo arquivo CMakePresets.json poderá ser utilizado para conduzir o CMake com o Visual Studio, Visual Studio Code e a partir da linha de comando. As exceções são as opções cacheRoot e cmakeGenerateCommand. Essas opções são específicas para o cenário Abrir Cache Existente no Visual Studio e não podem ser reproduzidas na linha de comando.

Configuração Descrição
hostOS Uma matriz de OS (sistemas operacionais) com suporte. Os valores aceitos são Windows, Linux e macOS.

O valor de hostOS é usado pelo Visual Studio e pelo Visual Studio Code para ocultar as Predefinições de Configuração que não se aplicam ao sistema operacional do sistema de destino e fornecer uma melhor experiência ao usuário.

Se hostOS não for especificado, o Visual Studio e o Visual Studio Code sempre mostrarão todas as Predefinições de Configuração para seleção. Este campo também pode ser uma cadeia de caracteres, que é equivalente a uma matriz contendo uma cadeia de caracteres.

Há suporte para essa opção no Visual Studio e Visual Studio Code.
intelliSenseMode Especifica o modo usado para calcular as informações do IntelliSense no Visual Studio com o formato <target>-<toolset>-<arch>.

Valores aceitos:

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

Se intelliSenseMode não for especificado, o Visual Studio usará o modo IntelliSense que corresponde aos compiladores e à arquitetura de destino especificados. intelliSenseMode é frequentemente usado para fornecer IntelliSense aprimorado para compilação cruzada.

No Visual Studio 2019, será necessário especificar explicitamente um modo IntelliSense clang ao compilar com clang ou clang-cl.
intelliSenseOptions Um mapa de opções adicionais de configuração do IntelliSense.

useCompilerDefaults: um bool que especifica se é necessário usar os caminhos de inclusão e definição padrão do compilador para o IntelliSense. Só deverá ser false se os compiladores em uso não derem suporte a argumentos no estilo gcc. Assume o padrão de true.

additionalCompilerArgs: uma matriz de opções adicionais para controlar o IntelliSense no Visual Studio. Essa opção dá suporte à expansão de macro.
enableMicrosoftCodeAnalysis Um bool que permite a análise de código da Microsoft no Visual Studio ao compilar com cl ou clang-cl. Assume o padrão de false.
codeAnalysisRuleset Especifica o conjunto de regras a ser usado ao executar a análise de código da Microsoft no Visual Studio. É possível usar um caminho para um arquivo de conjunto de regras ou o nome de um arquivo de conjunto de regras instalado com o Visual Studio. Essa opção dá suporte à expansão de macro.
disableExternalAnalysis Um bool que especifica se a análise de código deverá ser executada em cabeçalhos externos no Visual Studio.
codeAnalysisExternalRuleset Especifica o conjunto de regras que será usado ao executar a análise de código da Microsoft no cabeçalho externo no Visual Studio. É possível usar um caminho para um arquivo de conjunto de regras ou o nome de um arquivo de conjunto de regras instalado com o Visual Studio. Essa opção dá suporte à expansão de macro.
enableClangTidyCodeAnalysis Um bool que permite a análise de código organizada no Visual Studio ao compilar com clang-cl. Assume o padrão de false.
clangTidyChecks Uma lista de avisos separados por vírgula passados para clang-tidy ao executar a análise de código clang-tidy no Visual Studio. Caracteres curinga são permitidos e o prefixo - removerá verificações.
cacheRoot Especifica o caminho para um cache do CMake. Esse diretório deve conter um arquivo CMakeCache.txt existente. Há suporte para essa chave apenas com o cenário Abrir Cache Existente no Visual Studio. Essa opção dá suporte à expansão de macro.
cmakeGenerateCommand Uma ferramenta de linha de comando (especificada como um programa de linha de comando e argumentos, por exemplo, gencache.bat debug) para gerar o cache do CMake. Esse comando executará no shell usando o ambiente especificado da predefinição quando a configuração do CMake for invocada. Há suporte para essa chave apenas com o cenário Abrir Cache Existente no Visual Studio. Essa opção dá suporte à expansão de macro.

Mapa de fornecedores de configurações remotas do Visual Studio

Um mapa de fornecedor com o URI do fornecedor microsoft.com/VisualStudioRemoteSettings/CMake/<version> é permitido por Predefinição de Configuração e contém as opções específicas para o desenvolvimento remoto no Visual Studio. Desenvolvimento remoto significa o CMake está sendo invocado em uma conexão SSH remota ou WSL. Nenhuma das opções no mapa de fornecedor de configurações remotas do Visual Studio se aplica ao Visual Studio Code.

Todas as configurações no mapa de fornecedores de configurações remotas do Visual Studio são opcionais e herdadas das Predefinições de Configuração especificadas pela chave inherits. Somente as opções que foram modificadas serão gravadas no arquivo. O mapa de fornecedores de configurações remotas do Visual Studio tem suporte em ambos CMakePresets.json e CMakeUserPresets.json.

As opções no Mapa de fornecedores de configurações do Visual Studio não afetam a construção da linha de comando do CMake ou do CTest. É assim que o mesmo arquivo CMakePresets.json poderá ser utilizado para conduzir o CMake com o Visual Studio, Visual Studio Code e a partir da linha de comando.

Muitas das opções no mapa de fornecedores de Configurações Remotas do Visual Studio serão ignoradas ao direcionar o WSL1. Isso ocorre porque o conjunto de ferramentas do WSL1 executa todos os comandos localmente e depende de unidades do Windows montadas na pasta /mnt para acessar os arquivos de origem local do WSL1. Cópias do arquivo de origem não são necessárias. As opções que são ignoradas ao direcionar o WSL1 foram marcadas explicitamente.

Configuração Descrição
sourceDir Caminho para o diretório no sistema remoto onde o projeto será copiado. Assume o padrão de $env{HOME}/.vs/$ms{projectDirName}. Essa opção dá suporte à expansão de macro.

Em cenários de cópia remota, a macro ${sourceDir} avalia o diretório de origem do projeto no sistema remoto e não o diretório de origem do projeto no computador Windows. Os cenários de cópia remota incluem direcionar uma conexão SSH remota. Nesses casos, o diretório de origem do projeto no sistema remoto é determinado pelo valor de sourceDir no mapa de fornecedores de Configurações Remotas do Visual Studio. Essa opção será ignorada ao direcionar o WSL1.
copySources Se true, o Visual Studio copiará as fontes do Windows para o sistema remoto. Defina como false se você mesmo gerencia a sincronização de arquivos. Assume o padrão de true. Essa opção será ignorada ao direcionar o WSL1.
copySourcesOptions Um objeto de opções relacionadas à cópia de origem do Windows para o sistema remoto. Esse objeto será ignorado ao direcionar o WSL1.

copySourcesOptions.exclusionList: uma lista de caminhos que serão excluídos ao copiar os arquivos de origem ao sistema remoto. Um caminho poderá ser o nome de um arquivo ou diretório ou um caminho relativo da raiz da cópia. Assume o padrão de [ ".vs", ".git", "out" ]. Essa opção dá suporte à expansão de macro.

copySourcesOptions.method: o método usado para copiar os arquivos de origem para o sistema remoto. Os valores aceitos são rsync e sftp. Assume o padrão de rsync.

copySourcesOptions.concurrentCopies: o número de cópias simultâneas usadas durante a sincronização de origens com o sistema remoto. Assume o padrão de 5.

copySourcesOptions.outputVerbosity: o nível de detalhamento das operações de cópia de origem para o sistema remoto. Os níveis aceitos são Normal, Verbose e Diagnostic. Assume o padrão de Normal.
rsyncCommandArgs Uma lista de argumentos de linha de comando passados para rsync. Assume o padrão de [ "-t", "--delete", "--delete-excluded" ]. Essa opção dá suporte à expansão de macro e é ignorada ao direcionar o WSL1.
copyBuildOutput Especifica se a saída de build do sistema remoto deverá ser copiada de volta para o Windows. Assume o padrão de false. Essa opção será ignorada ao direcionar o WSL1.
copyOptimizations Um objeto de opções relacionadas a otimizações de cópia de origem. Essas opções serão ignoradas ao direcionar o WSL1.

copyOptimizations.maxSmallChange: o número máximo de arquivos que serão copiados usando sftp em vez de rsync. O valor padrão é 10.

copyOptimizations.useOptimizations: especifica as otimizações de cópia em uso. Os valores aceitos são otimizações sem cópia (None), otimizações somente rsync (RsyncOnly) ou otimizações rsync e sftp (RsyncAndSftp). Assume o padrão de RsyncAndSftp.

copyOptimizations.rsyncSingleDirectoryCommandArgs: uma lista de argumentos de linha de comando passados para rsync ao copiar o conteúdo de um único diretório para o sistema remoto. Assume o padrão de [ "-t", "-d" ]. Essa opção dá suporte à expansão de macro.
copyAdditionalIncludeDirectoriesList Uma lista de caminhos para os diretórios de cabeçalho remotos a serem copiados localmente para o IntelliSense. Essa opção dá suporte à expansão de macro.
copyExcludeDirectoriesList Uma lista de caminhos para os diretórios de cabeçalho remotos que não devem ser copiados localmente para o IntelliSense. Essa opção dá suporte à expansão de macro.
forceWSL1Toolset Se true, o Visual Studio sempre usará o conjunto de ferramentas do WSL1 ao direcionar o WSL do Visual Studio. O conjunto de ferramentas do WSL1 executa todos os comandos localmente e conta com unidades do Windows montadas na pasta /mnt para acessar os arquivos de origem local do WSL. Essas opções podem ser mais lentas com o WSL2. Assume o padrão de false.

O conjunto de ferramentas do WSL1 sempre será usado no Visual Studio 2019 versão 16.10. Essa opção será relevante quando o suporte nativo para WSL2 estiver disponível.

Eventos remotos de pré-compilação e pós-compilação

As opções para remotePrebuildEvent e remotePostbuildEvent foram preteridas com a adoção de CMakePresets.json.

Codifique os eventos de pré-compilação, pré-vínculo e pós-compilação no CMakeLists.txt usando add_custom_command. Isso garantirá o mesmo comportamento ao compilar com o Visual Studio e a partir da linha de comando.

Se for necessário um comportamento específico para o Visual Studio, você poderá adicionar uma tarefa remota personalizada em tasks.vs.json. Para começar, clique com o botão direito do mouse na raiz CMakeLists.txt no Gerenciador de Soluções da Exibição de Pastas e selecione Configurar Tarefas. Em seguida, você poderá adicionar uma nova tarefa remota ao arquivo tasks.vs.json.

A seguinte tarefa remota cria um diretório chamado teste no sistema Linux remoto:

{
      "taskLabel": "mkdir",
      "appliesTo": "CMakeLists.txt",
      "type": "remote",
      "command": "mkdir test",
      "remoteMachineName": "localhost"
  }

Clique com o botão direito do mouse em qualquer CMakeLists.txt e selecione a opção mkdir para executar esta tarefa.

O valor de remoteMachineName deverá corresponder ao nome do host de uma conexão no Gerenciador de Conexões.

Macros de fornecedores da Microsoft

Os dois mapas de fornecedores da Microsoft, Visual Studio Settings e Visual Studio Remote Settings, dão suporte a todas as macros definidas pelo CMake. Nossos mapas de fornecedores dão suporte a todas as macros definidas pelo CMake. Para obter mais informações, consulte Expansão de macro de predefinições cmake. Todas as macros e variáveis de ambiente serão expandidas antes de passadas para o CMake.

O Visual Studio dá suporte a macros de fornecedor com o prefixo ms. As macros de fornecedores da Microsoft somente poderão ser usadas em mapas de fornecedores da Microsoft. O CMake não poderá usar as predefinições que tenham macros de fornecedores fora de um mapa de fornecedores.

Macro Descrição
$ms{projectDirName} Avalia o nome da pasta aberta no Visual Studio. Essa macro é usada para definir o valor padrão de sourceDir em cenários de cópia remota. Não há suporte para essa macro pelo Visual Studio Code. Use o ${sourceDirName} em vez disso.

Variáveis de ambiente

Macro Descrição
$env{<variable-name>}
$penv{<variable-name>}		 Variáveis de ambiente de referência usando essa sintaxe com suporte do CMake. Para obter mais informações, consulte Expansão de macro de predefinições cmake.

Macros preteridas

Algumas macros que tinha suporte do CMakeSettings.json foram preteridas com a adoção de CMakePresets.json.

Use as macros com suporte do CMake para construir os caminhos de arquivo. Quando você usar as macros, isso garantirá que o mesmo arquivo CMakePresets.json funcione dentro do Visual Studio e a partir da linha de comando.

Macro preterida Recomendação
${projectFile} ${sourceDir}/CMakeLists.txt
${thisFile} ${sourceDir}/CMakePresets.json

Sintaxe de shell aceita

Use a sintaxe $env{HOME} para fazer referência a $HOME ao construir caminhos do Linux nos mapas de fornecedores da Microsoft.