Configurar builds usando o CMake

  • Artigo

O Azure Sphere usa o CMake para configurar builds para aplicativos com Visual Studio, Visual Studio Code e as linhas de comando Windows e Linux. O CMake é um sistema de make de código aberto e multiplataforma. Para obter informações gerais sobre o CMake, consulte o CMake Wiki.

As seguintes fontes fornecem informações sobre como usar o CMake com o Visual Studio ou Visual Studio Code:

Os builds do CMake usam os seguintes arquivos:

Arquivo Propósito
CMakeLists.txt Arquivo de configuração do CMake geral. Necessário para todos os builds.
CMakePresets.json Arquivo de predefinições de configuração para Visual Studio e Visual Studio Code. Esse arquivo ou CMakeSettings.json é necessário para criar com o Visual Studio.
CMakeSettings.json Arquivo de configuração do Visual Studio. Esse arquivo ou CMakePresets.json é necessário para criar com o Visual Studio.
CMakeWorkspaceSettings.json Arquivo de configuração do Visual Studio para projetos com várias raízes, como no exemplo IntercoreComms.
.vscode/settings.json Visual Studio Code arquivo de configuração. Necessário para criar com Visual Studio Code.

Os parâmetros CMake são separados por espaços. O caractere de continuação de linha "^" para a linha de comando do Windows, " \ " para a linha de comando linux ou "'" para o Powershell pode ser usado para legibilidade, mas não é necessário. O caractere específico é determinado pela configuração do terminal do Windows ou linux.

Funções do CMake para o Azure Sphere

O arquivo CMakeLists.txt fornece as configurações gerais de configuração que o CMake usa para criar um aplicativo. O Azure Sphere dá suporte ao uso das seguintes funções no CMakeLists.txt:

Nome Propósito
azsphere_target_hardware_definition Especifique o hardware de destino.
azsphere_target_add_image_package Crie um pacote de imagem.

Se você tiver um aplicativo existente que foi criado com um SDK anterior a 20.04, consulte Converter um aplicativo existente para usar as funções CMake.

O arquivo CMakeLists.txt deve chamar o comando do projeto antes de qualquer uma das funções azsphere_ .

Definição de hardware de destino

Você pode especificar o hardware que está direcionando chamando a função azsphere_target_hardware_definition para armazenar o valor em CMakeLists.txt. Essa função usa dois parâmetros: uma lista de diretórios para pesquisar e um nome de arquivo para pesquisar. Por exemplo:

azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "<path>/my_app/contoso_hardware_definitions" "<path>/my_app/test_hardware" TARGET_DEFINITION "contoso_board.json")

O parâmetro TARGET_DEFINITION é necessário. Ele especifica o nome do arquivo de definição de hardware que seu aplicativo requer. O parâmetro TARGET_DIRECTORY lista os diretórios nos quais pesquisar esse arquivo. Esse parâmetro é opcional; se você omitir, o CMake só será visualizado na pasta HardwareDefinitions na instalação do SDK. Para especificar várias pastas, inclua cada nome da pasta em aspas duplas e use um espaço para separar nomes de pastas, como no exemplo. No exemplo, <o caminho> representa o caminho para a pasta my_app em seu computador de desenvolvimento.

Criação de pacote de imagem

Especifique o arquivo de pacote de imagem e todos os arquivos de recurso a serem incluídos ao criar chamando a função azsphere_target_add_image_package para armazenar o valor em CMakeLists.txt. A função azsphere_target_add_image_package e o projeto a ser criado são necessários; os arquivos de recurso são opcionais.

A chamada de função a seguir cria um pacote de imagens que contém apenas o aplicativo Azure Sphere:

azsphere_target_add_image_package(${PROJECT_NAME})

O próximo exemplo cria um pacote de imagem que contém um certificado além de um aplicativo:

azsphere_target_add_image_package(${PROJECT_NAME} RESOURCE_FILES "certs/bundle.pem")

O destino CMake passado para azsphere_target_add_image_package deve ser chamado ${PROJECT_NAME}, e a função azsphere_target_add_image_package pode ser chamada apenas uma vez do arquivo CMakeLists.txt.

Funções de CMake preteridas

Antes do SDK versão 24.03, as funções CMake azsphere_configure_tools e azsphere_configure_api foram usadas para especificar a versão das ferramentas SDK de destino e a API de destino definida no arquivo CMakeLists.txt. Essas funções agora estão preteridas e o conjunto de API de destino deve ser especificado no arquivo de configuração apropriado. Consulte a página Versão do runtime do aplicativo, sysroots e APIs Beta para obter detalhes.

Se você estiver usando uma versão mais antiga do SDK e vir um erro de configuração do CMake sobre uma revisão de ferramentas sem suporte, poderá contornar isso adicionando novamente essas funções ao CMakeLists.txt. Como exemplo:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Como excluir o cache CMake ao alterar arquivos de configuração

