Versão do runtime do aplicativo, sysroots e APIs Beta

Artigo
04/03/2024

Uma versão do SDK do Azure Sphere pode conter APIs de produção e APIs Beta. As APIs de produção são consideradas estáveis de longo prazo (LTS), enquanto as APIs Beta ainda estão em desenvolvimento e podem ser alteradas ou removidas de uma versão posterior. Na maioria dos casos, novas APIs são marcadas como Beta em sua primeira versão e movidas para produção em uma versão subsequente. As APIs beta fornecem acesso antecipado a novos recursos, permitindo prototipagem e comentários antes de serem finalizados. Os aplicativos que usam APIs Beta geralmente exigirão modificações após futuras versões do sistema operacional e SDK do Azure para continuar funcionando corretamente.

Os recursos beta são rotulados como recurso BETA na documentação. Cada aplicativo de alto nível do Azure Sphere especifica se ele destina-se apenas a APIs de produção ou de produção e APIs Beta.

Conjuntos de API de destino, ARV e sysroots

O conjunto de API de destino indica quais APIs o aplicativo usa: somente APIs de produção ou produção e APIs Beta. O valor definido da API de destino é um inteiro que representa a versão de runtime do aplicativo (ARV) ou o ARV mais uma cadeia de caracteres que identifica a versão da API Beta. O valor numérico especifica apenas as APIs de produção no ARV, enquanto o "valor+BetaNumber" especifica a produção e as APIs Beta em uma versão específica. Por exemplo, o ARV 8 indica a versão 21.01 e "8+Beta2101" especifica a produção e as APIs Beta na versão 20.01. Versões futuras adicionarão ARVs adicionais.

O SDK do Azure Sphere implementa vários conjuntos de API usando sysroots. Um sysroot especifica as bibliotecas, os arquivos de cabeçalho e as ferramentas usadas para compilar e vincular um aplicativo que visa um determinado conjunto de API. Os sysroots são instalados no diretório SDK do Microsoft Azure Sphere na subpasta sysroots.

Definir ou atualizar o conjunto de API de destino para um aplicativo de alto nível

Se você basear seu aplicativo em um exemplo do Azure Sphere, a API de destino definida por padrão será o conjunto de API que o exemplo usa. Se o exemplo usar apenas APIs de produção, o conjunto de API de destino será definido como o valor ARV atual. Se o exemplo usar APIs de produção e Beta para a versão atual, o conjunto de API de destino será "value+BetaNumber", para incluir as APIs Beta.

Se você não basear seu aplicativo em um exemplo, precisará definir a API de destino definida nas instruções de build para o aplicativo.

Se você já criou um aplicativo, talvez seja necessário alterar o conjunto de API de destino se você recompilar o aplicativo para uma nova versão do sistema operacional. Se o aplicativo usar APIs Beta, você deverá atualizá-lo quando as opções de conjunto de API de destino forem alteradas, o que normalmente ocorre em cada versão do recurso. As APIs beta podem ser movidas diretamente do Beta status para a produção, resultando em um novo ARV ou podem ser alteradas e permanecer em Beta. Se você atualizar um aplicativo que usa APIs Beta para direcionar um conjunto de API de destino mais recente, você poderá encontrar erros ou avisos sobre APIs removidas ou removidas.

Sempre que você alterar o conjunto de API de destino, você precisa excluir o arquivo CMakeCache.txt antes de compilar o aplicativo. Esse arquivo é armazenado no diretório out\ARM-Debug ou out\ARM-Release para seu projeto.

Especificar conjunto de API de destino

Defina a API de destino definida em CMakePresets.json:

Use "AZURE_SPHERE_TARGET_API_SET" para configurar o conjunto de API de destino. Por exemplo:

"AZURE_SPHERE_TARGET_API_SET": "5" Ou "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Se o aplicativo atingir o conjunto de API mais recente, basta definir essa variável como "latest-lts", se ainda não estiver. Se o aplicativo tiver como destino o conjunto de API Beta mais recente, basta definir essa variável como "latest-beta", se ainda não estiver. No entanto, se o aplicativo atingir um conjunto de API mais antigo, você precisará definir essa variável para corresponder ao valor específico que ele usa.

Para especificar a variável de AZURE_SPHERE_TARGET_API_SET externa em um projeto do Visual Studio, defina o seguinte no arquivo CMakeSettings.json, dentro das configurações ARM-Debug e ARM-Release:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Para especificar a variável de AZURE_SPHERE_TARGET_API_SET externa em um projeto Visual Studio Code, defina o seguinte no arquivo .vscode/settings.json:
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
Para especificar a variável de AZURE_SPHERE_TARGET_API_SET externa na linha de comando, inclua o parâmetro ao invocar o CMake:

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

Substitua "latest-lts" por "latest-beta" ou um valor mais antigo específico, como "4" ou "5+Beta2004", conforme explicado anteriormente.

Conjuntos de API de destino e compatibilidade do sistema operacional

A compatibilidade de um aplicativo com o sistema operacional do Azure Sphere depende do conjunto de API de destino com o qual o aplicativo foi criado e do ARV mais recente compatível com a versão do sistema operacional. Um aplicativo ou sistema operacional de nível inferior usa um ARV mais antigo (que tem um número menor) e um aplicativo ou sistema operacional de nível superior usa um ARV mais recente (que tem um número maior). As seções a seguir descrevem o que esperar em cada cenário possível.

Aplicativos de nível inferior com sistema operacional de nível superior

Há suporte para imagens de nível inferior existentes que usam apenas APIs de produção em versões de nível superior do sistema operacional do Azure Sphere. Por exemplo, um aplicativo criado com a API de destino Set 1 é executado com êxito em um sistema operacional do Azure Sphere que dá suporte ao ARV 2. Assim, seus aplicativos implantados existentes continuarão a operar corretamente após as atualizações do sistema operacional de nuvem. Você pode usar sideload ou implantar imagens de nível inferior e somente produção em um sistema operacional de nível superior sem erro.

Imagens de nível inferior que usam APIs Beta não têm suporte e podem não funcionar por design em versões de nível superior do sistema operacional do Azure Sphere. Por exemplo, um aplicativo criado com a API de destino Set 1+Beta1902 pode não ser executado em um sistema operacional do Azure Sphere que tem a ARV 2. Tenta sideload de tal imagem retornar um erro, a menos que você use o --force sinalizador no comando de implantação de sideload do dispositivo az sphere . Da mesma forma, o comando az sphere image add requer o --force sinalizador para carregar tal imagem. Nenhuma verificação atual impede posteriormente que uma imagem de nível inferior carregada anteriormente que usa APIs Beta seja implantada juntamente com um sistema operacional de nível superior que não dá mais suporte a essas APIs Beta.

Aplicativos de nível superior com sistema operacional de nível inferior

Aplicativos de nível superior não podem ser implantados em versões de nível inferior do sistema operacional do Azure Sphere, independentemente de usarem APIs Beta. As tentativas de sideload dessa imagem falharão com um erro. No momento, as tentativas de implantar ao ar não são possíveis porque o SDK e o sistema operacional de nível superior são lançados simultaneamente.