Configuración de compilaciones mediante CMake

Artículo
09/27/2024

Importante

Esta es la documentación de Azure Sphere (heredado). Azure Sphere (heredado) se retira el 27 de septiembre de 2027 y los usuarios deben migrar a Azure Sphere (integrado) en este momento. Use el selector de versiones situado encima de la TOC para ver la documentación de Azure Sphere (integrado).

Azure Sphere usa CMake para configurar compilaciones de aplicaciones con Visual Studio, Visual Studio Code y las líneas de comandos de Windows y Linux. CMake es un sistema de código abierto, multiplataforma. Para obtener información general sobre CMake, consulte la wiki de CMake.

Las siguientes fuentes proporcionan información sobre el uso de CMake con Visual Studio o Visual Studio Code:

Las compilaciones de CMake usan los siguientes archivos:

Archivo	Fin
CMakeLists.txt	Archivo de configuración general de CMake. Obligatorio para todas las compilaciones.
CMakePresets.json	Archivo de valores preestablecidos de configuración para Visual Studio y Visual Studio Code. Este archivo o CMakeSettings.json es necesario para compilar con Visual Studio.
CMakeSettings.json	Archivo de configuración de Visual Studio. Este archivo o CMakePresets.json es necesario para compilar con Visual Studio.
CMakeWorkspaceSettings.json	Archivo de configuración de Visual Studio para proyectos con varias raíces, como en el ejemplo IntercoreComms.
.vscode/settings.json	Archivo de configuración de Visual Studio Code. Obligatorio para compilar con Visual Studio Code.

Los parámetros de CMake se separan mediante espacios. El carácter de continuación de línea "^" para la línea de comandos de Windows, " \ " para la línea de comandos de Linux o "'" para PowerShell se puede usar para mejorar la legibilidad, pero no es necesario. El carácter específico está determinado por la configuración del terminal de Windows o Linux.

Funciones de CMake para Azure Sphere

El archivo CMakeLists.txt proporciona los valores de configuración generales que CMake usa para compilar una aplicación. Azure Sphere admite el uso de las siguientes funciones en CMakeLists.txt:

Nombre	Fin
azsphere_target_hardware_definition	Especifica el hardware de destino.
azsphere_target_add_image_package	Crea un paquete de imágenes.

Si tiene una aplicación existente creada con un SDK anterior al 20.04, consulte Conversión de una aplicación existente para que use las funciones de CMake.

El archivo CMakeLists.txt debe llamar al comando project antes que cualquiera de las funciones de azsphere_.

Definición del hardware de destino

Puede especificar el hardware de destino mediante una llamada a la función azsphere_target_hardware_definition para que se almacene el valor en el archivo CMakeLists.txt. Esta función toma dos parámetros: una lista de directorios para buscar y un nombre de archivo que se va a buscar. Por ejemplo:

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

Se requiere el parámetro TARGET_DEFINITION. Especifica el nombre del archivo de definición de hardware que requiere la aplicación. El parámetro TARGET_DIRECTORY enumera los directorios en los que se va a buscar este archivo. Este parámetro es opcional; Si lo omite, CMake solo busca en la carpeta HardwareDefinitions de la instalación del SDK. Para especificar varias carpetas, incluya cada nombre de carpeta entre comillas dobles y use un espacio para separar los nombres de carpeta, como en el ejemplo. En el ejemplo, <la ruta> de acceso representa la ruta de acceso a la carpeta my_app del equipo de desarrollo.

Creación de paquetes de imágenes

Especifique el archivo de paquete de imágenes y todos los archivos de recursos que se van a incluir al compilar mediante una llamada a la función azsphere_target_add_image_package para que se almacene el valor en el archivo CMakeLists.txt. La función azsphere_target_add_image_package y el proyecto que se va a compilar son obligatorios, los archivos de recursos son opcionales.

La siguiente llamada a función crea un paquete de imágenes que contiene solo la aplicación Azure Sphere:

azsphere_target_add_image_package(${PROJECT_NAME})

En el ejemplo siguiente se crea un paquete de imágenes que contiene un certificado además de una aplicación:

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

El destino de CMake pasado a azsphere_target_add_image_package debe denominarse ${PROJECT_NAME}, y la función azsphere_target_add_image_package solo se puede llamar una vez desde el archivo CMakeLists.txt.