Se você alterar um dos arquivos de configuração, você deverá excluir o cache CMake para garantir que os builds subsequentes não falhem. Siga este procedimento antes de tentar outro build:

  • Para compilações Visual Studio Code, execute o comando CMake:Delete Cache e Reconfigurar na Paleta de Comandos.
  • Para builds de CLI (linha de comando), exclua o diretório de build que você criou em uma etapa anterior.

O Visual Studio detecta alterações no arquivo de configuração do CMake e exclui automaticamente o cache.

Converter um aplicativo existente para usar as funções CMake

Se você já tiver um aplicativo do Azure Sphere criado com o CMake antes do SDK 20.04, deverá convertê-lo para usar essas novas funções. Você ainda pode criar esses aplicativos inalterados por enquanto, mas o suporte para eles é limitado e pode ser removido em uma versão futura.

Para obter um exemplo das alterações que você deve fazer, veja como os arquivos de configuração CMakeLists.txt e *.json foram alterados para o aplicativo de alto nível do MCU Update externo para a versão 20.04.

Nota

Além das atualizações para usar as funções, esses arquivos foram atualizados nos exemplos do Azure Sphere para usar nomes de função minúsculas, alinhando-se com convenções do CMake.

CMakeLists.txt alterações de configuração

Os exemplos a seguir mostram as alterações necessárias para atualizar o arquivo CMakeLists.txt de 20.01 ou anterior para usar as novas funções.

Exemplo de arquivo de CMakeLists.txt do SDK 20.01

CMAKE_MINIMUM_REQUIRED(VERSION 3.8)
PROJECT(ExternalMcuUpdateNrf52 C)

ADD_EXECUTABLE(${PROJECT_NAME} main.c file_view.c mem_buf.c epoll_timerfd_utilities.c nordic/slip.c nordic/crc.c nordic/dfu_uart_protocol.c)
TARGET_LINK_LIBRARIES(${PROJECT_NAME} applibs pthread gcc_s c)

SET(ADDITIONAL_APPROOT_INCLUDES "ExternalNRF52Firmware/blinkyV1.bin;ExternalNRF52Firmware/blinkyV1.dat;ExternalNRF52Firmware/s132_nrf52_6.1.0_softdevice.bin;ExternalNRF52Firmware/s132_nrf52_6.1.0_softdevice.dat")
INCLUDE("${AZURE_SPHERE_MAKE_IMAGE_FILE}")

Arquivo CMakeLists.txt atualizado

O arquivo CMakeLists.txt atualizado chama as funções azsphere_target_hardware_definition para definir o hardware de destino. Ele também chama azsphere_target_add_image_package para criar o pacote de imagem e, opcionalmente, especificar os arquivos a serem incluídos nele.

cmake_minimum_required(VERSION 3.20)

project(ExternalMcuUpdateNrf52 C)

add_executable(${PROJECT_NAME} main.c file_view.c mem_buf.c epoll_timerfd_utilities.c nordic/slip.c nordic/crc.c nordic/dfu_uart_protocol.c)
target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c)

azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "../../../HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "sample_hardware.json")

azsphere_target_add_image_package(
    ${PROJECT_NAME}
    RESOURCE_FILES
        "ExternalNRF52Firmware/blinkyV1.bin"
        "ExternalNRF52Firmware/blinkyV1.dat"
        "ExternalNRF52Firmware/s132_nrf52_6.1.0_softdevice.bin"
        "ExternalNRF52Firmware/s132_nrf52_6.1.0_softdevice.dat")

Nota

Não há suporte para caminhos absolutos para RESOURCE_FILES.

Configuração de CMakePresets.json do Visual Studio

O arquivo CMakePresets.json permite especificar opções comuns de configurar, compilar e testar e compartilhá-las com desenvolvedores usando outros ambientes de desenvolvimento. Por exemplo, você pode usar o mesmo arquivo de configuração predefinições para invocar o CMake no Visual Studio, Visual Studio Code, um pipeline de Integração Contínua ou na CLI no Windows, Linux ou macOS.

A partir da versão 22.07, os projetos atuais usam predefinições definidas em CMakePresets.json, enquanto os projetos existentes podem continuar a usar configurações em CMakeSettings.json. Os exemplos são enviados com apenas um arquivo de configuração, CMakePresets.json ou CMakeSettings.json. O ambiente de desenvolvimento usará o arquivo presente. Consulte cada projeto de exemplo para ver qual arquivo é usado. Para projetos que usam CMakeSettings.json, consulte Alterações de configuração do Visual Studio CMakeSettings.json.

Os arquivos CMakePresets.json para um aplicativo de alto nível e para um aplicativo em tempo real são muito semelhantes; as únicas diferenças estão nas CMAKE_TOOLCHAIN_FILE variáveis e ARM_GNU_PATH .

