Configurar as construções com o CMake

Artigo
04/03/2024

O Azure Sphere utiliza o CMake para configurar compilações para aplicações com o Visual Studio, o Visual Studio Code e as linhas de comandos do Windows e Linux. O CMake é um sistema open source multiplataformas. Para obter informações gerais sobre cMake, veja o Wiki CMake.

As seguintes origens fornecem informações sobre a utilização do CMake com o Visual Studio ou o Visual Studio Code:

As construções CMake utilizam os seguintes ficheiros:

Ficheiro	Objetivo
CMakeLists.txt	Ficheiro de configuração CMake geral. Necessário para todas as construções.
CMakePresets.json	Ficheiro predefinido de configuração para Visual Studio e Visual Studio Code. Este ficheiro ou CMakeSettings.json é necessário para criar com o Visual Studio.
CMakeSettings.json	Ficheiro de configuração do Visual Studio. Este ficheiro ou CMakePresets.json é necessário para criar com o Visual Studio.
CMakeWorkspaceSettings.json	Ficheiro de configuração do Visual Studio para projetos com múltiplas raízes, como no exemplo IntercoreComms.
.vscode/settings.json	Ficheiro de configuração do Visual Studio Code. Necessário para criar com o Visual Studio Code.

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

Funções CMake para o Azure Sphere

O ficheiro CMakeLists.txt fornece as definições de configuração gerais que o CMake utiliza para criar uma aplicação. O Azure Sphere suporta a utilização das seguintes funções no CMakeLists.txt:

Nome	Objetivo
azsphere_target_hardware_definition	Especifique o hardware de destino.
azsphere_target_add_image_package	Criar um pacote de imagem.

Se tiver uma aplicação existente criada com um SDK anterior à 20.04, veja Converter uma aplicação existente para utilizar as funções CMake.

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

Definição de hardware de destino

Pode especificar o hardware que está a filtrar ao chamar a função azsphere_target_hardware_definition para armazenar o valor no CMakeLists.txt. Esta função utiliza dois parâmetros: uma lista de diretórios para procurar e um nome de ficheiro a procurar. 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")

É necessário o parâmetro TARGET_DEFINITION. Especifica o nome do ficheiro de definição de hardware necessário para a sua aplicação. O parâmetro TARGET_DIRECTORY lista os diretórios nos quais pretende procurar este ficheiro. Este parâmetro é opcional; Se omitir, o CMake procura apenas na pasta HardwareDefinitions na instalação do SDK. Para especificar várias pastas, coloque cada nome de pasta entre aspas duplas e utilize um espaço para separar nomes de pastas, como no exemplo. No exemplo, <> path representa o caminho para a pasta my_app no seu computador de desenvolvimento.

Criação de pacotes de imagens

Especifique o ficheiro do pacote de imagem e quaisquer ficheiros de recursos a incluir ao criar ao chamar a função azsphere_target_add_image_package para armazenar o valor no CMakeLists.txt. A função azsphere_target_add_image_package e o projeto a compilar são necessários; os ficheiros de recursos são opcionais.

A chamada de função seguinte cria um pacote de imagem que contém apenas a aplicação do Azure Sphere:

azsphere_target_add_image_package(${PROJECT_NAME})

O exemplo seguinte cria um pacote de imagem que contém um certificado para além de uma aplicação:

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

O destino CMake transmitido para azsphere_target_add_image_package tem de ter o nome ${PROJECT_NAME}, e a função azsphere_target_add_image_package só pode ser chamada uma vez a partir do ficheiro 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 foram utilizadas para especificar a versão das ferramentas do SDK de destino e a API de destino definidas no ficheiro de CMakeLists.txt. Estas funções foram preteridas e o conjunto de API de destino deve ser especificado no ficheiro de configuração adequado. Veja a página Versão do runtime da aplicação, sysroots e APIs Beta para obter detalhes.

Se estiver a utilizar uma versão mais antiga do SDK e vir um erro de configuração do CMake sobre uma revisão de ferramentas não suportadas, pode resolvê-la ao voltar a adicionar essas funções ao CMakeLists.txt. Como exemplo:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Como eliminar a cache CMake ao alterar os ficheiros de configuração

Se alterar um dos ficheiros de configuração, deve eliminar a cache CMake para garantir que as compilações subsequentes não falham. Siga este procedimento antes de tentar outra criação:

Para criar o Visual Studio Code, execute o comando CMake:Delete Cache e Reconfigure a partir da Paleta de Comandos.
Para compilações da linha de comandos (CLI), elimine o diretório de compilação que criou num passo anterior.

O Visual Studio deteta alterações ao ficheiro de configuração CMake e elimina automaticamente a cache.

Converter uma aplicação existente para utilizar as funções CMake

Se já tiver uma aplicação do Azure Sphere criada com cMake antes do SDK 20.04, deve convertê-la para utilizar estas novas funções. Ainda pode criar essas aplicações inalteradas por enquanto, mas o suporte para as mesmas é limitado e pode ser removido numa versão futura.

Para obter um exemplo das alterações que deve efetuar, veja como os ficheiros de configuração CMakeLists.txt e *.json foram alterados para a aplicação de alto nível da Atualização mcU externa para a versão 20.04.

Nota

Além das atualizações para utilizar as funções, estes ficheiros foram atualizados nos exemplos do Azure Sphere para utilizar nomes de funções em minúsculas, alinhando-se assim com as convenções CMake.

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

