APIs de versão do runtime do aplicativo, sysroots e Beta

Artigo
11/05/2024

Importante

Esta é a documentação do Azure Sphere (herdado). O Azure Sphere (herdado) será desativado em 27 de setembro de 2027 e os usuários devem migrar para o Azure Sphere (integrado) até esse momento. Use o seletor de versão localizado acima do sumário para exibir a documentação do Azure Sphere (Integrado).

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 LTS (estáveis em longo prazo), enquanto as APIs beta ainda estão em desenvolvimento e podem ser alteradas ou removidas de uma versão posterior. Na maioria dos casos, as novas APIs são marcadas como Beta na primeira versão, e passam para produção em uma versão subsequente. As APIs Beta dão acesso antecipado a novas APIs, permitindo a criação de protótipos e o envio de comentários antes da finalização. Em geral, os aplicativos que usam as APIs Beta precisarão de modificações após as versões futuras do SDK e do sistema operacional do Azure para continuarem 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 serve apenas a APIs de produção ou a APIs de produção e Beta.

Conjunto de APIs de destino, ARV e sysroots

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

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

Definir ou atualizar a API de destino definida 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 usado pelo exemplo. Se o exemplo usar apenas APIs de produção, o conjunto de API de destino será definido como o valor de ARV atual. Se o exemplo usar as 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 o conjunto de API de destino nas instruções de build do aplicativo.

Se você já tiver criado um aplicativo, talvez seja necessário alterar o conjunto de API de destino ao 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 do conjunto de APIs de destino forem alteradas, o que normalmente ocorre a cada versão de recurso. APIs de beta podem ser movidos diretamente do status da versão Beta para produção, resultando em um novo ARV, ou eles podem ser alterados e permanecem na versão Beta. Se você atualizar um aplicativo que usa APIs Beta para direcionar um conjunto de APIs de destino mais recente, poderá encontrar erros ou avisos sobre APIs removidas ou desativadas.

Toda vez que você alterar o conjunto de APIs de destino, precisará excluir o arquivo CMakeCache.txt antes de compilar o aplicativo. Esse arquivo é armazenado no diretório out\ARM-Debug ou out\ARM-Release do projeto.

Especificar o conjunto de APIs de destino

Defina o conjunto de APIs de destino em CMakePresets.json:

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

"AZURE_SPHERE_TARGET_API_SET": "5" ou "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Se o seu aplicativo for direcionado ao conjunto de APIs mais recente, basta definir essa variável como "latest-lts", se ainda não estiver. Se o app for direcionado ao conjunto de APIs Beta mais recente, basta definir essa variável como "latest-beta", caso ainda não esteja. No entanto, se o aplicativo for direcionado a um conjunto de APIs mais antigo, você precisará definir essa variável para fazer a correspondência do valor específico que ela usa.

Para especificar a variável AZURE_SPHERE_TARGET_API_SET externa em um projeto do Visual Studio, defina o seguinte no arquivo CMakeSettings.json, nas configurações ARM-Debug e ARM-Release:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Para especificar a variável AZURE_SPHERE_TARGET_API_SET externa em um projeto do 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 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 de sistema operacional

A compatibilidade de um aplicativo com o sistema de operacional do Azure Sphere depende do API de destino definido com o qual o aplicativo foi compilado, e o ARV mais recente que dá suporte à 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 uma ARV mais recente (que tem um número mais alto). As seções a seguir descrevem o que esperar em cada cenário possível.

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

Há suporte para imagens de nível inferior existentes que só usam APIs de produção em versões de nível superior do sistema operacional do Azure Sphere. Por exemplo, um aplicativo que foi criado com o conjunto de APIs de destino 1 é executado com êxito em um sistema operacional Azure Sphere que dá suporte à ARV 2. Assim, os aplicativos implantados existentes continuarão funcionar corretamente após as atualizações do Cloud OS. Você pode fazer sideload ou implantar em nuvem em nível inferior apenas para produção para um sistema operacional de nível superior sem erro.

Não há suporte para imagens de nível inferior que usam APIs beta, e talvez elas não funcionem por design em versões de nível superior do sistema operacional do Azure Sphere. Por exemplo, um aplicativo que foi criado com o conjunto de APIs de destino 1+Beta1902 poderá não ser executado em um sistema operacional Azure Sphere que dá suporte à ARV 2. As tentativas de fazer o sideload dessa imagem retornam um erro, a menos que você use o --force sinalizador no comando azsphere device sideload deploy . Da mesma forma, o comando azsphere image add requer que o --force sinalizador carregue essa imagem. Nenhuma verificação atual subsequentemente impede que uma imagem de nível inferior carregada anteriormente que usa APIs da versão Beta seja implantada juntamente com um sistema operacional de nível superior que não oferece suporte a essas APIs de Beta.

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

Aplicativos de nível superior não podem ser implantados para versões de nível inferior do sistema operacional do Azure Sphere, independentemente de eles usarem APIs de Beta ou não. Tentar fazer sideload de uma imagem desse tipo falhará com um erro. Não é possível implantar via satélite no momento porque o SDK e o sistema operacional de nível superior são lançados simultaneamente.

Compartilhar via