Em um aplicativo de alto nível, ARM_GNU_PATH não é definido e CMAKE_TOOLCHAIN_FILE é definido da seguinte maneira:

    "CMAKE_TOOLCHAIN_FILE": "$env{AzureSphereDefaultSDKDir}/CMakeFiles/AzureSphereToolchain.cmake",

Em um aplicativo em tempo real, CMAKE_TOOLCHAIN_FILE e ARM_GNU_PATH são definidos da seguinte maneira:

    "CMAKE_TOOLCHAIN_FILE": "$env{AzureSphereDefaultSDKDir}/CMakeFiles/AzureSphereRTCoreToolchain.cmake",
    "ARM_GNU_PATH": "$env{ArmGnuPath}"

Configuração de CMakeSettings.json do Visual Studio

Os exemplos são enviados com um arquivo de configuração CMakePresets.json ou CMakeSettings.json. Consulte cada projeto para ver qual arquivo é usado. Esta seção descreve a configuração CMakeSettings.json. Para projetos que usam CMakePresets.json, consulte Visual Studio CMakePresets.json alterações de configuração.

Os exemplos a seguir mostram as alterações necessárias para atualizar o arquivo CMakeSettings.json no Visual Studio a partir de 20.01 ou anterior para usar as novas funções.

Exemplo de arquivo de CMakeSettings.json do SDK 20.01

{
  "environments": [
    {
      "environment": "AzureSphere",
      "AzureSphereTargetApiSet": "4",
      "AzureSphereTargetHardwareDefinitionDirectory": "${projectDir}\\..\\..\\..\\Hardware\\mt3620_rdb",
      "AzureSphereTargetHardwareDefinition": "sample_hardware.json"
    }
  ],
  "configurations": [
    {
      "name": "ARM-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [
        "AzureSphere"
      ],
      "buildRoot": "${projectDir}\\out\\${name}-${env.AzureSphereTargetApiSet}",
      "installRoot": "${projectDir}\\install\\${name}-${env.AzureSphereTargetApiSet}",
      "cmakeCommandArgs": "--no-warn-unused-cli",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": "",
      "variables": [
        {
          "name": "CMAKE_TOOLCHAIN_FILE",
          "value": "${env.AzureSphereDefaultSDKDir}CMakeFiles\\AzureSphereToolchain.cmake"
        },
        {
          "name": "AZURE_SPHERE_TARGET_API_SET",
          "value": "${env.AzureSphereTargetApiSet}"
        },
        {
          "name": "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY",
          "value": "${env.AzureSphereTargetHardwareDefinitionDirectory}"
        },
        {
          "name": "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION",
          "value": "${env.AzureSphereTargetHardwareDefinition}"
        }
      ]
    },
    {
      "name": "ARM-Release",
      "generator": "Ninja",
      "configurationType": "Release",
      "inheritEnvironments": [
        "AzureSphere"
      ],
      "buildRoot": "${projectDir}\\out\\${name}-${env.AzureSphereTargetApiSet}",
      "installRoot": "${projectDir}\\install\\${name}-${env.AzureSphereTargetApiSet}",
      "cmakeCommandArgs": "--no-warn-unused-cli",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": "",
      "variables": [
        {
          "name": "CMAKE_TOOLCHAIN_FILE",
          "value": "${env.AzureSphereDefaultSDKDir}CMakeFiles\\AzureSphereToolchain.cmake"
        },
        {
          "name": "AZURE_SPHERE_TARGET_API_SET",
          "value": "${env.AzureSphereTargetApiSet}"
        },
        {
          "name": "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY",
          "value": "${env.AzureSphereTargetHardwareDefinitionDirectory}"
        },
        {
          "name": "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION",
          "value": "${env.AzureSphereTargetHardwareDefinition}"
        }
      ]
    }
  ]
}

Arquivo de CMakeSettings.json do SDK atualizado

