Configurar compilações usando o CMake

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

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

• Projetos CMake no Visual Studio
• Extensão CMake Tools para Visual Studio Code

As compilações do CMake usam os seguintes arquivos:

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 do Linux ou "'" para Powershell pode ser usado para legibilidade, mas não é necessário. O caractere específico é determinado pela configuração do terminal Windows ou Linux.

Funções CMake para o Azure Sphere

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

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

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

Definição de hardware de destino

Você pode especificar o hardware que está segmentando chamando a função azsphere_target_hardware_definition para armazenar o valor em CMakeLists.txt. Esta 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 é obrigató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 procurar esse arquivo. Este parâmetro é opcional; se você omiti-lo, o CMake procurará somente na pasta HardwareDefinitions na instalação do SDK. Para especificar várias pastas, coloque cada nome de pasta entre aspas duplas e use um espaço para separar nomes de pastas, como no exemplo. No exemplo, <path> representa o caminho para a pasta my_app na máquina de desenvolvimento.

Criação de pacotes de imagens

Especifique o arquivo de pacote de imagem e quaisquer arquivos de recursos 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 construído são obrigatórios, os arquivos de recursos são opcionais.

A chamada de função a seguir cria um pacote de imagem 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 a partir do arquivo CMakeLists.txt.

Funções CMake preteridas

Antes da versão 24.03 do SDK, as funções CMake azsphere_configure_tools e azsphere_configure_api eram usadas para especificar a versão das ferramentas SDK de destino e a API de destino definidas no arquivo CMakeLists.txt. Essas funções agora estão obsoletas e o conjunto de APIs de destino deve ser especificado no arquivo de configuração apropriado. Consulte a página Versão do tempo de execução 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á contorná-lo adicionando novamente essas funções ao CMakeLists.txt. Em forma de 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, exclua o cache CMake para garantir que as compilações subsequentes não falhem. Siga este procedimento antes de tentar outra compilação:

• Para compilações do Visual Studio Code, execute o comando CMake:Delete Cache and Reconfigure da Paleta de Comandos.
• Para compilações de linha de comando (CLI), exclua o diretório de compilação que você criou em uma etapa anterior.

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

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

Se você já tiver um aplicativo do Azure Sphere que foi 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 Atualização MCU Externa para a versão 20.04.

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 CMakeLists.txt 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 de 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 construir 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")

Configuração do Visual Studio CMakePresets.json

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

A partir da versão 22.07, os projetos atuais usam predefinições definidas no CMakePresets.json, enquanto os projetos existentes podem continuar a usar configurações no CMakeSettings.json. As amostras são enviadas 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 Visual Studio CMakeSettings.json alterações de configuração.

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 está 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 forma:

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

Configuração do Visual Studio CMakeSettings.json

As amostras são enviadas 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 de CMakeSettings.json no Visual Studio a partir de 20.01 ou anterior para usar as novas funções.

Exemplo de arquivo CMakeSettings.json 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 SDK atualizado

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

• No campo "ambientes", apenas "Azure Sphere" é necessário.
• No campo "configurações" para as compilações Debug e Release:
  • Os valores "buildRoot" e "installRoot" não exigem mais a configuração AzureSphereTargetApiSet.
  • A cadeia de ferramentas CMake agora é definida 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 construído com o sysroot estável de longo prazo (LTS) mais recente. As configurações de AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY e AZURE_SPHERE_TARGET_HARDWARE_DEFINITION não são mais necessárias, porque esses valores agora estão definidos no arquivo CMakeLists.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"
        }
      ]
    }
  ]
}

Configuração .vscode/settings.json do Visual Studio Code

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 20.01 SDK .vscode/settings.json arquivo

{
    "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 espaço de trabalho para Visual Studio Code.

O arquivo de 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, porque esses valores agora sã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, porque esses valores agora estão definidos no arquivo CMakePresets.json . O AZURE_SPHERE_TARGET_API_SET valor é agora "latest-lts", o que indica que o projeto deve ser construído com o mais recente sysroot estável a longo prazo (LTS).

Observe que o campo também foi excluído "cmake.configureArgs" por motivos não relacionados ao CMake. (O campo não é mais necessário porque o --no-warn-unused-cli parâmetro não é necessário para esta compilação.)

Os seguintes campos aplicam-se às extensões:

• "cmake.configureOnOpen": true Notifica a extensão cmake-tools para iniciar a configuração quando o espaço de trabalho for aberto.

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" especifica o provedor IntelliSense a ser usado para a extensão cpp-tools , neste 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 que a compilação CMake está habilitada e outra contendo 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.