<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="parallel-installability" xml:lang="cs">

  <info>

    <link type="guide" xref="index#maintainer-guidelines"/>

    <credit type="author copyright">

      <name>Havoc Pennington</name>

      <email its:translate="no">hp@pobox.com</email>

      <years>2002</years>

           installability: http://ometer.com/parallel.html.

           Licence CC-BY-SA 3.0 confirmed by e-mail with him. -->

    </credit>

    <credit type="author copyright">

      <name>Philip Withnall</name>

      <email its:translate="no">philip.withnall@collabora.co.uk</email>

      <years>2015</years>

    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>Jak psát knihovny, aby v budoucnu šly instalovat souběžně různé verze</desc>

  </info>

  <title>Souběžná instalace</title>

  <synopsis>

    <title>Shrnutí</title>

    
Pokud mohou být dva balíčky nainstalovány souběžně, nesmí mít společné názvy souborů a lidé provádějící vývoj vůči balíčku vždy kompilují vůči očekávané verzi. Pro démony, pomocné programy a konfigurační soubory to platí úplně stejně, jako pro hlavičkové soubory a binární knihovny.

    <list>

      <item>
Zajistěte, aby všechny verze knihoven šly nainstalovat vedle sebe. (<link xref="#justification"/>)
</item>

      <item>
Všem souborům instalovaným knihovnou přidělte číslo verze. (<link xref="#solution"/>)
</item>

      <item>
Udržujte číslo verze balíčku oddělené od názvu souboru s knihovnou nebo čísla verze libtool. Je pak jasnější, která část čísla verze balíčku se mění s API. (<link xref="#version-numbers"/>)
</item>

      <item>
Nainstalujte hlavičkové soubory C do <file>$(includedir)/liblibrary-version/library/</file>. (<link xref="#header-files"/>)
</item>

      <item>
Nainstalujte spustitelné soubory knihovny do <file>$(libdir)/liblibrary-version.so.soname</file>. (<link xref="#libraries"/>)
</item>

      <item>
Nainstalujte soubory pkg-config do <file>$(libdir)/pkgconfig/library-version.pc</file>. (<link xref="#pkg-config"/>)
</item>

      <item>
U souborů s nastavením zajistěte zpětnou a dopřednou kompatibilitu nebo je instalujte do <file>$(sysconfdir)/knihovna-verze/</file>. (<link xref="#configuration-files"/>)
</item>

      <item>
Nastavte GETTEXT_PACKAGE na library-version. (<link xref="#gettext"/>)
</item>

      <item>
Do všech názvů rozhraní D-Bus, názvů služeb a cest k objektům zahrňte číslo verze. Například: org.domain.KnihovnaVerze.Rozhraní, org.domain.KnihovnaVerze a /org/domain/KnihovnaVerze/. (<link xref="#dbus"/>)
</item>

      <item>
Nainstalujte spustitelné soubory démonů do <file>$(libexecdir)/library-daemon-version</file>. (<link xref="#programs"/>)
</item>

      <item>
Spustitelné soubory pomůcek instalujte do <file>$(bindir)/knihovna-utility-verze</file> a symbolické odkazy do <file>$(bindir)/knihovna-utility</file>. (<link xref="#programs"/>)
</item>

    </list>

  </synopsis>

  <section id="justification">

    <title>Odůvodnění</title>

    
