Бета-версии API, параметры sysroot и версия среды выполнения приложения

Статья
09/27/2024

Внимание

Это документация по Azure Sphere (устаревшая версия). Служба Azure Sphere (устаревшая версия) выходит на пенсию 27 сентября 2027 г., и к этому времени пользователи должны перейти в Azure Sphere (интегрированная). Используйте селектор версий, расположенный над toC, чтобы просмотреть документацию по Azure Sphere (интегрированная).

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

Функции бета-версии помечены как бета-версия в документации. В описании каждого высокоуровневого приложения Azure Sphere указывается, используются ли в приложении только рабочие версии API или рабочие версии и бета-версии API.

Целевые наборы API, ARV и параметры sysroot

Целевой набор 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 с помощью параметра sysroot. Параметр sysroot определяет набор библиотек, файлов заголовков и инструментов, которые используются для компиляции и компоновки приложения, предназначенного для конкретного набора API. Все наборы sysroot устанавливаются во вложенной папке sysroots в каталоге пакета SDK Microsoft Azure Sphere.

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

Если приложение основано на примере для Azure Sphere, по умолчанию целевым API-интерфейсом является набор API, используемый в этом примере. Если в примере используются только рабочие API, для целевого набора API будет задано текущее значение АРВ. Если в примере используются как рабочие, так и бета-версии API по состоянию для текущего выпуска, будет указан целевой набор API "значение+номер_бета_версии", чтобы он включал 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 со значением ARV, равным "1", успешно выполняется в ОС Azure Sphere, которая поддерживает значение ARV, равное "2". То есть существующие развернутые приложения будут работать правильно после установки обновлений ОС из облака. Образы более низкого уровня, предназначенные только для рабочей среды, можно без ошибок загрузить без публикации или развернуть из облака в операционную систему более высокого уровня.

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

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

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

Поделиться через