Programkörningsversion, sysroots och Beta-API:er

Artikel
09/27/2024

Viktigt!

Det här är dokumentationen om Azure Sphere (Legacy). Azure Sphere (Legacy) upphör den 27 september 2027 och användarna måste migrera till Azure Sphere (integrerad) vid den här tiden. Använd versionsväljaren ovanför TOC för att visa dokumentationen om Azure Sphere (integrerad).

En Azure Sphere SDK-version kan innehålla både produktions-API:er och Beta-API:er. Produktions-API:er anses vara långsiktiga stabila (LTS), medan Beta-API:er fortfarande är under utveckling och kan ändras i eller tas bort från en senare version. I de flesta fall markeras nya API:er som Beta 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 att fungera korrekt.

Betafunktioner är märkta med BETA-funktion i dokumentationen. Varje Azure Sphere-högnivåprogram anger om det endast är avsett för 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 som 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 körningsversion (ARV) eller ARV plus en sträng som identifierar beta-API-versionen. Enbart det numeriska värdet anger endast produktions-API:er i ARV, medan "value+BetaNumber" anger produktions- och Beta-API:er i en viss version. ARV 8 anger till exempel versionen 21.01 och "8+Beta2101" anger produktions- och beta-API:er i 20.01-versionen. Framtida versioner lägger till ytterligare ARV:er.

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

Ange eller uppdatera mål-API:et för en högnivåapp

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

Om du inte baserar programmet på ett exempel måste du ange mål-API:et i bygginstruktionerna för appen.

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 api-måluppsä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 förbli i Beta. Om du uppdaterar ett program som använder Beta-API:er för att rikta in sig på en senare mål-API-uppsättning kan det uppstå fel eller varningar om borttagna eller tillbakadragna API:er.

Varje gång du ändrar mål-API-uppsättningen måste du ta bort 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 beta", 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 filen CMakeSettings.json, både i konfigurationerna ARM-Debug och ARM-Release:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Ange den externa AZURE_SPHERE_TARGET_API_SET variabeln i ett Visual Studio Code-projekt genom att ange följande i filen .vscode/settings.json:
```
    "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 som "4" eller "5+Beta2004" som vi förklarade tidigare.

Api-måluppsättningar och OS-kompatibilitet

Kompatibiliteten för ett program med Azure Sphere OS beror på mål-API-uppsättningen som programmet skapades med och den senaste ARV som operativsystemversionen 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å nednivå med operativsystem på hög nivå

Befintliga avbildningar på nednivå som endast använder produktions-API:er stöds i uppnivåversioner av Azure Sphere OS. Till exempel körs ett program som har skapats med mål-API Set 1 på ett Azure Sphere OS som stöder ARV 2. Därför fortsätter dina befintliga distribuerade program att fungera korrekt efter uppdateringar av molnoperativsystemet. Du kan antingen separat läsa in eller distribuera nednivåavbildningar på nednivå, endast produktion till ett operativsystem på högre nivå utan fel.

Avbildningar på nednivå som använder Beta-API:er stöds inte och fungerar kanske inte avsiktligt i versioner på högre nivå av Azure Sphere-operativsystemet. Ett program som har skapats med mål-API Set 1+Beta1902 kan till exempel misslyckas med att köras på ett Azure Sphere OS 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å kommandot azsphere device sideload deploy . På samma sätt kräver kommandot azsphere 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å nednivå som använder Beta-API:er distribueras tillsammans med ett operativsystem på hög nivå som inte längre stöder dessa Beta-API:er.

Program på hög nivå med operativsystem på nednivå

Program på hög nivå kan inte distribueras till nednivåversioner av Azure Sphere OS, oavsett om de använder Beta-API:er. Försök att separat läsa in en sådan avbildning misslyckas med ett fel. Det går för närvarande inte att distribuera over-the-air eftersom SDK:et och operativsystemet på den aktuella nivån släpps samtidigt.

Dela via