O arquivo CMakeSettings.json atualizado inclui as seguintes alterações:

  • No campo "ambientes", apenas "Azure Sphere" é necessário.
  • No campo "configurações" para os builds Depuração e Versão:
    • Os valores "buildRoot" e "installRoot" não exigem mais a configuração AzureSphereTargetApiSet.
    • O conjunto de ferramentas CMake agora é definido em "cmakeToolChain", em vez de em "variáveis".
    • O campo "variáveis" agora especifica apenas o conjunto de API de destino e usa o novo valor "latest-lts" para indicar que o projeto deve ser criado com o mais recente sysroot LTS (long-term-stable). As configurações AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY e AZURE_SPHERE_TARGET_HARDWARE_DEFINITION não são mais necessárias, pois esses valores agora estão definidos no arquivoCMakeLists.txt.
{
  "environments": [
    {
      "environment": "AzureSphere"
    }
  ],
  "configurations": [
    {
      "name": "ARM-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [
        "AzureSphere"
      ],
      "buildRoot": "${projectDir}\\out\\${name}",
      "installRoot": "${projectDir}\\install\\${name}",
      "cmakeToolchain": "${env.AzureSphereDefaultSDKDir}CMakeFiles\\AzureSphereToolchain.cmake",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": "",
      "variables": [
        {
          "name": "AZURE_SPHERE_TARGET_API_SET",
          "value": "latest-lts"
        }
      ]
    },
    {
      "name": "ARM-Release",
      "generator": "Ninja",
      "configurationType": "Release",
      "inheritEnvironments": [
        "AzureSphere"
      ],
      "buildRoot": "${projectDir}\\out\\${name}",
      "installRoot": "${projectDir}\\install\\${name}",
      "cmakeToolchain": "${env.AzureSphereDefaultSDKDir}CMakeFiles\\AzureSphereToolchain.cmake",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": "",
      "variables": [
        {
          "name": "AZURE_SPHERE_TARGET_API_SET",
          "value": "latest-lts"
        }
      ]
    }
  ]
}

Visual Studio Code configuração .vscode/settings.json

Os exemplos a seguir mostram as alterações necessárias para atualizar o arquivo .vscode/settings.json para Visual Studio Code de 20.01 ou anterior para usar as novas funções.

Exemplo de arquivo SDK .vscode/settings.json do SDK 20.01

{
    "cmake.generator": "Ninja",
    "cmake.buildDirectory": "${workspaceRoot}/out/${buildType}-${command:azuresphere.AzureSphereTargetApiSet}",
    "cmake.buildToolArgs": [ "-v" ],
    "cmake.configureArgs": [ "--no-warn-unused-cli" ],
    "cmake.configureSettings": {
        "CMAKE_TOOLCHAIN_FILE": "${command:azuresphere.AzureSphereSdkDir}/CMakeFiles/AzureSphereToolchain.cmake",
        "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY": "${workspaceRoot}/../../../HardwareDefinitions/mt3620_rdb",
        "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION": "sample_hardware.json",
        "AZURE_SPHERE_TARGET_API_SET": "4"
    },
    "cmake.configureOnOpen": true,
    "C_Cpp.default.configurationProvider": "vector-of-bool.cmake-tools"
}

Arquivo .vscode/settings.json atualizado

O arquivo .vscode/settings.json contém configurações de workspace para Visual Studio Code.

O arquivo settings.json atualizado inclui as seguintes alterações no campo "cmake.configureSettings":

  • As AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY configurações e AZURE_SPHERE_TARGET_HARDWARE_DEFINITION não são mais necessárias, pois esses valores agora estão definidos no arquivo CMakeLists.txt .
  • As CMAKE_TOOLCHAIN_FILE configurações e AZURE_SPHERE_TARGET_API_SET não são mais necessárias, pois esses valores agora são definidos no arquivo CMakePresets.json . O AZURE_SPHERE_TARGET_API_SET valor agora "latest-lts"é , o que indica que o projeto deve ser criado com o mais recente sysroot LTS (long-term-stable).

Observe que o "cmake.configureArgs" campo também foi excluído por razões não relacionadas ao CMake. (O campo não é mais necessário porque o --no-warn-unused-cli parâmetro não é necessário para esse build.)

Os seguintes campos se aplicam a extensões:

  • "cmake.configureOnOpen": true notifica a extensão cmake-tools para começar a configurar quando o workspace for aberto.

  • "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" especifica o provedor IntelliSense a ser usado para a extensão cpp-tools ; nesse caso, a extensão cmake-tools .

{
    "cmake.generator": "Ninja",
    "cmake.buildDirectory": "${workspaceRoot}/out/${buildType}-${command:azuresphere.AzureSphereTargetApiSet}",
    "cmake.buildToolArgs": [ "-v" ]
    },
    "cmake.configureOnOpen": true,
    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"
}

Criando um arquivo CMakeWorkspaceSettings.json

Se você estiver usando o Visual Studio 2022, versão 17.1 ou posterior e tiver um projeto com várias raízes, como o exemplo IntercoreComms, precisará adicionar um arquivo CMakeWorkspaceSettings.json à pasta de nível superior do projeto. O arquivo tem duas entradas, uma para especificar se o build do CMake está habilitado e um que contém os caminhos para as várias raízes. Por exemplo, para o exemplo IntercoreComms, o CMakeWorkspaceSettings.json tem o seguinte conteúdo:

{
  "enableCMake": true,
  "sourceDirectory": [ "IntercoreComms_HighLevelApp", "IntercoreComms_RTApp_MT3620_BareMetal" ]
}

Os caminhos são especificados em relação à pasta que contém o arquivo CMakeWorkspaceSettings.json.