Версия среды выполнения приложения, интерфейсы sysroots и бета-версии API

Статья
08/09/2023

Выпуск пакета SDK для Azure Sphere может содержать как рабочие API, так и бета-версии API. Рабочие API считаются долгосрочными стабильными (LTS), тогда как бета-версии API все еще находятся в стадии разработки и могут быть изменены или удалены из более позднего выпуска. В большинстве случаев новые API помечены как бета-версия в первом выпуске и перемещаются в рабочую среду в последующем выпуске. Бета-интерфейсы API предоставляют ранний доступ к новым функциям, позволяя создавать прототипы и оставлять отзывы до завершения их работы. Приложения, использующие бета-версии API, обычно требуют изменений после будущих выпусков ОС Azure и пакета SDK, чтобы продолжать работать правильно.

Бета-функции помечены как бета-функция в документации. Каждое высокоуровневое приложение Azure Sphere указывает, предназначено ли оно только для рабочих API или как для рабочей, так и для бета-версии.

Целевые наборы API, ARV и sysroots

Целевой набор API указывает, какие API использует приложение: только рабочие API или рабочие и бета-версии API. Целевое значение набора API — это целое число, представляющее версию среды выполнения приложения (ARV) или ARV, а также строку, идентифицирующая бета-версию API. Только числовое значение указывает только рабочие API в ARV, тогда как "value+BetaNumber" указывает рабочие и бета-интерфейсы API в определенном выпуске. Например, ARV 8 указывает выпуск 21.01, а "8+Beta2101" — рабочие и бета-версии API в выпуске 20.01. В будущих выпусках будут добавлены дополнительные ARV.

Пакет SDK для Azure Sphere реализует несколько наборов API с помощью sysroots. Sysroot указывает библиотеки, файлы заголовков и средства, используемые для компиляции и связывания приложения, предназначенного для определенного набора API. Sysroots устанавливаются в каталоге пакета SDK Microsoft Azure Sphere во вложенной папке sysroots.

Установка или обновление целевого набора API для высокоуровневого приложения

Если приложение создано на примере Azure Sphere, целевой API, заданный по умолчанию, — это набор API, используемый в примере. Если в примере используются только рабочие API, целевому набору API будет присвоено текущее значение ARV. Если в примере используются как рабочие, так и бета-версии API для текущего выпуска, целевой набор API будет иметь значение +BetaNumber для включения бета-интерфейсов API.

Если приложение не основывается на примере, необходимо задать целевой API, заданный в инструкциях по сборке приложения.

Если вы уже создали приложение, может потребоваться изменить целевой набор API, если вы перестроите приложение для нового выпуска ОС. Если приложение использует бета-версии API, его следует обновить при изменении параметров целевого набора API, что обычно происходит в каждом выпуске компонентов. Бета-интерфейсы API могут быть перемещены непосредственно из состояния бета-версии в рабочую среду, в результате чего создается новый ARV, или они могут быть изменены и останутся в бета-версии. При обновлении приложения, использующего БЕТА-интерфейсы API для назначения более недавнего набора целевых API, могут возникнуть ошибки или предупреждения об удаленных или устаревших API.

При любом изменении целевого набора API необходимо удалить файл CMakeCache.txt перед сборкой приложения. Этот файл хранится в каталоге out\ARM-Debug или out\ARM-Release проекта.

Указание целевого набора API

Задайте целевой набор API в CMakePresets.json:

Используйте AZURE_SPHERE_TARGET_API_SET для настройки целевого набора API. Например:

"AZURE_SPHERE_TARGET_API_SET": "5" Или "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Если приложение предназначено для последнего набора API, можно просто задать для этой переменной значение latest-lts, если это еще не так. Если ваше приложение предназначено для последней бета-версии набора API, можно просто задать для этой переменной значение "последняя бета-версия", если это еще не так. Однако если ваше приложение предназначено для более старого набора API, необходимо задать эту переменную, чтобы она соответствовала конкретному значению, которое оно использует.

Чтобы указать внешнюю переменную AZURE_SPHERE_TARGET_API_SET в проекте Visual Studio, задайте в CMakeSettings.json файле следующую команду в конфигурациях ARM-Debug и ARM-Release:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Чтобы указать внешнюю переменную AZURE_SPHERE_TARGET_API_SET в проекте Visual Studio Code, задайте в 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 и совместимость ОС

Совместимость приложения с ОС Azure Sphere зависит от целевого набора API, с помощью которого было создано приложение, и последней версии ARV, которую поддерживает версия ОС. Приложение нижнего уровня или ОС использует более старую версию ARV (с меньшим числом), а приложение более высокого уровня или ОС использует более новую версию ARV (с более высоким числом). В следующих разделах описывается, чего ожидать в каждом возможном сценарии.

Приложения нижнего уровня с ОС более высокого уровня

Существующие образы нижнего уровня, использующие только рабочие API, поддерживаются в более поздних версиях ОС Azure Sphere. Например, приложение, созданное с помощью целевого набора API 1, успешно работает в ОС Azure Sphere, поддерживающей ARV 2. Таким образом, существующие развернутые приложения будут продолжать работать должным образом после обновлений облачной ОС. Вы можете загружать неопубликованные образы или развертывать в облаке только рабочие образы в ОС более высокого уровня без ошибок.

Образы нижнего уровня, использующие бета-версии API, не поддерживаются и могут не работать в более поздних версиях ОС Azure Sphere. Например, приложение, созданное с помощью целевого набора API 1+Beta1902, может не работать в ОС Azure Sphere с ARV 2. Попытки загрузить неопубликованный образ возвращают ошибку, если вы не используете --force флаг в команде az sphere device sideload deploy . Аналогично команде az sphere image add требуется флаг для отправки --force такого изображения. Никакие текущие проверки впоследствии не помешают развертыванию ранее отправленного образа нижнего уровня, использующего бета-интерфейсы API, вместе с ОС более высокого уровня, которая больше не поддерживает эти бета-интерфейсы API.

Приложения более высокого уровня с ОС нижнего уровня

Приложения более высокого уровня не могут быть развернуты в версиях ОС Azure Sphere на нижнем уровне, независимо от того, используются ли в них бета-версии API. Попытка загрузить неопубликованное изображение завершится ошибкой. Попытки развертывания по беспроводной сети в настоящее время невозмочены, так как пакет SDK для более высокого уровня и ОС выпускаются одновременно.