Configurar compilaciones con CMake

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

Los siguientes orígenes proporcionan información sobre el uso de CMake con Visual Studio o Visual Studio Code:

• CMake projects in Visual Studio
• Extensión CMake Tools para Visual Studio Code

Las compilaciones CMake usan los siguientes archivos:

Archivo	Propósito
CMakeLists.txt	General CMake archivo de configuración. Necesario 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 crear con Visual Studio.
CMakeSettings.json	Archivo de configuración de Visual Studio. Este archivo o CMakePresets.json es necesario para crear con Visual Studio.
CMakeWorkspaceSettings.json	Archivo de configuración de Visual Studio para proyectos con varias raíces, como en el ejemplo de IntercoreComms.
.vscode/settings.json	Visual Studio Code archivo de configuración. Necesario para la construcción con Visual Studio Code.

Los parámetros CMake están separados por 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 viene determinado por la configuración del terminal de Windows o Linux.

CMake functions for Azure Sphere

El archivo CMakeLists.txt proporciona la configuración general que CMake usa para crear una aplicación. Azure Sphere admite el uso de las siguientes funciones en CMakeLists.txt:

Nombre	Propósito
azsphere_target_hardware_definition	Especifique el hardware de destino.
azsphere_target_add_image_package	Crear un paquete de imagen.

Si tiene una aplicación existente creada con un SDK anterior a la versión 20.04, vea Convertir una aplicación existente para usar las funciones CMake.

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

Definición de hardware de destino

Puede especificar el hardware al que se dirige llamando a la función azsphere_target_hardware_definition para almacenar el valor en CMakeLists.txt. Esta función toma dos parámetros: una lista de directorios para buscar y un nombre de archivo para 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")

El parámetro TARGET_DEFINITION es obligatorio. 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 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, escriba el nombre de cada carpeta entre comillas dobles y use un espacio para separar los nombres de las carpetas, como en el ejemplo. En el ejemplo, <ruta de acceso> representa la ruta de acceso a la carpeta my_app del equipo de desarrollo.

Creación de paquetes de imagen

Especifique el archivo de paquete de imagen y los archivos de recursos que se incluirán al crear llamando a la función azsphere_target_add_image_package para almacenar el valor en CMakeLists.txt. La función azsphere_target_add_image_package y el proyecto que se va a crear son necesarios; los archivos de recursos son opcionales.

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

azsphere_target_add_image_package(${PROJECT_NAME})

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

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

El destino CMake pasado a azsphere_target_add_image_package debe llamarse ${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 CMake azsphere_configure_tools y azsphere_configure_api se usaban 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 están ahora en desuso y el conjunto de API de destino debe especificarse en el archivo de configuración adecuado en su lugar. Para obtener más información, consulta la página Versión de tiempo de ejecución de aplicaciones, sysroots y API beta .

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

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Cómo eliminar la caché de CMake al cambiar los archivos de configuración

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

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

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

Convertir una aplicación existente para usar las funciones CMake

Si ya tiene una aplicación Azure Sphere que se creó con CMake antes del SDK 20.04, debe convertirla para usar estas nuevas funciones. Por ahora, todavía puede crear estas aplicaciones sin cambios, pero la compatibilidad con ellas es limitada y puede eliminarse en una versión futura.

Para ver un ejemplo de los cambios que debes realizar, mira cómo se han cambiado los archivos de configuración CMakeLists.txt y *.json para la aplicación de alto nivel actualización de MCU externa para la versión 20.04.

Nota

Además de las actualizaciones para usar las funciones, estos archivos se han actualizado en las muestras de Azure Sphere para usar nombres de funciones en minúsculas, de modo que se alinean con las convenciones CMake.

CMakeLists.txt cambios de configuración

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

Ejemplo de archivo de 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}")

Archivo de CMakeLists.txt actualizado

El archivo CMakeLists.txt actualizado llama a las funciones de azsphere_target_hardware_definition para establecer el hardware de destino. También llama a azsphere_target_add_image_package para crear el paquete de imagen y, opcionalmente, especifica los archivos que se incluirán 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 Visual Studio CMakePresets.json

El archivo CMakePresets.json te permite especificar opciones de configuración, compilación y prueba comunes y, a continuación, compartirlas con desarrolladores que usen otros entornos de desarrollo. Por ejemplo, puede usar el mismo archivo de configuración de valores 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. Las muestras se envían con un solo 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, vea 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 son las CMAKE_TOOLCHAIN_FILE y ARM_GNU_PATH variables.

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 y CMAKE_TOOLCHAIN_FILEARM_GNU_PATH se establecen de la siguiente manera:

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

Configuración de visual Studio CMakeSettings.json

Las muestras 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, vea Cambios de configuración de Visual Studio CMakePresets.json.

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

Ejemplo de archivo de 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}"
        }
      ]
    }
  ]
}

Archivo de CMakeSettings.json SDK actualizado

El archivo CMakeSettings.json actualizado incluye los siguientes cambios:

• En el campo "entornos", solo se requiere "Azure Sphere".
• En el campo "configuraciones" para las compilaciones debug y release:
  • Los valores "buildRoot" e "installRoot" ya no requieren la configuración de AzureSphereTargetApiSet.
  • El CMake toolchain ahora se define 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 debe compilarse con la sysroot más reciente de larga duración estable (LTS). La configuración de AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY y AZURE_SPHERE_TARGET_HARDWARE_DEFINITION ya no es necesaria, ya que estos valores se establecen ahora en el archivoCMakeLists.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 Visual Studio Code .vscode/settings.json

En los ejemplos siguientes se muestran los cambios necesarios para actualizar el archivo .vscode/settings.json para Visual Studio Code de 20.01 o una versión anterior para usar las nuevas funciones.

Ejemplo 20.01 SDK .vscode/settings.json archivo

{
    "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 de Visual Studio Code.

El archivo de 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 la configuración 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 se establecen ahora en el archivo CMakePresets.json . El AZURE_SPHERE_TARGET_API_SET valor es ahora "latest-lts", lo que indica que el proyecto debe compilarse con la sysroot más reciente estable a largo plazo (LTS).

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

Los siguientes campos se aplican a extensiones:

• "cmake.configureOnOpen": true notifica a la extensión cmake-tools para empezar a configurar cuando se abre el área de trabajo.

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" especifica el proveedor de IntelliSense que se 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"
}

Crear 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 de IntercoreComms, tendrá que 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 CMake está habilitada y otra que contiene las rutas a varias raíces. Por ejemplo, para el ejemplo de IntercoreComms, el CMakeWorkspaceSettings.json tiene el contenido siguiente:

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

Las rutas de acceso se especifican con respecto a la carpeta que contiene el archivo CMakeWorkspaceSettings.json.