Všechny veřejné knihovny by měly být navržené tak, aby je šlo instalovat souběžně ve více verzích, kvůli jednoduššímu pozdějšímu porušení API po dobu existence knihovny. Pokud je knihovna používána více projekty a chcete porušit API, buď musí projekty naráz přejít na nové API, nebo některé z nich již nebude nadále možné nainstalovat souběžně s ostatními, protože závisí na konfliktní verzi této knihovny.

    
To komplikuje správu a žádat pro všech projektech, aby naráz přesly na novou verzi API je organizačně náročné a demoralizující, protože většina porušení API nepřinese mnoho nových funkcí, které by motivovaly k přechodu.

    
Řešením je zajistit, aby šly všechny verze knihoven nainstalovat naráz, takže staré i nové verze API budou nainstalované a aplikace zkompilované vůči nim souběžně, bez konfliktů. Vestavění podpory pro tento druh souběžné instalace je mnohem jednodušší udělat na začátku projektu, než to dělat zpětně.

    
Tím se odstraní problém „slepice nebo vejce“ při přechodu celé sady aplikací z jedné verze knihovny na novější a pro správce knihovny si tím velmi zjednoduší porušení API, takže mohou při vývoji mnohem rychleji reagovat na přání nových funkcí.

    
Jiným a rovněž platným řešením pro knihovny je, nikdy nenarušovat API — tímto se řídí libc.

  </section>

  <section id="solution">

    <title>Řešení</title>

    
Řešením problému v podstatě je přejmenovat knihovnu a ve většině případů je nejhezčím způsobem, jak to udělat, vložit do cesty ke každému instalovanému souboru číslo verze. Díky tomu může být naráz nainstalováno více verzí knihovny.

    
Kupříkladu řekněme, že knihovna Foo tradičně instaluje tyto soubory:

    <list>

      <item>
<file>/usr/include/foo.h</file>
</item>

      <item>
<file>/usr/include/foo-utils.h</file>
</item>

      <item>
<file>/usr/lib/libfoo.so</file>
</item>

      <item>
<file>/usr/lib/pkgconfig/foo.pc</file>
</item>

      <item>
<file>/usr/share/doc/foo/foo-manual.txt</file>
</item>

      <item>
<file>/usr/bin/foo-utility</file>
</item>

    </list>

    
Můžete změnit verzi 4 knihovny Foo, aby místo toho instalovala tyto soubory:

    <list>

      <item>
<file>/usr/include/foo-4/foo/foo.h</file>
</item>

      <item>
<file>/usr/include/foo-4/foo/utils.h</file>
</item>

      <item>
<file>/usr/lib/libfoo-4.so</file>
</item>

      <item>
<file>/usr/lib/pkgconfig/foo-4.pc</file>
</item>

      <item>
<file>/usr/share/doc/foo-4/foo-manual.txt</file>
</item>

      <item>
<file>/usr/bin/foo-utility-4</file>
</item>

    </list>

    
Pak by mohly být nainstalovány souběžně s verzí 5:

    <list>

      <item>
<file>/usr/include/foo-5/foo/foo.h</file>
</item>

      <item>
<file>/usr/include/foo-5/foo/utils.h</file>
</item>

      <item>
<file>/usr/lib/libfoo-5.so</file>
</item>

      <item>
<file>/usr/lib/pkgconfig/foo-5.pc</file>
</item>

      <item>
<file>/usr/share/doc/foo-5/foo-manual.txt</file>
</item>

      <item>
<file>/usr/bin/foo-utility-5</file>
</item>

    </list>

    
To je jednoduše podporováno pomocí <link href="http://www.freedesktop.org/wiki/Software/pkg-config/"><cmd>pkg-config</cmd></link>: <file>foo-4.pc</file> by přidal do cesty <file>/usr/include/foo-4</file> a do seznamu knihoven odkaz <file>libfoo-4.so</file>; <file>foo-5.pc</file> by přidal <file>/usr/include/foo-5</file> a <file>libfoo-5.so</file>.

  </section>

  <section id="version-numbers">

    <title>Čísla verzí</title>

    
Číslo verze které se zahrne do názvu souboru je veze ABI/API. Nemělo by jít o celé číslo verze balíčku, jen o část, která významěmně porušuje API. Pokud používáte pro číslování verzí projektu standartní schéma hlavní.vedlejší.setinkové, je verzí API typicky hlavní číslo verze.

    
Vedlejší vydání (typicky, když je přidáno API, ale není změněno nebo odebráno) a setinková vydání (typicky opravy chyb) neovlivňují <link xref="api-stability">zpětnou kompatibilitu API</link>, takže nevyžadují přesun všech souborů.

    
Příklady v následujícím oddíle předpokládají, že verze API a název souboru s knihovnou jsou exportovány z <file>configure.ac</file> pomocí následujícího kódu:

    <listing>

      <title>Číslování verzí API v Autoconf</title>

      <desc>Kód pro export verze API a názvu souboru s knihovnou z <file>configure.ac</file></desc>

      # Před vydáním by se měl upravit řetězec KNIHOVNA_LT_VERSION, který