Funciones de CMake en desuso

Antes de la versión 24.03 del SDK, las funciones de CMake azsphere_configure_tools y azsphere_configure_api se usaron para especificar la versión de las herramientas del SDK de destino y la API de destino establecidas en el archivo CMakeLists.txt. Estas funciones ya están en desuso y el conjunto de API de destino debe especificarse en el archivo de configuración adecuado en su lugar. Consulte la página Versión del entorno de ejecución de la aplicación, sysroots y API beta para obtener más información.

Si usa una versión anterior del SDK y ve un error de configuración de CMake sobre una revisión de herramientas no admitidas, puede solucionarlo si vuelve a agregar esas funciones al CMakeLists.txt. Por ejemplo:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Eliminación de la memoria caché de CMake al cambiar los archivos de configuración

Si cambia uno de los archivos de configuración, debe eliminar la memoria caché de CMake para asegurarse de que no se produzcan errores en las compilaciones posteriores. Siga este procedimiento antes de intentar otra compilación:

Para las compilaciones de Visual Studio Code, ejecute el comando CMake:Delete Cache y Vuelva a configurar desde la paleta de comandos.
Para las compilaciones de línea de comandos (CLI), elimine el directorio de compilación que creó en un paso anterior.

Visual Studio detecta los cambios en el archivo de configuración de CMake y elimina automáticamente la memoria caché.

Conversión de una aplicación existente para que use las funciones de CMake

Si ya tiene una aplicación Azure Sphere que se ha compilado con CMake antes del SDK 20.04, debe convertirla para que pueda usar estas nuevas funciones. Puede seguir compilando estas aplicaciones sin cambios por ahora, pero la compatibilidad con ellas es limitada y se puede quitar en una versión futura.

Para ver un ejemplo de los cambios que debe realizar, consulte cómo se cambiaron los archivos de configuración de CMakeLists.txt y *.json para la aplicación de alto nivel de actualización de microcontrolador externo para la versión 20.04.

Nota:

Además de las actualizaciones para usar las funciones, estos archivos se han actualizado en los ejemplos de Azure Sphere para que usen los nombres de función en minúsculas y se adapten así a las convenciones de CMake.

Cambios de configuración en CMakeLists.txt

En los ejemplos siguientes se muestran los cambios necesarios para actualizar el archivo CMakeLists.txt de la versión 20.01 o anterior para que use las nuevas funciones.

Ejemplo del archivo CMakeLists.txt con el 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}")

Archivo CMakeLists.txt actualizado

El archivo CMakeLists.txt actualizado llama a las funciones azsphere_target_hardware_definition para establecer el hardware de destino. También llama a azsphere_target_add_image_package para compilar el paquete de imágenes y, opcionalmente, especificar los archivos que se van a incluir en él.

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:

No se admiten rutas de acceso absolutas para RESOURCE_FILES.

Configuración de CMakePresets.json de Visual Studio

El archivo CMakePresets.json permite especificar opciones comunes de configuración, compilación y prueba y, a continuación, compartirlas con desarrolladores mediante otros entornos de desarrollo. Por ejemplo, puede usar el mismo archivo de configuración preestablecidos para invocar CMake en Visual Studio, Visual Studio Code, una canalización de integración continua o desde la CLI en Windows, Linux o macOS.

A partir de la versión 22.07, los proyectos actuales usan valores preestablecidos definidos en CMakePresets.json, mientras que los proyectos existentes pueden seguir usando la configuración en CMakeSettings.json. Los ejemplos se envían solo con un archivo de configuración, ya sea CMakePresets.json o CMakeSettings.json. El entorno de desarrollo usará el archivo que está presente. Consulte cada proyecto de ejemplo para ver qué archivo se usa. Para los proyectos que usan CMakeSettings.json, consulte Cambios de configuración de Visual Studio CMakeSettings.json.

Los archivos CMakePresets.json para una aplicación de alto nivel y para una aplicación en tiempo real son muy similares; las únicas diferencias se encuentran en las CMAKE_TOOLCHAIN_FILE variables y ARM_GNU_PATH .

