Configurar builds usando o CMake

O Azure Sphere usa o CMake para configurar builds para aplicativos com o Visual Studio, Visual Studio Code e as linhas de comando do Windows e Linux. O CMake é um sistema make de software livre multiplataforma. Para obter informações gerais sobre o CMake, confira o wiki do CMake.

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

• Projetos do CMake no Visual Studio
• Extensão de Ferramentas do CMake para Visual Studio Code

Os builds do CMake usam os seguintes arquivos:

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

Funções do CMake para 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 criado com um SDK anterior a 20.04, confira Converter um aplicativo existente para usar as funções CMake.

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

Definição de hardware de destino

Você pode especificar o hardware ao 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 a serem pesquisados e um nome de arquivo a ser pesquisado. 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 exige. O parâmetro TARGET_DIRECTORY lista os diretórios nos quais procurar esse arquivo. Esse parâmetro é opcional; se você omiti-lo, o CMake procurará apenas 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 os nomes das pastas, como no exemplo. No exemplo, <path> representa o caminho para a pasta my_app em seu computador de desenvolvimento.

Criação do pacote de imagens

Especifique o arquivo de pacote de imagens e arquivos de recurso a serem incluídos ao compilar 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 seguinte chamada de função cria um pacote de imagens que contém apenas o aplicativo Azure Sphere:

azsphere_target_add_image_package(${PROJECT_NAME})

O seguinte exemplo cria um pacote de imagens que contém um certificado além de um aplicativo:

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

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

Funções do CMake preteridas

Antes da versão 24.03 do SDK, as funções do CMake azsphere_configure_tools e azsphere_configure_api eram usadas para especificar a versão das ferramentas do SDK de destino e o conjunto de APIs de destino 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 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. Por exemplo:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

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

Se você alterar um dos arquivos de configuração, exclua o cache do CMake para garantir que as compilações subsequentes não falhem. Siga este procedimento antes de tentar outro build:

• Para builds do Visual Studio Code, execute o comando CMake:Delete Cache and Reconfigure na Paleta de Comandos.
• Para builds da 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 do CMake

Se você já tiver um aplicativo Azure Sphere criado com o CMake antes do SDK 20.04, converta-o 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ê pode fazer, examine como os arquivos de configuração CMakeLists.txt e *.json foram alterados para o aplicativo de alto nível da Atualização do MCU externo para a versão 20.04.

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

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

Exemplo de arquivo 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")

Configuração do Visual Studio CMakePresets.json

O arquivo CMakePresets.json permite que você especifique opções comuns de configuração, compilação e teste e, em seguida, compartilhe-as com desenvolvedores que usam 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, no Visual Studio Code, em 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 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 é 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 CMakeSettings.json no Visual Studio da versão 20.01 ou anterior para usar as novas funções.

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

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

• No campo "environments", apenas "Azure Sphere" é necessário.
• No campo "configurações" para as compilações de depuração e versão:
  • Os valores "buildRoot" e "installRoot" não exigem mais a configuração AzureSphereTargetApiSet.
  • A cadeia de ferramentas do CMake agora é definida em “cmakeToolChain”, em vez de em “variables”.
  • O campo "variables" agora especifica apenas o conjunto de APIs de destino e usa o novo valor "latest-lts" para indicar que o projeto deve ser criado com o sysroot LTS (estável de longo prazo) mais recente. As configurações AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY e AZURE_SPHERE_TARGET_HARDWARE_DEFINITION não são mais necessárias, porque esses valores agora sã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 do Visual Studio Code .vscode/settings.json

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

Exemplo 20.01 Arquivo .vscode/settings.json SDK

{
    "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 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, 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 compilado com o sysroot LTS (long-term-stable) mais recente.

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 essa compilação.)

Os seguintes campos se aplicam à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 ; 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 que a compilação do CMake está habilitada e outra 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.