# je ve formě a:r:v (aktuální:revize:věk). Postupujte podle následujících bodů:

#

#   1. Když od poslední aktualizace došlo ke změně zdrojového kódu knihovny

#      jako celku, zvyšte revizi („a:r:v“ se změní na „a:r+1:v“).

#   2. Když bylo od poslední aktualizace přidáno, odebráno nebo změněno

#      rozhraní, zvyšte aktuální a revizi nastavte na 0.

#   3. Když bylo od posledního veřejného vydání přidáno rozhraní, zvyšte věk.

#   4. Když bylo od posledního veřejného vydání odebráno nebo změněno 

#      rozhraní, nastavte věk na 0.

AC_SUBST([KNIHOVNA_LT_VERSION],[1:0:0])

AC_SUBST([KNIHOVNA_API_VERSION],[4])

    </listing>

  </section>

  <section id="header-files">

    <title>Hlavičkové soubory C</title>

    
Hlavičkové soubory by vždy měly být nainstalovány v podsložce s číslem verze, kterou požaduje přepínač <cmd>-I</cmd> pro kompilátor jazyka C. Například, když je hlavičkový soubor <file>foo.h</file> a aplikace udělá následující:

    #include <foo/foo.h>

    
pak by měly být nainstalovány tyto soubory:

    <list>

      <item>
<file>/usr/include/foo-4/foo/foo.h</file>
</item>

      <item>
<file>/usr/include/foo-5/foo/foo.h</file>
</item>

    </list>

    
Aplikace by měla kompilátoru jazyka C předat přepínač <cmd>-I/usr/include/foo-4</cmd> nebo <cmd>-I/usr/include/foo-5</cmd>. Jak již bylo několikrát řečeno, to vše vám může usnadnit <cmd>pkg-config</cmd>.

    
Všimněte si zvláštní podsložky <file>foo/</file>. Funguje jako jmenný prostor pro #include, aby se předešlo kolizi názvů s jinými knihovnami. Když například dvě různé knihovny nainstalují každá hlavičkový soubor s názvem <file>utils.h</file>, který se ve skutečnosti vloží, když použijete kód #include <utils.h>?

    
Existuje pokušení ponechat jeden z hlavičkových souborů mimo kteroukoliv podsložku:

    <list>

      <item>
<file>/usr/include/foo.h</file>
</item>

      <item>
<file>/usr/include/foo-5/foo.h</file>
</item>

    </list>

    
Problém je v tom, že uživatel určitě vždycky omylem použije nesprávnou hlavičku, protože <cmd>-I/usr/include</cmd> si při kompilaci vždy najde nějakou cestičku do příkazového řádku. Pokud to musíte udělat, minimálně do knihovny přidejte kontrolu, která při inicializaci knihovny objeví aplikaci používající nesprávný hlavičkový soubor.

    
Hlavičkové soubory s číslem verze mohou být instalovány z automake pomocí následujícího kódu:

    <listing>

      <title>Hlavičkové soubory v Automake</title>

      <desc>Kód pro instalaci hlavičkových souborů s číslem verze z <file>Makefile.am</file></desc>

      libraryincludedir = $(includedir)/liblibrary-@LIBRARY_API_VERSION@/library

library_headers = \

	liblibrary/example1.h \

	liblibrary/example2.h \

	$(NULL)

# The following headers are private, and shouldn't be installed:

private_headers = \

	liblibrary/example-private.h \

	$(NULL)

# The main header simply #includes all other public headers:

main_header = liblibrary/library.h

public_headers = \

	$(main_header) \

	$(library_headers) \

	$(NULL)

libraryinclude_HEADERS = $(public_headers)

    </listing>

    
