Ihr erstes eigenes Rezept: ein Programm, das der Bibliothek fehlt, als QTS-Paket

Die Rezeptbibliothek des App Builders baut eine lange Liste von Programmen. Ist Ihres nicht darunter, kann ein Projekt ein eigenes Rezept mitbringen: zwei Dateien in seinem Ordner recipes/, im Format der Bibliothek. Diese Anleitung packt cmatrix 2.0, ein kleines Terminalprogramm, das ncurses aus der Bibliothek braucht, als QTS-Paket für Geräte mit x86_64 und mit ARM 64-Bit.

1. ProjektPaket aus dem Quellcode
2. Rezeptrecipe.json, build.sh
3. Prüfendie Prüfung im Editor
4. Bauenzwei Apps, zwei Prozessoren
5. Paketmake qpkg

Die Bilder stammen aus dem Panel und dem Editor von Bucket & Code Server IDE; jeder Schritt ist so ausgeführt, wie diese Anleitung ihn beschreibt. Der Datenordner ist /share/ZFS530_DATA/BucketVS.

01Projekt anlegen

Auf der Seite Projekte fragt Neues Projekt zuerst nach der Vorlage. Wählen Sie Paket aus dem Quellcode: ein QTS-Paket aus Programmen, die Sie mit eigenen Rezepten aus dem Quellcode kompilieren, für x86_64 und arm64.

Nennen Sie das Projekt cmatrix. Der Name des Projekts wird zum Namen des Pakets und, in Kleinbuchstaben und ohne die Zeichen, die ein Rezeptname nicht enthalten kann, zum Namen seines Starter-Rezepts und seiner beiden Apps. Der Schritt Dienst gibt an, was das Paket tut, während es läuft. Kommandozeilenwerkzeug ist bereits gewählt, wenn sich der Schritt öffnet. Es verlinkt bin/cmatrix des Pakets nach /usr/bin, solange das Paket gestartet ist. Der Ordner des Projekts enthält dann:

Das Makefile baut zwei Apps: <name> für den Prozessor dieses NAS und <name>-arm64 für Geräte mit ARM 64-Bit, auf einem x86_64-NAS ein Cross-Build. Beide bauen im Ubuntu-24.04-Builder und linken statisch; fehlt diese Umgebung, legt Diese Umgebung anlegen auf der Seite Toolchains sie an. Direkt nach dem Anlegen bauen ist bei dieser Vorlage aus: Das Starter-Rezept nennt eine Platzhalterquelle mit einer sha256 aus 64 Nullen, daher schlägt ein Build fehl, bis das Rezept Ihr Programm nennt.

02Das Starter-Rezept

Im Editor öffnen in der Projektansicht öffnet den Ordner des Projekts im Editor. recipe.json sagt, was gebaut wird; build.sh sagt, wie.

build.sh definiert drei Phasen, die jeweils im entpackten Quellcode laufen. Im Starter-Rezept sind es die Phasen für CMake; die Kommentare nennen jeweils die Form für autoconf und 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 und meson_std übergeben das Präfix der App, den Link-Modus und, bei einer ARM-App, das Cross-Ziel, sodass dieselbe Datei beiden Apps dient.

03Die Quelle Ihres Programms

Nehmen Sie die Adresse des Release-Archivs und lassen Sie das Terminal des Editors seine sha256 berechnen:

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

cmatrix baut mit CMake und zeichnet mit ncurses, das die Bibliothek enthält. Sein CMake-Skript findet ncurses als Datei, libncurses.a, und in einer statischen App beendet CMake die Linkzeile dahinter mit -Wl,-Bdynamic, sodass das Linken eine dynamische libc verlangen und abbrechen würde. Das do_configure des Starter-Rezepts hält die Zeile bis zu ihrem Ende statisch, deshalb braucht build.sh keine Änderung:

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

In recipe.json wird die Prüfung zu bin/cmatrix -V, der Option, die die Version von cmatrix 2.0 ausgibt (auf --version antwortet es mit seinem Hilfetext):

{
  "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"
}

• Ein Rezeptordner enthält recipe.json, build.sh und die Vendor-Datei, die recipe.json nennen kann, und sonst nichts. Ein Patch kommt als Here-Document in build.sh.
• recipes.txt nennt bereits das Starter-Rezept; die Rezepte der Bibliothek, von denen es abhängt, kommen in ihrer Reihenfolge zum Build hinzu.

04Prüfen

Jedes Mal, wenn Sie eine Datei eines Rezepts speichern, werden die Rezepte des Projekts geprüft, und die Befunde erscheinen in der Ansicht Probleme, jeder bei seiner Datei und Zeile. Die Prüfung liest recipe.json und parst build.sh mit bash -n; sie führt das Rezept nie aus. Die 64 Nullen des Starter-Rezepts sind ein solcher Befund, eine Warnung in der sha256-Zeile, bis dort die echte Summe steht.

Dieselbe Prüfung läuft im Terminal und in einem CI-Job:

make lint                  # bvs recipe lint . (der Ordner des Projekts)
bvs recipe lint --json .   # die Befunde als JSON, für einen CI-Schritt

