CMake를 사용하여 빌드 구성

Azure Sphere는 CMake를 사용하여 Visual Studio, Visual Studio Code 및 Windows 및 Linux 명령줄을 사용하는 애플리케이션에 대한 빌드를 구성합니다. CMake는 오픈 소스의 플랫폼 간 생성 도구입니다. CMake에 대한 일반적인 내용은 CMake Wiki를 참조하세요.

다음 소스는 Visual Studio 또는 Visual Studio Code에서 CMake를 사용하는 방법에 대한 정보를 제공합니다.

• Visual Studio의 CMake 프로젝트
• Visual Studio Code용 CMake 도구 확장

CMake 빌드는 다음 파일을 사용합니다.

CMake 매개 변수는 공백으로 구분됩니다. Windows 명령줄의 줄 연속 문자 "^", Linux 명령줄의 경우 "\ " 또는 Powershell의 경우 "'"를 가독성을 위해 사용할 수 있지만 필수는 아닙니다. 특정 문자는 Windows 또는 Linux 터미널 구성에 의해 결정됩니다.

Azure Sphere용 CMake 함수

CMakeLists.txt 파일은 CMake가 애플리케이션을 빌드하는 데 사용하는 일반 구성 설정을 제공합니다. Azure Sphere는 CMakeLists.txt 다음 함수의 사용을 지원합니다.

20.04 이전의 SDK로 만든 기존 애플리케이션이 있는 경우 CMake 함수를 사용하도록 기존 앱 변환을 참조 하세요.

CMakeLists.txt 파일은 azsphere_ 함수보다 먼저 프로젝트 명령을 호출해야 합니다.

대상 하드웨어 정의

azsphere_target_hardware_definition 함수를 호출하여 대상 하드웨어를 지정하여 값을 CMakeLists.txt 저장할 수 있습니다. 이 함수는 검색할 디렉터리 목록과 검색할 파일 이름이라는 두 개의 매개 변수를 사용합니다. 예시:

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

TARGET_DEFINITION 매개 변수가 필요합니다. 애플리케이션에 필요한 하드웨어 정의 파일의 이름을 지정합니다. TARGET_DIRECTORY 매개 변수는 이 파일을 검색할 디렉터리를 나열합니다. 이 매개 변수는 선택 사항입니다. 생략하면 CMake는 SDK 설치의 HardwareDefinitions 폴더에만 표시됩니다. 여러 폴더를 지정하려면 예제와 같이 각 폴더 이름을 큰따옴표로 묶고 공백을 사용하여 폴더 이름을 구분합니다. 이 예제 <에서 경로> 는 개발 머신의 my_app 폴더 경로를 나타냅니다.

이미지 패키지 생성

CMakeLists.txt 값을 저장하기 위해 azsphere_target_add_image_package 함수를 호출하여 빌드할 때 포함할 이미지 패키지 파일 및 리소스 파일을 지정합니다. azsphere_target_add_image_package 함수와 빌드할 프로젝트가 필요합니다. 리소스 파일은 선택 사항입니다.

다음 함수 호출은 Azure Sphere 애플리케이션만 포함하는 이미지 패키지를 만듭니다.

azsphere_target_add_image_package(${PROJECT_NAME})

다음 예제에서는 애플리케이션 외에도 인증서가 포함된 이미지 패키지를 만듭니다.

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

azsphere_target_add_image_package 전달된 CMake 대상의 이름은 ${PROJECT_NAME}이어야 하며 azsphere_target_add_image_package 함수는 CMakeLists.txt 파일에서 한 번만 호출할 수 있습니다.

사용되지 않는 CMake 함수

SDK 버전 24.03 이전에는 CMake 함수 azsphere_configure_tools 및 azsphere_configure_api 사용하여 CMakeLists.txt 파일에서 대상 SDK 도구 버전 및 대상 API 집합을 지정했습니다. 이러한 함수는 이제 더 이상 사용되지 않으며 대상 API 집합을 적절한 구성 파일에 대신 지정해야 합니다. 자세한 내용은 애플리케이션 런타임 버전, sysroots 및 베타 API 페이지를 참조하세요.