Kromě správného číslování verzí by měla mít všechna API v instalovaných hlavičkových souborech <link xref="namespacing">správný jmenný prostor</link>.

  </section>

  <section id="libraries">

    <title>Knihovny</title>

    
Objektové soubory knihovny by měly mít názvy s číslem verze. Například:

    <list>

      <item>
<file>/usr/lib/libfoo-4.so</file>
</item>

      <item>
<file>/usr/lib/libfoo-5.so</file>
</item>

    </list>

    
To umožňuje aplikacím získat při kompilaci právě tu, kterou chtějí a zajistí to, že verze 4 a 5 nemají žádné soubory společné.

    
Knihovny s číslem verze mohou být sestaveny a nainstalovány z automake pomocí následujícího kódu:

    <listing>

      <title>Knihovny v Automake</title>

      <desc>Kód pro sestavení a instalaci knihoven s číslem verze z <file>Makefile.am</file></desc>

      lib_LTLIBRARIES = libknihovna/libknihovna-@KNIHOVNA_API_VERSION@.la

libknihovna_libknihovna_@KNIHOVNA_API_VERSION@_la_SOURCES = \

	$(private_headers) \

	$(knihovna_sources) \

	$(NULL)

libknihovna_libknihovna_@KNIHOVNA_API_VERSION@_la_CPPFLAGS = …

libknihovna_libknihovna_@KNIHOVNA_API_VERSION@_la_CFLAGS = …

libknihovna_libknihovna_@KNIHOVNA_API_VERSION@_la_LIBADD = …

libknihovna_libknihovna_@KNIHOVNA_API_VERSION@_la_LDFLAGS = \

	-version-info $(KNIHOVNA_LT_VERSION) \

	$(AM_LDFLAGS) \

	$(NULL)

    </listing>

    <section id="library-sonames">

      <title>Názvy souborů s knihovnami</title>

      
Názvy souborů s knihovnami (známé též jako soname nebo číslování verzí libtool) se zaměřují jen na problém linkování dříve přeložených aplikací za běhu. Neřeší záležitosti okolo kompilace aplikací, které požadují dřívější verzi, a ani nic jiného okolo knihoven.

      
Z toho důvodu byste ještě navíc měli používat pro knihovny názvy s číslováním verzi. Každá z těchto věcí cílí na jiný problém.

    </section>

  </section>

  <section id="pkg-config">

    <title>Soubory pkg-config</title>

    
Soubory pkg-config by měly mít názvy s číslem verze. Například:

    <list>

      <item>
<file>/usr/lib/pkgconfig/foo-4.pc</file>
</item>

      <item>
<file>/usr/lib/pkgconfig/foo-5.pc</file>
</item>

    </list>

    
Protože každý soubor pkg-config obsahuje informace o verzi názvu knihovny včetně cesty, měl by být kterýkoliv projekt, který závisí na knihovně, schopen se přepnout z jedné verze na jinou prostou změnou kontroly ve svém pkg-config z <file>neco-4</file> na <file>neco-5</file> (a provedením příslušného přechodu v API).

    
Soubory pkg-config s rozlišením verze mohou být instalovány z autoconf a automake pomocí následujícího kódu:

    <listing>

      <title>Soubory pkg-config v Autoconf a Automake</title>

      <desc>Kód pro instalaci souborů pkg-config s rozlišením verze z <file>configure.ac</file> a <file>Makefile.am</file></desc>

      AC_CONFIG_FILES([

libknihovna/knihovna-$KNIHOVNA_API_VERSION.pc:libknihovna/knihovna.pc.in

],[],

[KNIHOVNA_API_VERSION='$KNIHOVNA_API_VERSION'])

      # Všimněte si, že soubor s šablonou se nazývá library.pc.in, ale generuje se

# soubor .pc s číslem verze pomocí stejné magie, jako v AC_CONFIG_FILES.

pkgconfigdir = $(libdir)/pkgconfig

pkgconfig_DATA = libknihovna/knihovna-$(KNIHOVNA_API_VERSION).pc

