CMake를 사용하여 빌드 구성

  • 아티클

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

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

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

파일 목적
CMakeLists.txt 일반 CMake 구성 파일입니다. 모든 빌드에 필요합니다.
CMakePresets.json Visual Studio 및 Visual Studio Code 대한 구성 사전 설정 파일입니다. Visual Studio를 사용하여 빌드하려면 이 파일 또는 CMakeSettings.json 필요합니다.
CMakeSettings.json Visual Studio 구성 파일. Visual Studio를 사용하여 빌드하려면 이 파일 또는 CMakePresets.json 필요합니다.
CMakeWorkspaceSettings.json IntercoreComms 샘플에서와 같이 여러 루트가 있는 프로젝트에 대한 Visual Studio 구성 파일입니다.
.vscode/settings.json 구성 파일을 Visual Studio Code. Visual Studio Code 사용하여 빌드하는 데 필요합니다.

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

Azure Sphere용 CMake 함수

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

이름 목적
azsphere_target_hardware_definition 대상 하드웨어를 지정합니다.
azsphere_target_add_image_package 이미지 패키지를 만듭니다.

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 and Reconfigure 명령을 실행합니다.
  • CLI(명령줄) 빌드의 경우 이전 단계에서 만든 빌드 디렉터리를 삭제합니다.

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

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

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

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

참고

함수를 사용하는 업데이트 외에도 이러한 파일은 소문자 함수 이름을 사용하도록 Azure Sphere 샘플에서 업데이트되어 CMake 규칙에 맞게 조정됩니다.

구성 변경 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")

참고

절대 경로는 RESOURCE_FILES 지원되지 않습니다.

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 구성 변경을 참조하세요.

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

예제 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"
        }
      ]
    }
  ]
}

.vscode/settings.json 구성 Visual Studio Code

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

예제 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 이제 이러한 값이 CMakeLists.txt 파일에 설정되므로 및 AZURE_SPHERE_TARGET_HARDWARE_DEFINITION 설정이 더 이상 필요하지 않습니다.
  • CMAKE_TOOLCHAIN_FILE 이제 이러한 값이 CMakePresets.json 파일에 설정되므로 및 AZURE_SPHERE_TARGET_API_SET 설정은 더 이상 필요하지 않습니다. 값은 AZURE_SPHERE_TARGET_API_SET 이제 "latest-lts"이며, 이는 프로젝트가 가장 최근의 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 파일이 포함된 폴더를 기준으로 지정됩니다.