Die Karte Rezepte der Projektansicht listet die Rezepte des Projekts so auf, wie seine Apps sie verwenden, jedes mit seinem Prüfergebnis und seinen Befunden. Ein Klick auf eine Zeile öffnet den Ordner des Rezepts im Editor, und das Menü der Zeile kopiert den Prüfbefehl.

05Die beiden Apps bauen

Bauen in der Projektansicht führt das Makefile des Projekts aus: Es legt die beiden Apps an, wenn sie fehlen, und baut sie nacheinander. Auf der Seite Apps zeigt jede App das Projekt, aus dem ihre Rezepte kommen, und das Protokoll des Builds nennt die Rezepte in ihrer Reihenfolge, ncurses zuerst.

• Ein Build liest die Rezepte des Projekts einmal, wenn er startet. Eine später gespeicherte Datei wartet auf den nächsten Build.
• Ein Projektrezept mit dem Namen eines Bibliotheksrezepts ersetzt dieses Rezept nur in den Apps dieses Projekts, und das Protokoll des Builds vermerkt das.
• Nach dem letzten Rezept läuft die Prüfung jedes Rezepts noch einmal im fertigen Präfix, bei diesem Rezept bin/cmatrix -V. Auf einem x86_64-NAS ist die ARM-App ein Cross-Build, und ihre Prüfungen laufen nur dort, wo qemu-user registriert ist; ohne qemu-user vermerkt der Build sie als nicht ausgeführt.

06Packen und installieren

licenses.txt gibt an, was share/licenses/ des Pakets enthält: eine Zeile pro Rezept, das das Paket enthält, mit seiner Lizenz und den Lizenzdateien in seinem Quellarchiv. Die Zeile des Starter-Rezepts nennt den Platzhalter. cmatrix braucht zwei Zeilen, weil ncurses hineingelinkt ist:

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

make qpkg im Terminal des Editors packt den neuesten erfolgreichen Build jeder App mit QDK von der Seite Toolchains in das Paket, eine Datei pro Architektur, und lässt eine App ohne einen solchen Build aus. Eine dynamisch gelinkte App wird abgelehnt: Ihre Programme würden ihre Bibliotheken im Präfix der App suchen, das das Paket nicht anlegt.

make qpkg

Die Pakete landen in build/qpkg/build/, benannt nach QPKG_NAME und QPKG_VER aus qpkg.cfg: cmatrix_0.1.0_x86_64.qpkg und cmatrix_0.1.0_arm_64.qpkg. Jedes enthält bin/, sbin/, share/ (ohne man, doc und info) und etc/ der App: hier cmatrix und das, was ncurses dort installiert hat, seine Werkzeuge und seine Terminaldatenbank. KEEP am Anfang von scripts/make-qpkg.sh nennt stattdessen die Pfade, die ein Paket enthalten soll, zum Beispiel bin/cmatrix share/terminfo.

Liegen die Dateien zum Signieren von Code in qpkg/ neben qpkg.cfg oder in einem Ordner, den QPKG_CERT_DIR nennt, wird das Paket signiert, und Testeinsatz in der Projektansicht (Admin) installiert es auf diesem NAS. Ihr eigenes App Center zeigt das Signieren und Veröffentlichen ausführlicher. Transmission von Grund auf begleitet ein Projekt vom Typ Paket aus dem Quellcode mit fünf Rezepten von Anfang bis Ende: von einem NAS, auf dem nichts eingerichtet ist, bis zum signierten Paket, das installiert ist und im Browser antwortet.

07Ein zweites Rezept

Bucket: New recipe fügt ein Rezept aus demselben Starter hinzu. Führen Sie es aus der Befehlspalette (Ctrl+Shift+P) aus, während eine Datei des Projekts geöffnet ist, oder klicken Sie im Explorer mit der rechten Maustaste auf den Ordner recipes oder den Ordner eines Rezepts. Es fragt nach dem Namen (Kleinbuchstaben, Ziffern und + . _ -), schreibt recipe.json und build.sh, öffnet recipe.json und prüft das Projekt.

• Tragen Sie den neuen Namen für Apps, die ab jetzt angelegt werden, in recipes.txt ein. Eine vorher angelegte App behält ihre Liste: Ändern auf ihrer Seite fügt das Rezept hinzu.
• Ein Rezept, dessen Build npm-, Go- oder Cargo-Pakete braucht, listet sie in einer Vendor-Datei. npm-vendor.py, go-vendor.py und cargo-vendor.py in /usr/bin/bucketvs/share/bucketvs/tools/ schreiben diese Liste; sie brauchen eine Python-Laufzeitumgebung von der Seite Toolchains.
• Projektrezepte laufen wie die der Bibliothek als root in der Builder-Umgebung, und jeder Developer kann sie schreiben und bauen. Ein Viewer sieht die Namen der Rezepte einer App in ihrem Build-Protokoll, nie die Rezeptdateien.
• Ein Projektrezept bleibt in seinem Projekt. In die Rezeptbibliothek und den signierten Katalog, den jedes NAS bezieht, gelangt es nur über eine geprüfte Änderung an Bucket & Code Server IDE selbst.