DISTCLEANFILES += $(pkgconfig_DATA)

EXTRA_DIST += libknihovna/knihovna.pc.in

    </listing>

  </section>

  <section id="configuration-files">

    <title>Soubory s nastavením</title>

    
Z hlediska uživatele je nejlepším přístupem k souborům s nastavením udržovat formát <link xref="api-stability">dopředně i zpětně kompatibilní</link> (obě verze knihovny rozumí právě té stejné syntaxi a sémantice souboru s nastavením). Pak lze použít ten samý soubor s nastavením pro všechny verze knihovny a není potřeba žádné číslování verzí u souborů s nastavením.

    
Pokud to ale dodržet nejde, měly by být soubory s nastavením jednoduše přejmenovány a uživatel musí nastavit každou verzi knihovny zvlášť.

  </section>

  <section id="gettext">

    <title>Překlady pomocí Gettext</title>

    
Jestli používáte pro překlady gettext v kombinaci s autoconf a automake, je normální postup nainstalovat překlady do <file>/usr/share/locale/jazyk/LC_MESSAGES/balíček</file>. Údaj baliček musíte změnit na správný název. Podle zvyklostí používaných v GNOME se to celé vloží do <file>configure.ac</file>:

    GETTEXT_PACKAGE=foo-4

AC_SUBST([GETTEXT_PACKAGE])

AC_DEFINE_UNQUOTED([GETTEXT_PACKAGE],["$GETTEXT_PACKAGE"])

    
Pak použijte GETTEXT_PACKAGE jako název balíčku předaný do bindtextdomain(), textdomain() a dgettext().

  </section>

  <section id="dbus">

    <title>Rozhraní D-Bus</title>

    
Rozhraní D-Bus je další formou API a podobá se API v C s tím rozdílem, že rozlišení verze se neprovádí při kompilaci, ale za běhu. Číslování verzí rozhraní D-Bus se jinak od API v C nijak neliší: čísla verzí musí být zahrnuta v názvech rozhraní, názvech služeb a v cestách k objektům.

    
Například pro službu org.example.Foo vystavující rozhraní A a B na objektech Controller a Client, by verze 4 a 5 API pro D-Bus vypadala nějak takto:

    <list>

      <title>Názvy služeb</title>

      <item>
org.example.Foo4
</item>

      <item>
org.example.Foo5
</item>

    </list>

    <list>

      <title>Názvy rozhraní</title>

      <item>
org.example.Foo4.InterfaceA
</item>

      <item>
org.example.Foo4.InterfaceB
</item>

      <item>
org.example.Foo5.InterfaceA
</item>

      <item>
org.example.Foo5.InterfaceB
</item>

    </list>

    <list>

      <title>Cesty k objektům</title>

      <item>
/org/example/Foo4/Controller
</item>

      <item>
/org/example/Foo4/Client
</item>

      <item>
/org/example/Foo5/Controller
</item>

      <item>
/org/example/Foo5/Client
</item>

    </list>

  </section>

  <section id="programs">

    <title>Programy, démoni a pomůcky</title>

    
Grafické aplikace obecně nepotřebují být nainstalované ve více verzích, protože na nich nezávisí další moduly. Démoni a pomocné programy ale spolupracují s dalšími částmi systému, a tak číslování verzí v názvech potřebují.

    
Mějme démona a pomocný program:

    <list>

      <item>
<file>/usr/libexec/foo-daemon</file>
</item>

      <item>
<file>/usr/bin/foo-lookup-utility</file>
</item>

    </list>

    
Číslo verze pak mohou mít přidělené jako:

    <list>

      <item>
<file>/usr/libexec/foo-daemon-4</file>
</item>

      <item>
<file>/usr/bin/foo-lookup-utility-4</file>
</item>

    </list>

    
Můžete nainstalovat symbolický odkaz z <file>/usr/bin/foo-lookup-utility</file> na doporučovanou verzi kopie pomocného programu, aby se pohodlněji používal uživatelům. 

  </section>

</page>