Philip Withnall
philip.withnall@collabora.co.uk 2015, 2016
Jak předejít konfliktům v symbolech mezi knihovnami pomocí jmenných prostorů ve všech API

# Jmenné prostory

#

        Shrnutí

        Když má knihovna přidělený správný jmenný prostor, může ve svém API definovat typy a metody, které mají stejné názvy jako v jiných knihovnách a program ji s nimi může použít souběžně, aniž by došlo ke konfliktům. Je toho dosaženo díky předřazení prefixu v podobě jedinečného jmenného prostoru knihovny před názvy všech typů a metod.

# API pro GObject

Jednotné a úplné jmenné prostory symbolů (funkcí a typů) a souborů jsou důležité ze dvou hlavních důvodů:

Zavedení zvyklostí, které pro vývojáře znamenají, že si stačí zapamatovat pár názvů symbolů, aby mohli knihovnu používat – zbytek si mohou snadno domyslet.

Zajištění, že symboly ze dvou projektů nebudou ve vzájemném konfliktu, když jsou vložené do stejného souboru.

Druhý bod je velmi důležitý — představte si, co by se stalo, když by každý projekt exportoval funkci nazvanou `create_object()`. Hlavičkové soubory, které by ji definovaly, by pak nemohly být vložené naráz ve stejném souboru. A i kdyby mohly, programátor by pak stejně nevěděl, ze kterého projektu je která. Jmenné prostory tento problém řeší pomocí použití jedinečného a jednotného prefixu pro všechny symboly a názvy souborů v projektu, čímž se symboly seskupí ve svém projektu a oddělí od ostatních projektů.

Konvence uvedené níže by se měly používat pro jmenné prostory všech symbolů. Jsou použity ve všech projektech založených na GLib, a měly by tak být dobře známy velkému množství vývojářů:

Funkce by měly používat `mala_pismena_s_podtrzitky`.

Struktury, typy a objekty by měly používat `VelkaPismenaNaZacatkuSlovBezPodtrzitek`.

Makra a konstanty by měly používat `VELKA_PISMENA_S_PODTRZITKY`.

Všechny symboly by měly mít prefix s krátkou (2 až 4 písmennou) verzí jmenného prostoru. To je dostatečně krátké pro snadné psaní, ale stále by to mělo být jedinečné.

Také názvy všech metody třídy by měly mít na začátku připojen název třídy.

Navíc by veřejné hlavičkové soubory měly být vkládány z podsložky, které pro ně fakticky vytvoří jmenný prostor. Například místo `#include <abc.h>` by měl projekt svým uživatelům umožnit použít `#include <namespace/abc.h>`.

Některé projekty připojují jmenný prostor k hlavičkovým souborům v rámci podsložky, například `#include <namespace/ns-abc.h>` namísto `#include <namespace/abc.h>`. Dochází tak ke zdvojení, ale ničemu to nevadí.

Například pro projekt s názvem „Walbottle“ by šel zvolit zkrácený název pro jmenný prostor „Wbl“. Když bude mít třídu „schema“ a třídu „writer“, instalovaly by se hlavičkové soubory:

$(includedir)/walbottle-$API_MAJOR/walbottle/schema.h

$(includedir)/walbottle-$API_MAJOR/walbottle/writer.h

(Použití $API_MAJOR výše je z důvodu možnosti souběžné instalace.)

Pro třídu schématu by měly být exportovány následující symboly (mimo jiné) a dodržet při tom zvyklosti pro GObject:

Struktura `WblSchema`

Struktura `WblSchemaClass`

Makro `WBL_TYPE_SCHEMA`

Makro `WBL_IS_SCHEMA`

Funkce `wbl_schema_get_type`

Funkce `wbl_schema_new`

Funkce `wbl_schema_load_from_data`