apkg: nový nástroj pro automatizaci upstream balení

Autor: Pixabay
Vítejte v historicky prvním článku o novém nástroji apkg, který vznikl v Laboratořích CZ.NIC, aby vývojářům usnadnil tvorbu softwarových balíků pro různá (nejen) linuxová distra přímo ze zdrojů.

Začnu úvodem o tom, proč svět nástroj jako apkg potřebuje a proč by vás to mohlo zajímat, pokud vyvíjíte software. V druhé půlce článku pak naleznete ukázku použití v praxi.

V textu hojně odkazuji na relevantní sekce oficiální dokumentace (v angličtině), nestyďte se tam nahlédnout v případě nejasností.

Pojmy

Píši o problematice balení poprvé v češtině, takže je na místě definice klíčových pojmů:

  • distribuce software – proces doručování softwaru k uživatelům,
  • distro – konkrétní množina softwaru k distribuci (např. Debian, Arch, Fedora, …),
  • balík (package) – archiv softwaru v distribučním formátu,
  • balič (packager) – osoba, která vytváří a spravuje balíky,
  • správce balíků (package manager) – nástroj pro správu balíků (např <tt>apt</tt>, <tt>dnf</tt>, <tt>pacman</tt>, …),
  • upstream – původní vývojáři softwaru.

Formáty balíků

Mezi stovkami existujících dister otevřeného softwaru existuje široká škála formátů balíků a také nástrojů pro jejich správu. Z mé zkušenosti jsou v divočině současně nejrozšířenější a nejpoptávanější balíky pro:

  • Debian a příbuzné: Ubuntu, Mint, MX, …,
  • Fedora a příbuzné: CentOS, Rocky, RHEL, SUSE, …,
  • Arch a příbuzné: Manjaro, Garuda, …

Sehnat balík v podporovaném formátu však ještě neznamená, že bude na systému fungovat. Závislosti balíků jsou obvykle generovány pro konkrétní vydání konkrétního distra a tedy není zaručena ani kompatibilita mezi různými verzemi stejného distra, natož mezi různými distry a jejich verzemi.

Distribuční balíky

Distribuce softwaru je komplexní problém a možná i proto je ve světě otevřeného software zvykem delegovat ji na specializované baliče. Každé linuxové distro má jinou politiku, procesy, zvyklosti a nástroje a z nich vyplývající zážitek pro své přispěvatele a uživatele.

Univerzální je však oddělení vývoje softwaru od jeho distribuce/balení. Zdrojové soubory pro tvorbu distribučních balíků žijí odděleně od zdrojů projektu. Práce vývojářů obvykle končí s vydáním nové verze a o tvorbu balíků se starají neopěvovaní hrdinové komunit jednotlivých dister.

Tento distribuovaný komunitní systém má své výhody i nevýhody. Zřejmou výhodou je efektivní dělba práce – vývojáři nemusí připravovat balíky pro stovky různých systémů přičemž každý z nich má svá specifika a temná zákoutí, ve kterých zkušený balič už umí chodit, ale neznalý vývojář je odsouzen k mnoha hodinám zbytečného utrpení. Pro uživatele je nejjednodušší získat software z oficiálních distribučních repozitářů a je zaručena určitá míra kompatibility s ostatními balíky v rámci distra.

Mezi nevýhody patří ztráta kontroly nad celým aspektem distribuce softwaru. Konzervativní distra jako Debian stable mají striktní pravidla, která omezují možnosti aktualizace balíků na novější verze. To může být problematické pro projekty s velkou kadencí vydání nebo pro projekty závisející na nových verzích závislostí, které ještě nejsou dostupné.

Různé politiky dister mohou vést k nekonzistencím mezi balíky stejného projektu napříč distry, například na Debianu je zvykem služby v balíku standardně povolit, na Fedoře jsou obvykle zakázané.

Nezávislí baliči obvykle nemají tak hlubokou znalost baleného softwaru jako vývojáři, což může vést k suboptimálním balíkům a chování v rozporu se záměry upstreamu.

Dle mého názoru také často dochází k nezdravému oddělení vývojářů od reálných zážitků uživatelů s jejich softwaru. V ideálním případě funguje komunikace mezi baliči a vývojáři směrem k lepšímu uživatelskému zážitku, ale to nelze zaručit, takže často žijí balíky svým vlastním životem a nebo naopak nežijí vůbec.

