애플리케이션 런타임 버전, sysroots 및 베타 API

아티클
08/09/2023

Azure Sphere SDK 릴리스에는 프로덕션 API와 베타 API가 모두 포함될 수 있습니다. 프로덕션 API는 LTS(장기 안정)로 간주되는 반면 베타 API는 아직 개발 중이며 이후 릴리스에서 변경되거나 제거될 수 있습니다. 대부분의 경우 새 API는 첫 번째 릴리스에서 베타로 표시되고 후속 릴리스에서 프로덕션으로 이동됩니다. 베타 API는 새로운 기능에 대한 초기 액세스를 제공하여 프로토타입 및 피드백이 완료되기 전에 활성화합니다. 베타 API를 사용하는 애플리케이션은 일반적으로 향후 Azure OS 및 SDK 릴리스가 제대로 작동하려면 수정이 필요합니다.

베타 기능에는 설명서의 BETA 기능 레이블이 지정됩니다. 모든 Azure Sphere 상위 수준 애플리케이션은 프로덕션 API만 대상으로 하는지 아니면 프로덕션 및 베타 API를 모두 대상으로 하는지를 지정합니다.

대상 API 집합, ARV 및 sysroots

대상 API 집합은 애플리케이션에서 사용하는 API(프로덕션 API만 또는 프로덕션 및 베타 API)를 나타냅니다. 대상 API 집합 값은 ARV(애플리케이션 런타임 버전) 또는 ARV를 나타내는 정수와 베타 API 릴리스를 식별하는 문자열입니다. 숫자 값만으로 ARV의 프로덕션 API만 지정하는 반면 "value+BetaNumber"는 특정 릴리스에서 프로덕션 및 베타 API를 지정합니다. 예를 들어 ARV 8은 21.01 릴리스를 나타내고 "8+Beta2101"은 20.01 릴리스의 프로덕션 및 베타 API를 지정합니다. 향후 릴리스는 추가 ARV를 추가합니다.

Azure Sphere SDK는 sysroots를 사용하여 여러 API 집합을 구현합니다. sysroot는 특정 API 집합을 대상으로 하는 애플리케이션을 컴파일하고 연결하는 데 사용되는 라이브러리, 헤더 파일 및 도구를 지정합니다. sysroots는 sysroots 하위 폴더의 Microsoft Azure Sphere SDK 디렉터리에 설치됩니다.

상위 수준 앱에 대한 대상 API 집합 설정 또는 업데이트

Azure Sphere 샘플에서 애플리케이션을 기반으로 하는 경우 기본적으로 설정된 대상 API는 샘플에서 사용하는 API 집합입니다. 샘플에서 프로덕션 API만 사용하는 경우 대상 API 집합이 현재 ARV 값으로 설정됩니다. 샘플에서 현재 릴리스에 프로덕션 API와 베타 API를 모두 사용하는 경우 대상 API 집합은 베타 API를 포함하기 위해 "value+BetaNumber"가 됩니다.

애플리케이션을 샘플에 기반으로 하지 않는 경우 앱에 대한 빌드 지침에서 대상 API 집합을 설정해야 합니다.

애플리케이션을 이미 만든 경우 새 OS 릴리스를 위해 앱을 다시 빌드하는 경우 대상 API 집합을 변경해야 할 수 있습니다. 앱에서 베타 API를 사용하는 경우 대상 API 집합 옵션이 변경될 때 업데이트해야 하며, 이는 일반적으로 각 기능 릴리스에서 발생합니다. 베타 API는 베타 상태 프로덕션으로 직접 이동되어 새 ARV가 생성되거나 변경되어 베타에 남아 있을 수 있습니다. 베타 API를 사용하여 최신 대상 API 집합을 대상으로 하는 애플리케이션을 업데이트하는 경우 제거되거나 사용 중지된 API에 대한 오류 또는 경고가 발생할 수 있습니다.

대상 API 집합을 변경할 때마다 애플리케이션을 빌드하기 전에 CMakeCache.txt 파일을 삭제해야 합니다. 이 파일은 프로젝트의 out\ARM-Debug 또는 out\ARM-Release 디렉터리에 저장됩니다.