이전 버전의 SDK를 사용하고 지원되지 않는 도구 수정 버전에 대한 CMake 구성 오류가 표시되는 경우 해당 함수를 CMakeLists.txt 다시 추가하여 해결할 수 있습니다. 예를 들어

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

구성 파일을 변경할 때 CMake 캐시를 삭제하는 방법

구성 파일 중 하나를 변경하는 경우 후속 빌드가 실패하지 않도록 CMake 캐시를 삭제해야 합니다. 다른 빌드를 시도하기 전에 다음 절차를 수행합니다.

• Visual Studio Code 빌드의 경우 명령 팔레트에서 CMake:Delete Cache 및 Reconfigure 명령을 실행합니다.
• CLI(명령줄) 빌드의 경우 이전 단계에서 만든 빌드 디렉터리를 삭제합니다.

Visual Studio는 CMake 구성 파일의 변경 내용을 검색하고 캐시를 자동으로 삭제합니다.

CMake 함수를 사용하도록 기존 앱 변환

20.04 SDK 이전에 CMake로 빌드된 Azure Sphere 애플리케이션이 이미 있는 경우 이러한 새 함수를 사용하도록 변환해야 합니다. 지금은 이러한 애플리케이션을 변경하지 않고 빌드할 수 있지만 지원은 제한되며 향후 릴리스에서 제거될 수 있습니다.

변경해야 하는 예제를 보려면 20.04 릴리스의 외부 MCU 업데이트 상위 수준 앱에 대해 CMakeLists.txt 및 *.json 구성 파일이 어떻게 변경되었는지 확인합니다.

CMakeLists.txt 구성 변경 내용

다음 예제에서는 새 함수를 사용하기 위해 CMakeLists.txt 파일을 20.01 이하에서 업데이트하는 데 필요한 변경 내용을 보여 줍니다.

20.01 SDK CMakeLists.txt 파일 예제

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

업데이트된 CMakeLists.txt 파일

업데이트된 CMakeLists.txt 파일은 azsphere_target_hardware_definition 함수를 호출하여 대상 하드웨어를 설정합니다. 또한 azsphere_target_add_image_package를 호출하여 이미지 패키지를 빌드하고 선택적으로 포함할 파일을 지정합니다.

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

Visual Studio CMakePresets.json 구성

CMakePresets.json 파일을 사용하면 일반적인 구성, 빌드 및 테스트 옵션을 지정한 다음 다른 개발 환경을 사용하여 개발자와 공유할 수 있습니다. 예를 들어 동일한 사전 설정 구성 파일을 사용하여 Visual Studio, Visual Studio Code, 연속 통합 파이프라인 또는 Windows, Linux 또는 macOS의 CLI에서 CMake를 호출할 수 있습니다.

릴리스 22.07을 기준으로 현재 프로젝트는 CMakePresets.json 정의된 사전 설정을 사용하고, 기존 프로젝트는 CMakeSettings.json 설정을 계속 사용할 수 있습니다. 샘플은 CMakePresets.json 또는 CMakeSettings.json 하나의 구성 파일만 함께 제공됩니다. 개발 환경에서는 존재하는 파일을 사용합니다. 사용되는 파일을 보려면 각 샘플 프로젝트를 참조하세요. CMakeSettings.json 사용하는 프로젝트의 경우 Visual Studio CMakeSettings.json 구성 변경 내용을 참조 하세요.

상위 수준 애플리케이션 및 실시간 애플리케이션에 대한 CMakePresets.json 파일은 매우 유사합니다. 유일한 차이점은 변수와 ARM_GNU_PATH 변수에 CMAKE_TOOLCHAIN_FILE 있습니다.

상위 수준 애플리케이션 ARM_GNU_PATH 에서는 설정 CMAKE_TOOLCHAIN_FILE 되지 않으며 다음과 같이 설정됩니다.

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

실시간 애플리케이션 CMAKE_TOOLCHAIN_FILE ARM_GNU_PATH 에서 다음과 같이 설정됩니다.

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

Visual Studio CMakeSettings.json 구성

샘플은 CMakePresets.json 또는 CMakeSettings.json 구성 파일과 함께 제공됩니다. 사용되는 파일을 보려면 각 프로젝트를 참조하세요. 이 섹션에서는 CMakeSettings.json 구성에 대해 설명합니다. CMakePresets.json 사용하는 프로젝트의 경우 Visual Studio CMakePresets.json 구성 변경 내용을 참조 하세요.

