Philip Withnall
philip.withnall@collabora.co.uk 2015

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

Jako zvláštní výjimka se vám držitelem autorských práv uděluje svolení kopírovat, upravovat a šířit ukázkový kód obsažený v tomto dokumentu za podmínek, které si zvolíte, bez dalších omezení.

Podpora introspekce pro GObject v kódu knihovny

# Introspekce

#

        Shrnutí

        GObject introspection (zkráceně „GIR“) je systém, který získává API z kódu v jazyce C a na jejich základě vytváří binární knihovny, které můžete použít k navázání jiných programovacích jazyků a v nástrojích pro introspekci nebo navázání originálních knihoven v C. Používá se k tomu systém anotací v dokumentačních komentářích ve zdrojových kódech, pomocí kterých se zveřejní doplňující informace o API, které jsou přímo z kódu strojově čitelné.

        Mělo by to být zapnuto pro všechna veřejná API, tzn. pro všechny knihovny. Zapnuto by to nemělo být pro programy, protože ty nevystavují žádná API. I tak je ale doporučeno přidat anotace k introspekci do dokumentačních komentářů v programovém kódu, aby dokumentace byla jasnější.

          Povolte introspekci pro všechny knihovny. ()
          Dávejte pozor na varování od g-ir-scanner a atribut introspectable="0" v souborech GIR. ()
          Přidávejte anotace k introspekci do všech dokumentačních komentářů. ()
          Navrhujte API už od začátku tak, aby v nich šla použít introspekce. ()

# Použití introspekce

Prvním korkem k použití introspekce je její přidání do sestavovacího systému podle instrukcí uvedených zde v metodě 1. Mělo by se tak stát v rané fázi projektu, protože schopnost introspekce ovlivňuje návrh API.

To by se mělo odrazit v souborech .gir a .typelib, které se pro projekt vygenerují. Soubor .gir je člověkem čitelný a můžete jej ručně zkoumat, jestli má API správnou introspekci (ačkoliv proces kompilace GIR vypíše chybové zprávy a varování pro chybějící anotace nebo jiné problémy). API s `introspectable="0"` nebude zpřístupněno pro vazbu na jazyk, protože mu schází anotace nebo není z jiných důvodů přítomno v souboru GIR.

Dalším krokem je přidat anotace do dokumentačních komentářů pro každou část veřejného API. Pokud některá konkrétní část nemá být v souboru GIR zpřístupněna, použijte anotaci `(skip)`. Dokumentaci se seznamem dostupných anotací najdete zde.

Když vytváříte anotace kódu pro program, je dobrým zvykem rozdělik hromadu kódu do vhodných interních privátních knihoven. Z dokumentačních komentářů pak můžete sestavit referenční příručku k API (viz ). Takovéto knihovny se pak neinstalují, ale přímo slinkují s vlastním programem. Přínos vygenerované interní dokumentace oceníte především u velkých projektů, kde interní kód může být opravdu rozsáhlý a těžko se v něm orientuje.

Anotace by ale neměly být přidávány bezúčelně: GIR má sadu výchozích anotací, které se použijí na základě různých pravidel (viz ). Například parametr `const gchar*` nepotřebuje výslovně uvádět anotaci `(transfer none)`, protože to dává najevo již modifikátor `const`. Když se tyto výchozí anotace naučíte, jen to prospěje věci.

# Návrh API

Aby API podporovalo introspekci bez přílišného množství anotací, musí dodržovat jisté zvyklosti, jako třeba standardní konvenci názvů GObject a konvenci pro API podporující vazby na jiné jazyky. To je nutné kvůli flexibilitě C: programový kód, který se chová slušně, může být napsán všemožnými způsoby, ale vysokoúrovňové jazyky tento druh volnosti nedovolují. Takže aby API v jazyce C mohlo být zpřístupněno ve vysokoúrovňovém jazyce, musí se podřídit chování podporovanému tímto jazykem.

Například GIR očekává, že jestliže funkce může selhat, tak vrací parametr `GError**`, který je vždy posledním parametrem. Analyzátor GIR takovýto parametr odhalí a automaticky převede atribut výjimky u metody v souboru GIR. Nemůže to ale udělat, pokud je například `GError**` vracen přímo nebo není posledním parametrem.

Proto musí být API navržena pro introspekci a při jejich psaní by měl být překontrolováván soubor GIR. Když GIR neodpovídá tomu, co pro nové API očekáváte, potřebuje API dodatečné anotace nebo i změnu v deklaraci C (jako v případě `va_list`).

g-ir-scanner vyšle varování, když narazí na kód, kterému nerozumí. Předání --warn-error nebo také --warn-all v `INTROSPECTION_SCANNER_ARGS` v Makefile.am způsobí, že kompilace selže, když se narazí na API nepodporující introspekci. Tím se zajistí, že nová API budou vždy podporovat introspekci, což je silně doporučováno.