대상 API 집합 지정

CMakePresets.json 대상 API 집합을 설정합니다.

"AZURE_SPHERE_TARGET_API_SET"를 사용하여 대상 API 집합을 구성합니다. 예를 들어:

"AZURE_SPHERE_TARGET_API_SET": "5" 또는 "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

앱이 최신 API 집합을 대상으로 하는 경우 아직 설정하지 않은 경우 이 변수를 "latest-lts"로 설정할 수 있습니다. 앱이 최신 베타 API 집합을 대상으로 하는 경우 아직 설정하지 않은 경우 이 변수를 "최신 베타"로 설정할 수 있습니다. 그러나 앱이 이전 API 집합을 대상으로 하는 경우 이 변수를 사용하는 특정 값과 일치하도록 설정해야 합니다.

Visual Studio 프로젝트에서 외부 AZURE_SPHERE_TARGET_API_SET 변수를 지정하려면 ARM-Debug 구성과 ARM-Release 구성 모두에서 CMakeSettings.json 파일에서 다음을 설정합니다.
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Visual Studio Code 프로젝트에서 외부 AZURE_SPHERE_TARGET_API_SET 변수를 지정하려면 .vscode/settings.json 파일에서 다음을 설정합니다.
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
명령줄에서 외부 AZURE_SPHERE_TARGET_API_SET 변수를 지정하려면 CMake를 호출할 때 매개 변수를 포함합니다.

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

앞에서 설명한 대로 "latest-lts"를 "latest-beta" 또는 특정 이전 값(예: "4" 또는 "5+Beta2004")으로 대체합니다.

대상 API 집합 및 OS 호환성

Azure Sphere OS와 애플리케이션의 호환성은 애플리케이션이 빌드된 대상 API 집합과 OS 버전이 지원하는 최신 ARV에 따라 달라집니다. 하위 수준 애플리케이션 또는 OS는 이전 ARV(숫자가 낮은)를 사용하고, 상위 수준 애플리케이션 또는 OS는 최신 ARV(숫자가 더 높임)를 사용합니다. 다음 섹션에서는 가능한 각 시나리오에서 무엇을 기대해야 하는지 설명합니다.

고급 OS를 사용하는 하위 수준 애플리케이션

프로덕션 API만 사용하는 기존 하위 수준 이미지는 Azure Sphere OS의 고급 버전에서 지원됩니다. 예를 들어 대상 API 집합 1을 사용하여 빌드된 애플리케이션은 ARV 2를 지원하는 Azure Sphere OS에서 성공적으로 실행됩니다. 따라서 기존 배포된 애플리케이션은 클라우드 OS 업데이트 후에도 계속 제대로 작동합니다. 오류 없이 하위 수준 프로덕션 전용 이미지를 상위 수준 OS에 테스트용으로 로드하거나 클라우드 배포할 수 있습니다.

베타 API를 사용하는 하위 수준 이미지는 Azure Sphere OS의 고급 버전에서 지원되지 않으며 의도적으로 작동하지 않을 수 있습니다. 예를 들어 대상 API Set 1+Beta1902로 빌드된 애플리케이션은 ARV 2가 있는 Azure Sphere OS에서 실행되지 않을 수 있습니다. az sphere device sideload deploy 명령에서 플래그를 --force 사용하지 않는 한 이러한 이미지를 사이드로드하려고 하면 오류가 반환됩니다. 마찬가지로 az sphere image add 명령을 사용하려면 플래그가 --force 이러한 이미지를 업로드해야 합니다. 이후 현재 검사는 베타 API를 사용하는 이전에 업로드된 하위 수준 이미지가 해당 베타 API를 더 이상 지원하지 않는 고급 OS와 함께 배포되는 것을 방지합니다.

하위 수준 OS를 사용하는 상위 수준 애플리케이션

상위 수준 애플리케이션은 베타 API를 사용하는지 여부에 관계없이 하위 수준 버전의 Azure Sphere OS에 배포할 수 없습니다. 이러한 이미지를 사이드로드하려고 하면 오류가 발생합니다. 현재는 고급 SDK와 OS가 동시에 릴리스되기 때문에 무선 배포 시도가 불가능합니다.