Váš první vlastní recept: program, který v knihovně chybí, jako balíček QTS

Knihovna receptů App Builder sestavuje dlouhý seznam programů. Když tam váš program chybí, může mít projekt vlastní recept: dva soubory ve složce recipes/ projektu, ve formátu knihovny. Návod z programu cmatrix 2.0 udělá balíček QTS pro NASy x86_64 a 64bitové NASy ARM. cmatrix je malý terminálový program, který potřebuje ncurses z knihovny.

1. ProjektPackage from source
2. Receptrecipe.json, build.sh
3. Kontrolalint v editoru
4. Sestavenídvě aplikace, dva procesory
5. Balíčekmake qpkg

Obrázky pocházejí z panelu a z editoru Bucket & Code Server IDE; každý krok je na nich proveden tak, jak ho popisuje tento návod. Datovou složkou je /share/ZFS530_DATA/BucketVS.

01Vytvořte projekt

Na stránce Projects se New project nejprve zeptá na šablonu. Vyberte Package from source: balíček QTS s programy, které kompilujete ze zdrojů s vlastními recepty, pro x86_64 a arm64.

Pojmenujte ho cmatrix. Název projektu se stane názvem balíčku. V malých písmenech a bez znaků, které název receptu nesmí obsahovat, se stane i názvem startovního receptu a obou aplikací projektu. Krok Service určuje, co balíček dělá, když běží. Volba Command-line tool, která je při otevření kroku už zvolená, vytvoří v /usr/bin odkaz na bin/cmatrix balíčku, dokud je balíček spuštěný. Složka projektu pak obsahuje:

Makefile sestavuje dvě aplikace: <name> pro procesor tohoto NASu a <name>-arm64 pro 64bitové NASy ARM; na NASu x86_64 jde o křížové sestavení. Obě se sestavují v prostředí Ubuntu 24.04 builder a linkují se staticky; když toto prostředí chybí, vytvoří ho Create this environment na stránce Toolchains. Build right after creating je u této šablony vypnuté: startovní recept uvádí zástupný zdroj se sha256 z 64 nul, takže sestavení selže, dokud recept neuvede váš program.

02Startovní recept

Open in editor v zobrazení projektu otevře složku projektu v editoru. recipe.json říká, co sestavit; build.sh říká jak.

build.sh definuje tři fáze a každá běží v rozbaleném zdroji. Fáze startovního receptu jsou pro CMake a jeho komentáře u každé uvádějí podobu pro autoconf a Meson:

do_configure() {
  # an autoconf source: configure_std; meson: meson_std. In a static app CMake ends the link line with -Wl,-Bdynamic
  # after a library it found as a file (lib<name>.a), and the link then asks for a shared libc;
  # CMAKE_LINK_SEARCH_END_STATIC keeps the line static to its end (D312)
  if [ "$STATIC" = 1 ]; then cmake_std -DCMAKE_LINK_SEARCH_END_STATIC=ON; else cmake_std; fi
}
do_build() {
  cmake --build _build -j"$JOBS" # autoconf: make_j; meson: meson compile -C _build
}
do_install() {
  cmake --install _build # autoconf: make install; meson: meson install -C _build
}

cmake_std, configure_std a meson_std předají prefix aplikace, režim linkování a u aplikace pro ARM i cíl křížového sestavení, takže stejný soubor slouží oběma aplikacím.

03Zdroj vašeho programu

Vezměte adresu archivu vydání a nechte terminál editoru spočítat jeho sha256:

curl -fsSL https://github.com/abishekvashok/cmatrix/archive/refs/tags/v2.0.tar.gz | sha256sum
ad93ba39acd383696ab6a9ebbed1259ecf2d3cf9f49d6b97038c66f80749e99a  -

cmatrix se sestavuje pomocí CMake a kreslí pomocí ncurses, kterou knihovna obsahuje. Jeho skript CMake najde ncurses jako soubor, libncurses.a, a ve statické aplikaci CMake za ním ukončí řádek linkování přepínačem -Wl,-Bdynamic, takže linkování by požádalo o sdílenou libc a zastavilo se. do_configure startovního receptu udrží řádek statický až do konce, takže build.sh zůstává tak, jak je:

do_configure() {
  if [ "$STATIC" = 1 ]; then cmake_std -DCMAKE_LINK_SEARCH_END_STATIC=ON; else cmake_std; fi
}

V recipe.json se kontrolou stane bin/cmatrix -V, tedy volba, která vypíše verzi cmatrix 2.0 (na --version program odpoví textem nápovědy):

{
  "name": "cmatrix",
  "version": "2.0",
  "summary": "cmatrix: the falling characters of The Matrix in a terminal",
  "category": "tool",
  "license": "GPL-3.0-or-later",
  "homepage": "https://github.com/abishekvashok/cmatrix",
  "source": {
    "url": "https://github.com/abishekvashok/cmatrix/archive/refs/tags/v2.0.tar.gz",
    "sha256": "ad93ba39acd383696ab6a9ebbed1259ecf2d3cf9f49d6b97038c66f80749e99a"
  },
  "deps": ["ncurses"],
  "env_packages": [],
  "static": true,
  "nss": false,
  "check": "bin/cmatrix -V"
}

• Složka receptu obsahuje recipe.json, build.sh a soubor vendor, který může recipe.json uvádět, a nic jiného. Záplata patří do build.sh jako here-document.
• recipes.txt už uvádí startovní recept; recepty z knihovny, na kterých závisí, se do sestavení přidají ve svém pořadí.