Upstream balíky

Jak jsem nastínil výše, existuje mnoho dobrých důvodů, proč nedelegovat veškeré balení na distro baliče a místo toho ho zahrnout do upstream vývojoveho procesu.

Upstream balíky mohou posloužit uživatelům na distrech, kde nejsou oficiální balíky dostupné nebo jsou ve starých verzích. Tvorba a instalace balíků na různých systémech může být zahrnuta v CI projektu, což umožní odchytit problémy před vydáním. Vývojáři mají plnou kontrolu nad upstream balíky a jejich repozitáři.

U nových projektů dává smysl začít upstream balíky a postupně je dostat do dister, což může trvat delší dobu. U starších projektů v distrech jsou zase upstream balíky způsob, jak poskytnout uživatelům nejnovější verze nezávisle na politikách a cyklech jednotlivých dister.

Na rozdíl od zdrojových kódů distro balíků, které bydlí v oddělených repozitářích, nic nebrání zahrnutí zdrojů upstream balíku přímo do zdrojového kódu projektu. Neexistuje však jednotný standard ani adekvátní nástroje, a tak to každý projekt řeší po svém.

V divočině můžeme vidět zdroje balíků různě rozmístěné v projektech, často v adresářích jako <tt>debian/</tt> či <tt>rpm/</tt> a obvykle doplněné kontroverzními skripty pro sestavení balíku. Zážitek neznalé osoby s tímto chaosem může být až traumatický.

apkg 📦

apkg vzniklo jako chybějící dílek skládačky upstream balení. Cílem je schopnost postavit kdykoliv balíky projektu pro konkrétní distro přímo ze zdrojů jedním příkazem.

<tt>apkg</tt> zavádí jednoduché konvence ohledně umístění zdrojů balíků v rámci projektu a poskytuje jednotné minimální rozhraní k balícím nástrojům podporovaných dister. Ve výsledku pak stačí ve zdrojích projektu zavolat <tt>apkg build</tt> a výsledkem jsou balíky projektu pro detekovaný systém.

Zvolené konvence jsou souborem dobrých zvyklostí z balící praxe spojených dohromady s cílem automatizovaného a konzistentního procesu tvorby upstream balíků. Zásadní vliv měly projekty Knot Resolver a Knot DNS, které už před nasazením <tt>apkg</tt> stavěly upstream balíky přímo ze zdrojů pro širokou škálu dister.

<tt>apkg</tt> lze plnohodnotně používat jak interaktivně z terminálu, tak v rámci CI/CD systémů, ať už jako příkaz ve skriptech nebo jako python modul. apkg CI průběžně testuje funkčnost <tt>apkg</tt> na 5 různých projektech napříč 11 distry.

Důležité: <tt>apkg</tt> negeneruje zdrojové soubory balíků ani je automaticky nemodifikuje – tato práce je stejně jako v případě distro balíků zodpovědností baličů.

Více se můžete dočíst v dokumentaci, je čas se podívat, jak to vypadá v praxi.

apkg na vlastní kůži

Pro demonstraci použiji projekt libyang, protože má málo závislostí a kompiluje se rychle, ale proces je univerzální a můžete ho aplikovat na kterýkoliv z projektů, které používají <tt>apkg</tt>.

Pokud si chcete <tt>apkg</tt> vyzkoušet, nastartuje systém založený na Debianu (<tt>.deb</tt> balíky) nebo Fedoře (<tt>.rpm</tt> balíky). Můžete použít váš vývojový systém, pokud vám nevadí balící závislosti a nebo virtuální stroj či kontejner dle libosti.

Instalace apkg

<tt>apkg</tt> je momentálně zhruba po roce vývoje v BETA fázi, kdy ho první projekty používají v produkci, ale vývoj je stále svižný, takže než dospěje, je oficiální cestou instalace PyPI:

pip3 install apkg

Více možností instalace naleznete v dokumentaci.

Příprava systému

Jednorázově nainstalujeme balící závislosti:

[debian-11]$ apkg system-setup

I system setup for packaging
I target distro: debian 11
# sudo -E apt-get install -y devscripts
✓ system ready for packaging

Zdroje projektu

Seženeme si zdrojové kódy projektu a dostavíme se do jeho kořenového adresáře:

git clone https://github.com/CESNET/libyang
cd libyang

Všechny další <tt>apkg</tt> příkazy spouštíme v kořenovém adresáři projektu.

Průzkum terénu – apkg status

Je čas zjistit, co si o tom myslí <tt>apkg</tt>:

[debian-11]$ apkg status

project name:            libyang
project base path:       /mnt/src/libyang
project VCS:             git
project config:          distro/config/apkg.toml (exists)
package templates path:  distro/pkg (exists)
package templates:
    deb: deb pkgstyle default: ubuntu | debian | linuxmint
    rpm: rpm pkgstyle default: fedora | centos | rocky | rhel | opensuse

current distro: debian 11 / Debian GNU/Linux 11 (bullseye)
    package style: deb
    package template: distro/pkg/deb

Ve výstupu vidíme:

Když spustíme <tt>apkg status</tt> ve stejném adresáři na Fedora 34 systému, vidíme změnu v detekovném distru a z toho vyplývající jiný zvolený balící styl a šablonu:

[fedora-34]$ apkg status

...

current distro: fedora 34 / Fedora 34
    package style: rpm
    package template: distro/pkg/rpm

<tt>apkg</tt> podporuje také Arch, ale <tt>libyang</tt> pro něj neobsahuje balící šablonu (obvykle <tt>distro/pkg/arch</tt>):

[arch]$ apkg status

...

current distro: arch / Arch Linux
    package style: unsupported
    package template: unsupported

Vstupní adresář – distro

<tt>distro/</tt> adresář je konvencí vstupní adresář <tt>apkg</tt>, do kterého nikdy nezasahuje.

$ tree distro

distro
├── config
│   └── apkg.toml
├── pkg
│   ├── deb
│   │   ├── changelog
│   │   ├── control
│   │   ├── rules
│   │   └── [a další debian balící soubory...]
│   └── rpm
│       └── libyang.spec
└── scripts
    ├── make-archive.sh
    └── upstream-version.sh

<tt>distro/config</tt> adresář obsahuje jediný konfigurační soubor
<tt>apkg.toml</tt>, který odkazuje na skripty v <tt>distro/scripts</tt>:

  • <tt>make-archive.sh</tt> pro vytvoření archivu projektu z aktualních zdrojů
  • <tt>upstream-version.sh</tt> pro zjištění aktuální upstream verze projektu

Tyto skripty jsou volitelné a mohou bydlet i mimo <tt>distro</tt> adresář.

Každý adresář v <tt>distro/pkg</tt> je konvencí šablona balíku – zdrojové soubory balíku pro určitý balící styl šablonované pomocí univerzálního jinja šablonovacího systému, který poskytuje extra flexibilitu potřebnou pro automatizaci.

Zdrojové soubory v šablonách jsou stejné jako ve zdrojích oficiálních distro balíků, jen s extra možností šablonování jako například náhrada <tt>{{ version }}</tt> aktuální verzí balíku atd.

<tt>distro/pkg/deb</tt> šablona obsahuje zdrojové soubory pro vytvoření balíku na Debianu a klonech.

<tt>distro/pkg/rpm</tt> šablona obsahuje zdrojové soubory pro vytvoření balíku na RPM systémech (Fedora a její klony).

Instalace balících závislostí

Bez dalšího otálení nainstalujeme závislosti pro sestavení balíku. Potřebujeme mít zprovozněné <tt>sudo</tt> a nebo být <tt>root</tt>:

[debian-11]$ apkg build-dep

I installing build deps
I target distro: debian 11
I build deps from template: distro/pkg/deb
I installing 4 build deps...
# sudo -E apt-get satisfy -y cmake debhelper (>= 10) libpcre2-dev (>= 10.21) pkg-config

To samé na Fedoře:

[fedora-34]$ apkg build-dep

I installing build deps
I target distro: fedora 34
I build deps from template: distro/pkg/rpm
I installing 4 build deps...
# sudo dnf install -y cmake gcc make pkgconfig(libpcre2-8) >= 10.21

Tento krok lze vykonat také v rámci příkazů <tt>build</tt> a <tt>install</tt> pomocí přepínače <tt>-b/--build-dep</tt> pro maximální pohodlí.

Závislosti lze také pouze vypsat bez instalace přepínačem <tt>-l/--list</tt> a zpracovat dle uvážení:

[debian-11]$ apkg build-dep --list

I listing build deps
I target distro: debian 11
I build deps from template: distro/pkg/deb
cmake
debhelper (>= 10)
libpcre2-dev (>= 10.21)
pkg-config

Sestavení balíků 📦

Konečně je čas sestavit balíky pomocí hlavního příkazu <tt>apkg build</tt>!

[debian-11] apkg build

I building packages
I target distro: debian 11
I creating dev source package
I creating dev archive
I running make_archive_script: distro/scripts/make-archive.sh
✓ made archive: pkg/archives/dev/libyang-2.0.97.tar.gz
I package style: deb
I package template: distro/pkg/deb
I building deb source package: libyang-2.0.97
✓ made source package: pkg/srcpkgs/debian-11/libyang2-2.0.97-1/libyang2_2.0.97-1.dsc
I unpacking source package for direct host build
I starting direct host build using dpkg-buildpackage
✓ built 6 packages in: pkg/pkgs/debian-11/libyang2_2.0.97-1

Stejný příkaz ve stejném adresáři na Fedoře:

[feodra-34] apkg build

I building packages
I target distro: fedora 34
I creating dev source package
I creating dev archive
✓ reuse cached archive: pkg/archives/dev/libyang-2.0.97.tar.gz
I package style: rpm
I package template: distro/pkg/rpm
I building .src.rpm using rpmbuild
✓ made source package: pkg/srcpkgs/fedora-34/libyang-2.0.97-1/libyang-2.0.97-1.fc34.src.rpm
I starting direct host .rpm build using rpmbuild
✓ built 6 packages in: pkg/pkgs/fedora-34/libyang-2.0.97-1.fc34

Zde si kromě změn kvůli jinému distru můžete všimnout odchylky v podobě:

✓ reuse cached archive: pkg/archives/dev/libyang-2.0.97.tar.gz

<tt>apkg</tt> zjistilo, že se stav projektu nezměnil od minula a není tedy třeba znova vyvářet zdrojový archiv, místo toho přepoužilo ten vytvořený v rámci předchozího buildu na Debianu.

Když spustíme stejný příkaz znova beze změn v projektu, <tt>apkg</tt> prostě přepoužije předchozí výstupy:

[feodra-34] apkg build

✓ reuse cached archive: pkg/archives/dev/libyang-2.0.97.tar.gz
✓ reuse cached source package: pkg/srcpkgs/fedora-34/libyang-2.0.97-1/libyang-2.0.97-1.fc34.src.rpm
✓ reuse 6 cached packages

Cache lze vypnout přepínačem <tt>--no-cache</tt>.

Výstupní adresář – pkg

Adresář <tt>pkg/</tt> je výstupní adresář <tt>apkg,</tt> který obsahuje veškerý výstup – archivy, zdrojové balíky, balíky a všechno mezi. Tento adresář můžete kdykoliv bez obav smazat.

$ tree pkg

pkg
├── archives
│   └── dev
│       └── libyang-2.0.97.tar.gz
├── build
│   ├── pkgs
│   │   ├── debian-11
│   │   │   └── libyang2_2.0.97-1
│   │   └── fedora-34
│   │       └── libyang-2.0.97-1.fc34
│   └── srcpkgs
│       ├── debian-11
│       │   └── libyang2-2.0.97-1
│       └── fedora-34
│           └── libyang-2.0.97-1
├── pkgs
│   ├── debian-11
│   │   └── libyang2_2.0.97-1
│   │       └── libyang*.deb
│   └── fedora-34
│       └── libyang-2.0.97-1.fc34
│           └── libyang*.rpm
└── srcpkgs
    ├── debian-11
    │   └── libyang2-2.0.97-1
    │       ├── libyang2_2.0.97-1.debian.tar.xz
    │       ├── libyang2_2.0.97-1.dsc
    │       └── libyang2_2.0.97.orig.tar.gz
    └── fedora-34
        └── libyang-2.0.97-1
            └── libyang-2.0.97-1.fc34.src.rpm

Více o struktuře výstupního adresáře se můžete dočíst v dokumentaci.

Instalace balíků

<tt>apkg</tt> umožňuje výsledné balíky nainstalovat, což se hodí zejména v rámci testování:

[debian-11]$ apkg install

I installing packages
✓ reuse cached archive: pkg/archives/dev/libyang-2.0.97.tar.gz
✓ reuse cached source package: pkg/srcpkgs/debian-11/libyang2-2.0.97-1/libyang2_2.0.97-1.dsc
✓ reuse 6 cached packages
# sudo -E apt-get install -y [seznam balíků k instalaci]
✓ installed 6 packages

<tt>apkg</tt> opět přepoužilo už postavené balíky. Kdyby nebyly dostupné, postavilo by je pomocí <tt>apkg build</tt>.

Hierarchie příkazů

Tím se dostáváme k hierarchii <tt>apkg</tt> příkazů (převzato z dokumentace):

                        apkg packaging workflow

 +------------------------------+    +------------------------------------+
 |                              |    |                                    |
 |     $ apkg make-archive      |    |     $ apkg get-archive [-v 1.2.3]  |
 |                              |    |                                    |
 |   in: current project state  | OR |   in: archive hosted online        |
 |                              |    |                                    |
 |  out: pkg/archives/dev/*.xz  |    |  out: pkg/archives/upstream/*.xz   |
 |                              |    |                                    |
 +---------------+--------------+    +----------------+-------------------+
                 |                                    |
                 |                                    |
                 |                                    |
                 v                                    v
      +----------+------------------------------------+-------------+
      |                                                             |
      |     $ apkg srcpkg                                           |
      |                                                             |
      |   in: distro/pkg/$TEMPLATE/  (package template)             |
      |       pkg/archives/*/*.xz    (archive)                      |
      |                                                             |
      |  out: pkg/srcpkgs/$DISTRO/$SRCPKG         (source package)  |
      |       pkg/build/srcpkgs/$DISTRO/$SRCPKG/  (build dir)       |
      |                                                             |
      +------------------------------+------------------------------+
                                     |
                                     |
                                     |
                                     v
      +------------------------------+------------------------------+
      |                                                             |
      |     $ apkg build                                            |
      |                                                             |
      |   in: pkg/srcpkgs/$DISTRO/$SRCPKG  (source package)         |
      |                                                             |
      |  out: pkg/pkgs/$DISTRO/$PKG        (package)                |
      |       pkg/build/pkgs/$DISTRO/$PKG  (build dir)              |
      |                                                             |
      +-------------------------------------------------------------+

Každý <tt>apkg</tt> příkaz, který generuje soubory, vypisuje na standardní výstup jeden výstupní soubor na řádek. Všechny příkazy, které očekávají vstupní soubory, podporují argument <tt>-F</tt>/<tt>--file-list</tt> pro specifikaci ze souboru včetně <tt>-</tt> pro standardní vstup.

Ve výsledku lze <tt>apkg</tt> příkazy zapojit za sebe. Když chybí vstupní soubory, <tt>apkg</tt> se pokusí chytře použít adekvátní příkaz pro jejich vytvoření.

Standardní chování <tt>apkg install</tt> lze explicitně rozepsat na jednotlivé příkazy:

apkg make-archive \                    # vytvoř archiv projektu
    | apkg srcpkg --archive -F - \     # vytvoř zdrojový balík
    | apkg build --srcpkg -F - \       # postav balíky
    | apkg install --custom-pkgs -F -  # nainstaluj balíky

Dejte nám zpětnou vazbu

<tt>apkg</tt> umí ještě další užitečné triky jako je stavba balíků z upstream archivů, ale pro dnešek se spokojíme s balíky přímo ze zdroje.

Pokud něco po cestě selhalo, zkuste přidat <tt>-L verbose</tt> a nebo <tt>-L debug</tt> hned za <tt>apkg</tt> pro podrobnější (a barevnější) výstup, např.

apkg -L debug build --build-dep

<tt>apkg</tt> existuje, aby zlepšilo život vývojářům, baličům, i uživatelům a zpětná vazba je klíčová pro jeho vývoj. Neváhejte otevřít Issue.

Nextcloud školení

Nechť vaše balíky přináší uživatelům radost. 📦

(Původně vyšlo na blogu CZ.NIC.)

Autor článku

Ve sdružení CZ.NIC se věnuje balíkům, tedy integraci software do (nejen) linuxových distribucí jako Debian/Ubuntu či Fedora/CentOS/RHEL.