다음 예제에서는 새 함수를 사용하기 위해 20.01 또는 이전 버전에서 Visual Studio의 CMakeSettings.json 파일을 업데이트하는 데 필요한 변경 내용을 보여 줍니다.

20.01 SDK CMakeSettings.json 파일 예제

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

업데이트된 SDK CMakeSettings.json 파일

업데이트된 CMakeSettings.json 파일에는 다음과 같은 변경 내용이 포함됩니다.

• "환경" 필드에서는 "Azure Sphere"만 필요합니다.
• 디버그 및 릴리스 빌드 모두에 대한 "구성" 필드에서 다음을 수행합니다.
  • “buildRoot” 및 “installRoot” 값에는 더 이상 AzureSphereTargetApiSet 설정이 필요하지 않습니다.
  • 이제 CMake 도구 체인이 "변수" 대신 "cmakeToolChain"에 정의됩니다.
  • “변수” 필드는 이제 대상 API 세트만 지정하고 새 “latest-lts” 값을 사용하여 프로젝트에서 가장 최근의 LTS(장기 안정적) sysroot로 빌드해야 함을 나타냅니다. 이제 이러한 값이 CMakeLists.txt 파일에 설정되므로 AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY 및 AZURE_SPHERE_TARGET_HARDWARE_DEFINITION 설정이 더 이상 필요하지 않습니다.

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

Visual Studio Code .vscode/settings.json 구성

다음 예제에서는 새 함수를 사용하기 위해 Visual Studio Code용 .vscode/settings.json 파일을 20.01 이하에서 업데이트하는 데 필요한 변경 내용을 보여 줍니다.

예제 20.01 SDK .vscode/settings.json 파일

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

.vscode/settings.json 파일이 업데이트됨

.vscode/settings.json 파일에는 Visual Studio Code에 대한 작업 영역 설정이 포함되어 있습니다.

업데이트된 settings.json 파일에는 "cmake.configureSettings" 필드에 다음과 같은 변경 내용이 포함됩니다.

• AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY AZURE_SPHERE_TARGET_HARDWARE_DEFINITION 이러한 값은 이제 CMakeLists.txt 파일에 설정되므로 더 이상 설정이 필요하지 않습니다.
• CMAKE_TOOLCHAIN_FILE AZURE_SPHERE_TARGET_API_SET 이러한 값은 이제 CMakePresets.json 파일에 설정되므로 더 이상 설정이 필요하지 않습니다. 이제 "latest-lts"이 값은 AZURE_SPHERE_TARGET_API_SET 프로젝트가 가장 최근의 LTS(장기 안정) sysroot를 사용하여 빌드되어야 했음을 나타냅니다.

CMake와 "cmake.configureArgs" 관련이 없는 이유로 필드도 삭제되었습니다. (이 빌드에 매개 변수가 --no-warn-unused-cli 필요하지 않으므로 필드가 더 이상 필요하지 않습니다.)

확장에는 다음 필드가 적용됩니다.

• "cmake.configureOnOpen": true 작업 영역이 열릴 때 구성을 시작하도록 cmake-tools 확장에 알림합니다.

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"는 cpp-tools 확장에 사용할 IntelliSense 공급자를 지정합니다. 이 경우 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"
}

CMakeWorkspaceSettings.json 파일 만들기

Visual Studio 2022 버전 17.1 이상을 사용하고 IntercoreComms 샘플과 같이 루트가 여러 개 있는 프로젝트가 있는 경우 프로젝트의 최상위 폴더에 CMakeWorkspaceSettings.json 파일을 추가해야 합니다. 파일에는 CMake 빌드를 사용하도록 지정하는 항목과 여러 루트에 대한 경로가 포함된 항목이 있습니다. 예를 들어 IntercoreComms 샘플의 경우 CMakeWorkspaceSettings.json 다음과 같은 콘텐츠가 있습니다.

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

경로는 CMakeWorkspaceSettings.json 파일이 포함된 폴더를 기준으로 지정됩니다.