Programkörningsversion, sysroots och beta-API:er

Artikel
04/03/2024

En Azure Sphere SDK-version kan innehålla både produktions-API:er och beta-API:er. Produktions-API:er anses vara stabila på lång sikt (LTS), medan beta-API:er fortfarande är under utveckling och kan komma att ändras eller tas bort från en senare version. I de flesta fall markeras nya API:er som betaversioner i sin första version och flyttas till produktion i en efterföljande version. Beta-API:er ger tidig åtkomst till nya funktioner, vilket möjliggör prototyper och feedback innan de slutförs. Program som använder beta-API:er kräver vanligtvis ändringar efter framtida Versioner av Azure OS och SDK för att fortsätta fungera korrekt.

Betafunktioner är märkta med BETA-funktion i dokumentationen. Varje azure sphere-program på hög nivå anger om det endast riktar in sig på produktions-API:er eller både produktions- och beta-API:er.

Mål-API-uppsättningar, ARV och sysroots

Api-måluppsättningen anger vilka API:er programmet använder: antingen endast produktions-API:er eller produktions- och beta-API:er. Värdet för api-måluppsättningen är antingen ett heltal som representerar programmets runtime-version (ARV) eller ARV plus en sträng som identifierar Beta API-versionen. Enbart det numeriska värdet anger endast produktions-API:erna i ARV, medan "värde+BetaNumber" anger produktions- och beta-API:erna i en viss version. Arv 8 anger till exempel 21.01-versionen och "8+Beta2101" anger produktions- och beta-API:erna i 20.01-versionen. Framtida versioner kommer att lägga till ytterligare ISO-filer.

Azure Sphere SDK implementerar flera API-uppsättningar med hjälp av sysroots. En sysroot anger vilka bibliotek, huvudfiler och verktyg som används för att kompilera och länka ett program som riktar sig till en viss API-uppsättning. Sysroots installeras i Microsoft Azure Sphere SDK-katalogen i undermappen sysroots.

Ange eller uppdatera mål-API:t för en app på hög nivå

Om du baserar programmet på ett Azure Sphere-exempel är mål-API:et som standard den API-uppsättning som används i exemplet. Om endast produktions-API:er används i exemplet anges det aktuella ARV-värdet till mål-API-uppsättningen. Om exemplet använder både produktions- och beta-API:er för den aktuella versionen blir mål-API-uppsättningen "värde+BetaNumber", för att inkludera beta-API:erna.

Om du inte baserar programmet på ett exempel måste du ange mål-API:t i appinstruktionerna.

Om du redan har skapat ett program kan du behöva ändra mål-API-uppsättningen om du återskapar appen för en ny OS-version. Om appen använder beta-API:er bör du uppdatera den när alternativen för mål-API-uppsättningen ändras, vilket vanligtvis inträffar vid varje funktionsversion. Beta-API:er kan flyttas direkt från betastatus till produktion, vilket resulterar i ett nytt ARV, eller så kan de ändras och finnas kvar i betaversionen. Om du uppdaterar ett program som använder beta-API:er för att rikta in sig på en nyare mål-API-uppsättning kan det uppstå fel eller varningar om borttagna eller tillbakadragna API:er.

När du ändrar mål-API-uppsättningen måste du ta bort den CMakeCache.txt filen innan du skapar programmet. Den här filen lagras i katalogen out\ARM-Debug eller out\ARM-Release för projektet.

Ange mål-API-uppsättning

Ange mål-API:et i CMakePresets.json:

Använd "AZURE_SPHERE_TARGET_API_SET" för att konfigurera mål-API-uppsättningen. Till exempel:

"AZURE_SPHERE_TARGET_API_SET": "5" Eller "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Om din app riktar in sig på den senaste API-uppsättningen kan du bara ange den här variabeln till "latest-lts", om den inte redan är det. Om din app riktar in sig på den senaste Beta-API-uppsättningen kan du bara ange den här variabeln till "senaste betaversionen", om den inte redan är det. Men om din app riktar in sig på en äldre API-uppsättning måste du ange den här variabeln så att den matchar det specifika värde den använder.

Om du vill ange den externa AZURE_SPHERE_TARGET_API_SET variabeln i ett Visual Studio-projekt anger du följande i den CMakeSettings.json filen, både i konfigurationerna ARM-Debug och ARM-Release:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Om du vill ange den externa AZURE_SPHERE_TARGET_API_SET variabeln i ett Visual Studio Code-projekt anger du följande i .vscode/settings.json-filen:
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
Om du vill ange den externa AZURE_SPHERE_TARGET_API_SET variabeln på kommandoraden tar du med parametern när du anropar CMake:

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

Ersätt "latest-lts" med "latest-beta" eller ett specifikt äldre värde, till exempel "4" eller "5+Beta2004", som beskrivits tidigare.

Mål-API-uppsättningar och OS-kompatibilitet

Kompatibiliteten för ett program med Azure Sphere-operativsystemet beror på mål-API-uppsättningen som programmet skapades med och den senaste ARV som OS-versionen stöder. Ett program eller operativsystem på lägre nivå använder ett äldre ARV (som har ett lägre tal), och ett program eller operativsystem på högre nivå använder ett nyare ARV (som har ett högre tal). I följande avsnitt beskrivs vad du kan förvänta dig i varje möjligt scenario.

Program på nedåtnivå med operativsystem på hög nivå

Befintliga avbildningar på nedåtnivå som endast använder produktions-API:er stöds i uppnivåversioner av Azure Sphere-operativsystemet. Ett program som har skapats med mål-API 1 körs till exempel på ett Azure Sphere-operativsystem som stöder ARV 2. Därför fortsätter dina befintliga distribuerade program att fungera korrekt efter molnoperativsystemuppdateringar. Du kan antingen separat inläsa eller molndetribuera avbildningar med endast produktionsnivå till ett operativsystem på hög nivå utan fel.

Bilder på nedåtnivå som använder beta-API:er stöds inte och kanske inte fungerar som de ska i uppnivåversioner av Azure Sphere-operativsystemet. Ett program som skapats med mål-API set 1+Beta1902 kan till exempel misslyckas med att köras på ett Azure Sphere-operativsystem som har ARV 2. Försök att separat läsa in en sådan avbildning returnerar ett fel om du inte använder --force flaggan på az sphere-enhetens distributionskommando för separat inläsning . På samma sätt kräver kommandot az sphere image add flaggan --force för att ladda upp en sådan avbildning. Inga aktuella kontroller förhindrar därefter att en tidigare uppladdad avbildning på nedåtnivå som använder Beta-API:er distribueras tillsammans med ett operativsystem på uppåtnivå som inte längre stöder dessa Beta-API:er.

Program på uppåtnivå med os på nedåtnivå

Program på uppåtnivå kan inte distribueras till lågnivåversioner av Azure Sphere-operativsystemet, oavsett om de använder beta-API:er. Försök att läsa in en sådan avbildning separat misslyckas med ett fel. Försök att distribuera över luften är för närvarande inte möjliga eftersom det nya SDK:et och operativsystemet släpps samtidigt.

Dela via