Os exemplos seguintes mostram as alterações necessárias para atualizar o ficheiro de CMakeLists.txt a partir da versão 20.01 ou anterior para utilizar as novas funções.

Exemplo 20.01 SDK CMakeLists.txt ficheiro

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}")

Ficheiro de CMakeLists.txt atualizado

O ficheiro de CMakeLists.txt atualizado chama as funções azsphere_target_hardware_definition para definir o hardware de destino. Também chama azsphere_target_add_image_package para criar o pacote de imagem e, opcionalmente, especifica os ficheiros a incluir no mesmo.

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

Os caminhos absolutos não são suportados para RESOURCE_FILES.

Configuração do Visual Studio CMakePresets.json

O ficheiro CMakePresets.json permite-lhe especificar opções comuns de configuração, compilação e teste e, em seguida, partilhá-las com programadores através de outros ambientes de desenvolvimento. Por exemplo, pode utilizar o mesmo ficheiro de configuração predefinido para invocar o CMake no Visual Studio, o Visual Studio Code, um pipeline de Integração Contínua ou a partir da CLI no Windows, Linux ou macOS.

A partir da versão 22.07, os projetos atuais utilizam predefinições definidas no CMakePresets.json, enquanto os projetos existentes podem continuar a utilizar definições no CMakeSettings.json. Os exemplos são enviados com apenas um ficheiro de configuração, CMakePresets.json ou CMakeSettings.json. O ambiente de desenvolvimento utilizará o ficheiro que está presente. Veja cada projeto de exemplo para ver que ficheiro é utilizado. Para projetos que utilizam CMakeSettings.json, veja Visual Studio CMakeSettings.json alterações de configuração.

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

Numa aplicação de alto nível, ARM_GNU_PATH não está definida e CMAKE_TOOLCHAIN_FILE é definida da seguinte forma:

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

Numa aplicação 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

Os exemplos são enviados com um ficheiro de configuração CMakePresets.json ou CMakeSettings.json. Veja cada projeto para ver que ficheiro é utilizado. Esta secção descreve a configuração CMakeSettings.json. Para projetos que utilizam CMakePresets.json, veja Visual Studio CMakePresets.json alterações de configuração.

Os exemplos seguintes mostram as alterações necessárias para atualizar o ficheiro de CMakeSettings.json no Visual Studio a partir da versão 20.01 ou anterior para utilizar as novas funções.

Exemplo 20.01 SDK CMakeSettings.json ficheiro

{
  "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}"
        }
      ]
    }
  ]
}

Ficheiro de CMakeSettings.json do SDK atualizado

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

No campo "ambientes", só é necessário "Azure Sphere".
No campo "configurações" para as compilações Depuração e Versão:
- Os valores "buildRoot" e "installRoot" já não requerem a definição AzureSphereTargetApiSet.
- A cadeia de ferramentas CMake está agora definida em "cmakeToolChain", em vez de em "variables".
- O campo "variables" especifica agora apenas o conjunto de API de destino e utiliza o novo valor "latest-lts" para indicar que o projeto deve ser criado com a sysroot de longo prazo (LTS) mais recente. As definições AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY e AZURE_SPHERE_TARGET_HARDWARE_DEFINITION já não são necessárias, uma vez que estes valores estão agora definidos no ficheiro deCMakeLists.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 seguintes mostram as alterações necessárias para atualizar o ficheiro .vscode/settings.json para o Visual Studio Code a partir da versão 20.01 ou anterior para utilizar as novas funções.

Exemplo 20.01 SDK .vscode/settings.json ficheiro

{
    "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"
}

Ficheiro .vscode/settings.json atualizado

O ficheiro .vscode/settings.json contém definições de área de trabalho para o Visual Studio Code.

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

As AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY definições e AZURE_SPHERE_TARGET_HARDWARE_DEFINITION já não são necessárias, porque estes valores estão agora definidos no ficheiro CMakeLists.txt .
As CMAKE_TOOLCHAIN_FILE definições e AZURE_SPHERE_TARGET_API_SET já não são necessárias, porque estes valores estão agora definidos no ficheiro CMakePresets.json . O AZURE_SPHERE_TARGET_API_SET valor é agora "latest-lts", o que indica que o projeto deve ser compilar com o sysroot mais recente de longa duração estável (LTS).

Tenha em atenção que o "cmake.configureArgs" campo também foi eliminado por razões não relacionadas com cMake. (O campo já não é necessário porque o --no-warn-unused-cli parâmetro não é necessário para esta compilação.)

Os seguintes campos aplicam-se a extensões:

"cmake.configureOnOpen": true notifica a extensão cmake-tools para começar a configurar quando a área de trabalho é aberta.
"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" especifica o fornecedor do IntelliSense a utilizar 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"
}

Criar um ficheiro de CMakeWorkspaceSettings.json

Se estiver a utilizar o Visual Studio 2022, versão 17.1 ou posterior, e tiver um projeto com múltiplas raízes, como o exemplo IntercoreComms, terá de adicionar um ficheiro CMakeWorkspaceSettings.json à pasta de nível superior do projeto. O ficheiro tem duas entradas, uma para especificar que a criação CMake está ativada e outra que contém os caminhos para as múltiplas 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 ficheiro CMakeWorkspaceSettings.json.