PaganOS Recipes

Receptury pakietów dla PaganOS. Każdy plik PAGBUILD.yaml definiuje jak zbudować pojedynczy pakiet.

Struktura

recipes/
├── core/       # pakiety bazowe (binutils, gcc, glibc, ...)
├── drivers/    # sterowniki (libinput, mesa, ...)
├── net/        # sieć (curl, wget, NetworkManager, ...)
├── gui/        # pakiety GUI (gtk, qt, xfce, ...)
├── utils/      # narzędzia (bubblewrap, ripgrep, ...)
└── boot/       # bootloader (grub)

Format PAGBUILD.yaml

pkgname: acl
pkgver: '2.4.0'
pkgrel: 1
pkgdesc: Commands for Manipulating POSIX Access Control Lists.
url: http://savannah.nongnu.org/projects/acl
arch: x86_64
license:
- GPL-2.0-only
depends:
- attr
makedepends:
- gcc
source:
- http://download.savannah.gnu.org/releases/${pkgname}/${pkgname}-${pkgver}.tar.gz
sha256sums:
- SKIP
build: |
  cd "${pkgname}-${pkgver}"
  ./configure --prefix=/usr
  make -j$(nproc)
package: |
  cd "${pkgname}-${pkgver}"
  make DESTDIR="${PKGDIR}" install

Zmienne dostępne w fazach build/package

• ${PKGDIR} — katalog DESTDIR (instalacja pakietu)
• ${pkgname}, ${pkgver}, ${pkgrel} — podstawiane też w adresach source:

Model pakietu (jak Arch/Debian — bez footprintów)

Receptura nie deklaruje listy plików. Faza package: instaluje wszystko do ${PKGDIR} (DESTDIR) i z tego katalogu pagbuild tworzy jeden pakiet — dokładnie jak PKGBUILD w Archu czy reguły install w Debianie. Lista plików nie jest danymi wejściowymi, tylko pochodną pakietu: pag wylicza SHA256 dla każdego pliku przy instalacji i zapisuje je w /var/lib/pag/files.db (rola, którą w Debianie pełni md5sums/.list, a w Archu .MTREE).

Nie używamy już pól footprint, footprint_devel, footprint_man, footprint_<lang> — to balast z formatu cards/NuTyX, którego pagbuild nigdy nie czytał. Podpakiety deweloperskie/dokumentacyjne/językowe są scalane z pakietem głównym (ich pliki i tak trafiają do DESTDIR). Do usuwania tych pól z istniejących receptur służy strip-recipes-footprints.py.

Pakiet wyjściowy

pagbuild buduje pakiety .pag (tar.xz z metadata.json + data.tar.xz), gotowe do instalacji przez pag install plik.pag. W repo trzymamy wyłącznie aktualną wersję każdego pakietu — starsze są usuwane przez pagsync.

Pakiet wydania (pagan-release) — wersja systemu przez repo

recipes/core/pagan-release to pakiet wydania („os-info”). Jego pkgver JEST wersją systemu, a depends opisuje, co to wydanie ma zawierać.

Dlaczego tak, a nie „wersja wpisana w obraz”:

• pliki /etc/os-release i /etc/pagan-release należą do PAKIETU, więc pag verify je obejmuje, a pag upgrade podmienia je przy nowszej wersji (z ochroną .pacnew, jeśli użytkownik je zmienił),
• w obrazie pakiet jest instalowany od razu, więc pag base register zapamiętuje go z wersją obrazu,
• provides: pagan-system=<wersja> pozwala innym pakietom wymagać pagan-system>=1.0.0 bez wiązania się z nazwą pakietu wydania,
• klucze dodatkowe codename: i desktop: (pagbuild je ignoruje) czyta build-pagan.sh — jedno miejsce z prawdą o kodename i środowisku.

Nowe wydanie — kolejność

1. Podnieś pkgver (i ewentualnie codename) w recipes/core/pagan-release/PAGBUILD.yaml; dopisz nowe pozycje w depends, jeśli wydanie ma dołożyć tapety/programy.
2. Podnieś PAGAN_VERSION w build-pagan.sh (builder ostrzeże w fazie weryfikacji obrazu, jeśli te dwie wartości się rozjadą).
3. pagbuild pagan-release → podpis → pagsync --gen-repo (albo GUI-Build).
4. Na maszynie użytkownika: sudo pag upgrade → nowa wersja systemu.

Uwagi

• depends muszą istnieć w repozytorium. pagan-wallpapers buduje sam builder (tapety leżą w branding/, do którego repo receptur nie ma dostępu), więc jego .pag (z ISO/packages/ po buildzie) wysyła się do repozytorium razem z pagan-release.
• Hooki: katalog hooks/ w .pag obsługuje pre-install, post-install, pre-remove, post-remove (API PKG_HOOK_API, PAG_NO_HOOKS=1 wyłącza, PAG_HOOK_TIMEOUT ogranicza czas). pagan-release używa post-install do odświeżenia baz pulpitu/ikon po dodaniu programów w wydaniu.

Receptury z własną konfiguracją (pagan-xfce-panel-layout)

Nie każdy pakiet jest kompilowany – niektóre wnoszą samą konfigurację. Wzorzec: pliki leżą w katalogu receptury i są wymienione w source: (pagbuild kopiuje je do katalogu budowy, więc w build: są dostępne po nazwie, bez ścieżek).

Przykład: recipes/gui/pagan-xfce-panel-layout wnosi domyślny układ panelu XFCE (/etc/xdg/xfce4/panel/default.xml) oraz skrypty widgetów genmon (/usr/libexec/pagan/panel/: CPU, RAM, sieć, bateria).

Jedno źródło prawdy dla repo i ISO

Układ panelu generuje gen-panel-xml.sh z tej samej receptury, której używa build-pagan.sh – nie ma drugiej kopii definicji układu do rozjechania:

• tutaj (pagbuild) generator jest wołany bez flag, bo depends gwarantuje obecność wtyczek (xfce4-panel, xfce4-whiskermenu-plugin, xfce4-genmon-plugin, xfce4-clipman-plugin),
• build-pagan.sh buduje te wtyczki „best-effort”, więc sam wykrywa braki w rootfs i przekazuje je flagami (--no-whiskermenu, --no-genmon, --no-clipman) – panel nigdy nie wskazuje na niezainstalowany moduł.

Zmieniając układ panelu (kolejność wtyczek, widgety, ulubione w menu) edytuje się tylko gen-panel-xml.sh i podnosi pkgver w tej recepturze.

Budowanie lokalnie

pagbuild recipes/core/acl/PAGBUILD.yaml

Narzędzia

• migrate-recipes.py — konwertuje receptury cards (Pkgfile) na PAGBUILD.yaml (footprinty są celowo pomijane)
• strip-recipes-footprints.py — usuwa pola footprint* z istniejących receptur (idempotentne; --apply, aby zapisać, domyślnie dry-run)

Polityka forków

Fork-first w całym repo: ../../FORK-POLICY.md. Krótko: co możemy zrobić forkiem, robimy forkiem — źródła w repo, pakiet -pagan, lokalny tarball + wyliczony sha256 (build bez sieci) i adnotacja licencyjna o statusie forka (FORK.md + NOTICE).