En una aplicación de alto nivel, ARM_GNU_PATH no se establece y CMAKE_TOOLCHAIN_FILE se establece de la siguiente manera:

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

En una aplicación en tiempo real, CMAKE_TOOLCHAIN_FILE y ARM_GNU_PATH se establecen de la siguiente manera:

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

Configuración de CMakeSettings.json de Visual Studio

Los ejemplos se envían con un archivo de configuración de CMakePresets.json o CMakeSettings.json. Consulte cada proyecto para ver qué archivo se usa. En esta sección se describe la configuración de CMakeSettings.json. Para los proyectos que usan CMakePresets.json, consulte Cambios de configuración de Visual Studio CMakePresets.json.

En los ejemplos siguientes se muestran los cambios necesarios para actualizar el archivo CMakeSettings.json en Visual Studio de la versión 20.01 o anterior para que use las nuevas funciones.

Ejemplo de archivo CMakeSettings.json del 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}"
        }
      ]
    }
  ]
}

Archivo actualizado CMakeSettings.json del SDK

El archivo CMakeSettings.json actualizado incluye los cambios siguientes:

En el campo "environments", solo se requiere "Azure Sphere".
En el campo "configuraciones" para las compilaciones Debug y Release:
- Los valores "buildRoot" y "installRoot" ya no requieren el valor AzureSphereTargetApiSet.
- La cadena de herramientas de CMake se define ahora en "cmakeToolChain", en lugar de en "variables".
- El campo "variables" especifica ahora solo el conjunto de API de destino y usa el nuevo valor "latest-lts" para indicar que el proyecto se debe compilar con el sysroot más reciente estable (LTS) de larga duración. Los valores de AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY y AZURE_SPHERE_TARGET_HARDWARE_DEFINITION ya no son necesarios, ya que estos valores ahora se establecen en el archivo 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"
        }
      ]
    }
  ]
}

Configuración de .vscode/settings.json de Visual Studio Code

En los ejemplos siguientes se muestran los cambios necesarios para actualizar el archivo .vscode/settings.json para Visual Studio Code de 20.01 o versiones anteriores para usar las nuevas funciones.

Archivo .vscode/settings.json del SDK de ejemplo 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"
}

Archivo .vscode/settings.json actualizado

El archivo .vscode/settings.json contiene la configuración del área de trabajo para Visual Studio Code.

El archivo settings.json actualizado incluye los siguientes cambios en el campo "cmake.configureSettings":

La AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY configuración y AZURE_SPHERE_TARGET_HARDWARE_DEFINITION ya no son necesarias, ya que estos valores se establecen ahora en el archivo CMakeLists.txt .
La CMAKE_TOOLCHAIN_FILE configuración y AZURE_SPHERE_TARGET_API_SET ya no son necesarias, ya que estos valores ahora están establecidos en el archivo CMakePresets.json . El AZURE_SPHERE_TARGET_API_SET valor es ahora "latest-lts", que indica que el proyecto debe compilarse con el sysroot estable a largo plazo (LTS) más reciente.

Tenga en cuenta que el "cmake.configureArgs" campo también se ha eliminado por motivos no relacionados con CMake. (El campo ya no es necesario porque el --no-warn-unused-cli parámetro no es necesario para esta compilación).

Los campos siguientes se aplican a las extensiones:

"cmake.configureOnOpen": true notifica a la extensión cmake-tools para empezar a configurar cuando se abra el área de trabajo.
"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" especifica el proveedor de IntelliSense que se va a usar para la extensión cpp-tools ; en este caso, la extensión 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"
}

Creación de un archivo de CMakeWorkspaceSettings.json

Si usa Visual Studio 2022, versión 17.1 o posterior, y tiene un proyecto con varias raíces, como el ejemplo IntercoreComms, deberá agregar un archivo de CMakeWorkspaceSettings.json a la carpeta de nivel superior del proyecto. El archivo tiene dos entradas, una para especificar que la compilación de CMake está habilitada y otra que contiene las rutas de acceso a las varias raíces. Por ejemplo, para el ejemplo IntercoreComms, el CMakeWorkspaceSettings.json tiene el siguiente contenido:

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

Las rutas de acceso se especifican en relación con la carpeta que contiene el archivo CMakeWorkspaceSettings.json.

Compartir a través de