04Zkontrolujte ho

Každé uložení souboru receptu zkontroluje recepty projektu a nálezy vypíše v zobrazení Problems, každý u příslušného souboru a řádku. Kontrola čte recipe.json a build.sh rozebere pomocí bash -n; recept nikdy nespouští. Takovým nálezem je 64 nul startovního receptu: varování na řádku sha256, dokud tam není skutečný součet.

Stejná kontrola běží v terminálu i v úloze CI:

make lint                  # bvs recipe lint . (the project folder)
bvs recipe lint --json .   # the findings as JSON, for a CI step

Karta Recipes v zobrazení projektu vypisuje recepty projektu tak, jak je berou jeho aplikace, každý s výsledkem kontroly lint a s nálezy. Kliknutí na řádek otevře složku receptu v editoru a nabídka řádku zkopíruje příkaz lint.

05Sestavte obě aplikace

Build v zobrazení projektu spustí Makefile projektu: vytvoří obě aplikace, pokud chybějí, a sestaví je jednu po druhé. Stránka každé aplikace na stránce Apps uvádí projekt, ze kterého pocházejí její recepty, a protokol sestavení uvádí recepty v pořadí, v jakém se sestavují, ncurses jako první.

• Sestavení načte recepty projektu jednou, při svém startu. Soubor uložený později čeká na další sestavení.
• Recept projektu se stejným názvem jako recept z knihovny nahradí tento recept jen v aplikacích tohoto projektu a protokol sestavení to uvede.
• Po posledním receptu se kontrola každého receptu spustí znovu nad hotovým prefixem: u tohoto receptu bin/cmatrix -V. Na NASu x86_64 je aplikace pro ARM křížové sestavení a její kontroly běží jen tam, kde je zaregistrován qemu-user; bez něj je sestavení zapíše jako nespuštěné.

06Zabalte a nainstalujte

licenses.txt určuje, co obsahuje share/licenses/ balíčku: jeden řádek na každý recept, který balíček obsahuje, s jeho licencí a soubory licence v jeho zdrojovém archivu. Startovní řádek uvádí zástupnou hodnotu. cmatrix potřebuje dva řádky, protože je do něj slinkována ncurses:

cmatrix GPL-3.0-or-later COPYING
ncurses X11 COPYING

make qpkg v terminálu editoru zabalí pomocí QDK ze stránky Toolchains nejnovější úspěšné sestavení každé aplikace do balíčku, jeden soubor na architekturu, a aplikaci, která žádné nemá, vynechá. Dynamicky linkovaná aplikace se odmítne: její programy by hledaly své knihovny v prefixu aplikace, který balíček nevytváří.

make qpkg

Balíčky skončí v build/qpkg/build/ a jsou pojmenované podle QPKG_NAME a QPKG_VER z qpkg.cfg: cmatrix_0.1.0_x86_64.qpkg a cmatrix_0.1.0_arm_64.qpkg. Každý obsahuje bin/, sbin/, share/ (bez man, doc a info) a etc/ aplikace: zde cmatrix a to, co tam nainstalovala ncurses, její nástroje a její databázi terminálů. KEEP na začátku scripts/make-qpkg.sh uvádí cesty, které má balíček obsahovat místo toho, například bin/cmatrix share/terminfo.

Se soubory pro podepisování kódu v qpkg/ vedle qpkg.cfg nebo ve složce, kterou uvádí QPKG_CERT_DIR, je balíček podepsaný a Test deploy v zobrazení projektu (pro správce) ho nainstaluje na tento NAS. Vlastní App Center ukazuje podepisování a publikování podrobněji. Transmission od nuly sleduje projekt Package from source s pěti recepty od začátku do konce: od NASu, na kterém není nic nastavené, až po podepsaný balíček, který je nainstalovaný a odpovídá v prohlížeči.

07Druhý recept

Bucket: New recipe přidá recept podle stejného startovního receptu. Spusťte ho z palety příkazů (Ctrl+Shift+P), když je otevřený soubor projektu, nebo klikněte pravým tlačítkem na složku recipes či na složku receptu v Exploreru. Zeptá se na název (malá písmena, číslice a + . _ -), zapíše recipe.json a build.sh, otevře recipe.json a zkontroluje projekt.

• Nový název zapište do recipes.txt pro aplikace vytvořené od této chvíle. Dříve vytvořená aplikace si ponechá svůj seznam: recept do ní přidá Change na její stránce.
• Recept, jehož sestavení potřebuje balíčky npm, Go nebo Cargo, je uvádí v souboru vendor. Tento seznam zapisují npm-vendor.py, go-vendor.py a cargo-vendor.py v /usr/bin/bucketvs/share/bucketvs/tools/; potřebují běhové prostředí Python ze stránky Toolchains.
• Recepty projektu běží v sestavovacím prostředí jako root, stejně jako recepty knihovny, a může je psát a sestavovat kterýkoli vývojář. Uživatel s rolí viewer vidí názvy receptů aplikace v jejím protokolu sestavení, soubory receptů nikdy.
• Recept projektu zůstává ve svém projektu. Do knihovny receptů a do podepsaného katalogu, který dostává každý NAS, se dostane jen změnou samotného Bucket & Code Server IDE, která prošla revizí.