Versão do runtime da aplicação, 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 a 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, as novas APIs são marcadas como Beta na primeira versão e movidas para produção numa versão subsequente. As APIs Beta fornecem acesso antecipado às novas funcionalidades, permitindo o prototipagem e o feedback antes de serem finalizadas. Geralmente, as aplicações que utilizam APIs Beta exigirão modificações após futuras versões do SDK e do SO do Azure para continuarem a funcionar corretamente.

As funcionalidades beta são identificadas como funcionalidade BETA na documentação. Todas as aplicações de alto nível do Azure Sphere especificam se se destina apenas a APIs de produção ou a APIs beta e de produção.

Conjuntos de API de destino, ARV e sysroots

O conjunto de API de destino indica que APIs a aplicação utiliza: apenas APIs de produção ou APIs beta e de produção. O valor do conjunto de API de destino é um número inteiro que representa a versão do runtime da aplicação (ARV) ou o ARV mais uma cadeia 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 numa 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. As versões futuras adicionarão ARVs adicionais.

O SDK do Azure Sphere implementa vários conjuntos de API com sysroots. Um sysroot especifica as bibliotecas, ficheiros de cabeçalho e ferramentas que são utilizados para compilar e ligar uma aplicação que visa um conjunto de API específico. Os sysroots são instalados no diretório do SDK do Microsoft Azure Sphere na subpasta sysroots.

Definir ou atualizar o conjunto de API de destino para uma aplicação de alto nível

Se basear a sua aplicação num exemplo do Azure Sphere, a API de destino definida por predefinição é o conjunto de API que o exemplo utiliza. Se o exemplo utilizar apenas APIs de produção, o conjunto de API de destino será definido como o valor ARV atual. Se o exemplo utilizar as APIs beta e de produção para a versão atual, o conjunto de API de destino será "value+BetaNumber", para incluir as APIs Beta.

Se não basear a aplicação num exemplo, terá de definir a API de destino definida nas instruções de compilação da aplicação.

Se já tiver criado uma aplicação, poderá ter de alterar o conjunto de API de destino se reconstruir a aplicação para uma nova versão do SO. Se a aplicação utilizar APIs Beta, deve atualizá-la quando as opções do conjunto de API de destino forem alteradas, o que normalmente ocorre em cada lançamento de funcionalidades. As APIs Beta podem ser movidas diretamente do estado Beta para a produção, o que resulta num novo ARV ou podem ser alteradas e permanecer em Beta. Se atualizar uma aplicação que utiliza APIs Beta para direcionar um conjunto de API de destino mais recente, poderá encontrar erros ou avisos sobre APIs removidas ou descontinuadas.

Sempre que alterar o conjunto de API de destino, tem de eliminar o ficheiro CMakeCache.txt antes de criar a aplicação. Este ficheiro é armazenado no diretório out\ARM-Debug ou out\ARM-Release do seu projeto.

Especificar conjunto de API de destino

Defina a API de destino definida no CMakePresets.json:

Utilize "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 a sua aplicação tiver como destino o conjunto de API mais recente, pode definir esta variável como "latest-lts", caso ainda não esteja. Se a sua aplicação tiver como destino o conjunto de API Beta mais recente, pode definir esta variável como "latest-beta", caso ainda não esteja. No entanto, se a aplicação tiver como destino um conjunto de API mais antigo, terá de definir esta variável para corresponder ao valor específico que utiliza.

Para especificar a variável de AZURE_SPHERE_TARGET_API_SET externo num projeto do Visual Studio, defina o seguinte no ficheiro de 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 de AZURE_SPHERE_TARGET_API_SET externo num projeto do Visual Studio Code, defina o seguinte no ficheiro .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 comandos, inclua o parâmetro ao invocar 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 SO

A compatibilidade de uma aplicação com o SO do Azure Sphere depende do conjunto de API de destino com o qual a aplicação foi criada e do ARV mais recente suportado pela versão do SO. Uma aplicação ou SO de nível inferior utiliza um ARV mais antigo (que tem um número mais baixo) e uma aplicação ou SO de nível superior utiliza um ARV mais recente (que tem um número mais elevado). As secções seguintes descrevem o que esperar em cada cenário possível.

Aplicações de nível inferior com SO de nível superior

As imagens de nível inferior existentes que utilizam apenas APIs de produção são suportadas em versões de nível superior do SO do Azure Sphere. Por exemplo, uma aplicação criada com o Conjunto de API de destino 1 é executada com êxito num SO do Azure Sphere que suporta o ARV 2. Assim, as aplicações implementadas existentes continuarão a funcionar corretamente após as atualizações do SO na cloud. Pode fazer sideload ou implementar imagens apenas de produção de nível inferior na cloud para um SO de nível superior sem erros.

As imagens de nível inferior que utilizam APIs Beta não são suportadas e podem não funcionar por predefinição, em versões de nível superior do SO do Azure Sphere. Por exemplo, uma aplicação criada com o Conjunto de API de destino 1+Beta1902 pode não ser executada num SO do Azure Sphere que tenha o ARV 2. As tentativas de sideload dessa imagem devolvem um erro, a menos que utilize o --force sinalizador no comando az sphere device sideload deploy . Da mesma forma, o comando az sphere image add requer que o --force sinalizador carregue essa imagem. Posteriormente, nenhuma verificação atual impede que uma imagem de nível inferior carregada anteriormente que utilize APIs Beta seja implementada juntamente com um SO de nível superior que já não suporta essas APIs Beta.

Aplicações de nível superior com SO de nível inferior

As aplicações de nível superior não podem ser implementadas em versões de nível inferior do SO do Azure Sphere, independentemente de utilizarem APIs Beta. As tentativas de sideload dessa imagem falharão com um erro. As tentativas de implementação por excesso de ar não são atualmente possíveis porque o SDK de nível superior e o SO são libertados em simultâneo.

Partilhar via