Philip Withnall
philip.withnall@collabora.co.uk 2015
Zpětná kompatibilita v API

# Stabilita API

#

        Shrnutí

          Definujte stabilitu API zaručovanou ve vašem projektu. ()
          Zajistěte změnu čísla verze příslušně ke změnám v API. ()

# API a ABI

Ve vysokoúrovňovém programování je API (Application Programming Interface – rozhraní pro programování aplikací) hranicí mezi dvěma komponentami použitými při vývoji. Úzce souvisí s ABI (Application Binary Interface – nízkoúrovňové rozhraní aplikací), které je tou stejnou hranicí, ale za běhu. Definuje možné způsoby, kterými mohou s komponentou spolupracovat ostatní komponenty. Z praktického hlediska jsou formou API běžné hlavičkové soubory C knihovny a zkompilované knihovní symboly jsou pak ABI. Rozdíl mezi API a ABI je jen v kompilaci kódu: existují určité věci v hlavičkách C, jako třeba `#define`, které mohou způsobit, že se změní API knihovny, aniž by se změnilo ABI. Ale tyto rozdíly jsou spíše akademického rázu a v praktickém životě můžete API a ABI považovat za jinou formu téhož.

Příkladem změn narušujících kompatibilitu API ve funkci C by bylo přidání nového parametru, změna typu vraceného funkcí nebo odstranění parametru.

Ale i další části projektu mohou mít formu API. Když démon vystavuje sám sebe na sběrnici D-Bus, tak tam exportovaná rozhraní mají podobu API. Obdobně, když je API C vystaveno v jazycích vyšší úrovně pomocí GIR, tvoří soubor GIR další API — když se změní, kterýkoliv kód vyšší úrovně, který jej používá, se musí změnit také.

Dalšími příklady méně obvyklých API jsou umístění a formáty souborů s nastavením a schémata GSettings. Jakékoliv změny v nich vyžadují, aby se změnil kód používající vaši knihovnu.

# Stabilita

Stabilitou API se míní určitá úroveň záruky od projektu, že se jeho API bude v budoucnu měnit jen jasně daným způsobem, případně vůbec. Obecně je API považováno za „stabilní“, pokud přináší zpětnou kompatibilitu (viz níže). Může ale být také prohlášeno za nestabilní nebo dopředně kompatibilní. Účelem záruky na stabilitu API je umožnit lidem používat váš projekt v rámci jejich vlastního programového kódu bez obav, že jej neustále budou muset aktualizovat kvůli změnám v API. Typická záruka na stabilitu API znamená, že kód, který ke kompilován vůči jedné verzi knihovny, poběží bez problémů vůči všem budoucím verzím knihovny se stejným hlavním číslem verze, nebo obdobně, že kód, který běží vůči démonovi, poběží i vůči všem budoucím verzím démona se stejným hlavním číslem verze.

Je možné použít pro různé komponenty projektu různé úrovně stability API. Například základní funkce v knihovně budou stabilní, takže jejich API zůstane v budoucnu beze změn, zatímco novější, méně základní funkce, by zůstaly nestabilní a mohly by se značně měnit, dokud by návrh nebyl vyladěn a pak by teprve byly označené za stabilní.

Obvykle se počítá s několika běžnými typy kompatibility:

## Nestabilní

API se může v budoucnu změnit nebo může být zrušeno.

## Zpětně kompatibilní

Jsou povoleny jen změny, které umožní kódu kompilovanému vůči nezměněnému API nadále fungovat vůči změněnému API (například nesmí být odebrány funkce).

## Dopředně kompatibilní

Jsou povoleny jen změny, které umožní kódu kompilovanému vůči změněnému API fungovat i vůči nezměněnému API (například nesmí být přidány funkce).

## Zcela stabilní

Nejsou umožněny žádné změny v API, jen v implementaci.

Když nějaký projekt o svém API řekne, že je stabilní, můžete si to vyložit jako zpětnou kompatibilitu. Jen velmi málo projektů se řadí mezi úplně stabilní, protože by to bránilo skoro všem budoucím změnám v projektu.

# Číslování verzí

Záruky stability API jsou úzce svázány s číslováním verze projektu, jak s číslováním balíčku, tak s číslováním pro libtool. Číslování verzí pro libtool existuje čistě pro účely sledování stability ABI a podrobně je vysvětleno v článku Autotools Mythbuster nebo v kapitole .

Číslování verzí balíčků (hlavní.vedlejší.setinkové) má úzkou souvislost se stabilitou API: typicky se hlavní číslo verze zvyšuje, když dojde ke změně ve zpětné kompatibilitě (například, když je přejmenována funkce, změněn parametr nebo odstraněna funkce). Vedlejší číslo verze se zvyšuje, když dojde ke změnám v dopředné kompatibilitě (například, když je přidáno nové veřejné API). Setinkové číslo verze se zvyšuje, když změny v kódu nijak neovlivnily API. Další informace viz .

Číslování verzí API není důležité jen pro C, ale i pro D-Bus a schémata GSettings (pokud je předpoklad, že se budou měnit). Podrobnosti viz dokumentace k číslování verzí API pro D-Bus.

U API pro GIR se jejich stabilita obvykle řídí stabilitou API v C, protože je z něj generováno. Jedinou komplikací je, že jeho stabilita závisí navíc na verzi gobject-introspection použité při generování GIR. Ta se ale v posledních verzích příliš nemění, takže to není až tak důležité.

# Externí odkazy

Tématem stability API se zabývají následující články:

Stránka o API na Wikipedii

Stránka o ABI na Wikipedii

Dokumentace k číslování verzí D-Bus