Ditt första egna recept: ett program som biblioteket saknar, som QTS-paket

Receptbiblioteket i App Builder bygger en lång rad program. När ditt inte finns bland dem kan ett projekt ha ett eget recept: två filer i dess mapp recipes/, i bibliotekets format. Den här guiden paketerar cmatrix 2.0, ett litet terminalprogram som behöver ncurses från biblioteket, som ett QTS-paket för x86_64-enheter och ARM 64-bitars enheter.

1. ProjektPaket från källkod
2. Receptrecipe.json, build.sh
3. Kontrolllint i redigeraren
4. Byggetvå appar, två processorer
5. Paketmake qpkg

Bilderna kommer från panelen och redigeraren i Bucket & Code Server IDE, med varje steg utfört så som den här guiden beskriver. Datamappen är /share/ZFS530_DATA/BucketVS.

01Skapa projektet

På sidan Projekt frågar Nytt projekt först efter mallen. Välj Paket från källkod: ett QTS-paket med program som du kompilerar från källkod med egna recept, för x86_64 och arm64.

Ge projektet namnet cmatrix. Projektets namn blir paketets namn. Skrivet med gemener och utan de tecken som ett receptnamn inte får innehålla blir det också namnet på startreceptet och på de två apparna. Steget Tjänst anger vad paketet gör medan det körs. Kommandoradsverktyg, som är valt när steget öppnas, länkar in paketets bin/cmatrix i /usr/bin medan paketet är startat. Projektets mapp innehåller sedan:

Projektets Makefile bygger två appar: <name> för den här NAS:ens processor och <name>-arm64 för ARM 64-bitars enheter, ett korsbygge på en x86_64-NAS. Båda byggs i Builder-miljön för Ubuntu 24.04 och länkas statiskt. Saknas den miljön skapar du den med Skapa den här miljön på sidan Verktygskedjor. Bygg direkt efter skapandet är av för den här mallen: startreceptet anger en platshållarkälla med en sha256 med 64 nollor, så ett bygge misslyckas tills receptet anger ditt program.

02Startreceptet

Öppna i redigeraren i projektvyn öppnar projektets mapp i redigeraren. recipe.json anger vad som ska byggas; build.sh anger hur.

build.sh definierar tre faser som var och en körs i den uppackade källkoden. Startreceptets faser är CMakes, och kommentarerna visar hur varje fas ser ut för autoconf och 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 och meson_std skickar med appens prefix, länkningssättet och, för en ARM-app, korsmålet, så att samma fil fungerar för båda apparna.

03Ditt programs källkod

Ta adressen till utgåvans arkiv och låt redigerarens terminal räkna ut dess sha256:

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

cmatrix byggs med CMake och ritar med ncurses, som finns i biblioteket. Dess CMake-skript hittar ncurses som en fil, libncurses.a, och i en statisk app avslutar CMake länkraden med -Wl,-Bdynamic efter den, så länkningen skulle begära en delad libc och stanna. Startreceptets do_configure håller raden statisk ända till slutet, så build.sh förblir som den är:

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

I recipe.json blir kontrollen bin/cmatrix -V, flaggan som skriver ut versionen av cmatrix 2.0 (på --version svarar programmet med sin hjälptext):

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

• En receptmapp innehåller recipe.json, build.sh och den vendor-fil som recipe.json kan ange, och inget annat. En patch läggs in i build.sh som ett here-dokument.
• recipes.txt anger redan startreceptet; de recept i biblioteket som det beror på läggs till i bygget i sin ordning.

04Kontrollera det

Varje gång en receptfil sparas kontrolleras projektets recept och fynden listas i vyn Problems, vart och ett vid sin fil och rad. Kontrollen läser recipe.json och tolkar build.sh med bash -n; den kör aldrig receptet. Startreceptets 64 nollor är ett sådant fynd, en varning på sha256-raden tills den riktiga summan står där.

Samma kontroll körs i terminalen och i ett CI-jobb:

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

Kortet Recept i projektvyn listar projektets recept så som apparna använder dem, vart och ett med sitt kontrollresultat och sina fynd. Ett klick på en rad öppnar receptets mapp i redigeraren, och radens meny kopierar kontrollkommandot.

05Bygg de två apparna

Bygg i projektvyn kör projektets Makefile: den skapar de två apparna när de saknas och bygger dem efter varandra. Varje apps sida på sidan Appar anger projektet som dess recept kommer från, och byggets logg anger varje recept i sin ordning, ncurses först.

• Ett bygge läser projektets recept en gång, när det startar. En fil som sparas senare väntar till nästa bygge.
• Ett projektrecept med samma namn som ett biblioteksrecept ersätter det receptet bara i det här projektets appar, och byggets logg säger det.
• Efter det sista receptet körs varje recepts kontroll igen i det färdiga prefixet: bin/cmatrix -V för det här receptet. På en x86_64-NAS är ARM-appen ett korsbygge, och dess kontroller körs bara där qemu-user är registrerat; utan det noterar bygget dem som inte körda.

06Packa och installera

licenses.txt anger vad paketets share/licenses/ innehåller: en rad per recept som paketet bär med sig, med dess licens och licensfilerna i dess källarkiv. Startreceptets rad anger platshållaren. cmatrix behöver två rader, eftersom ncurses är inlänkat i det:

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

make qpkg i redigerarens terminal packar det senaste lyckade bygget av varje app i paketet med QDK från sidan Verktygskedjor, en fil per arkitektur, och utelämnar en app som saknar ett sådant. En dynamiskt länkad app avvisas: dess program skulle leta efter sina bibliotek i appens prefix, som paketet inte skapar.

make qpkg

Paketen hamnar i build/qpkg/build/, namngivna efter QPKG_NAME och QPKG_VER i qpkg.cfg: cmatrix_0.1.0_x86_64.qpkg och cmatrix_0.1.0_arm_64.qpkg. Vart och ett innehåller appens bin/, sbin/, share/ (utan man, doc och info) och etc/: här cmatrix och det som ncurses installerade där, dess verktyg och dess terminaldatabas. KEEP överst i scripts/make-qpkg.sh anger i stället de sökvägar som ett paket ska innehålla, till exempel bin/cmatrix share/terminfo.

Med kodsigneringsfilerna i qpkg/ bredvid qpkg.cfg, eller i en mapp som QPKG_CERT_DIR anger, signeras paketet, och Testdriftsättning i projektvyn (för administratörer) installerar det på den här NAS:en. App Center från ditt eget förråd visar signering och publicering mer i detalj. Transmission från grunden tar ett projekt av typen Paket från källkod med fem recept hela vägen, från en NAS där inget är inställt till det signerade paketet installerat och svarande i webbläsaren.

07Ett andra recept

Bucket: New recipe lägger till ett recept från samma startrecept. Kör kommandot från Command Palette (Ctrl+Shift+P) medan en fil i projektet är öppen, eller högerklicka på mappen recipes eller en receptmapp i Explorer. Kommandot frågar efter namnet (gemener, siffror och + . _ -), skriver recipe.json och build.sh, öppnar recipe.json och kontrollerar projektet.

• Skriv in det nya namnet i recipes.txt för appar som skapas från och med nu. En app som skapats tidigare behåller sin lista: Ändra på dess sida lägger till receptet.
• Ett recept vars bygge behöver npm-, Go- eller Cargo-paket listar dem i en vendor-fil. npm-vendor.py, go-vendor.py och cargo-vendor.py i /usr/bin/bucketvs/share/bucketvs/tools/ skriver den listan; de behöver en Python-körmiljö från sidan Verktygskedjor.
• Projektrecept körs som root i byggmiljön, precis som bibliotekets, och vilken utvecklare som helst kan skriva och bygga dem. En viewer ser namnen på en apps recept i dess bygglogg, aldrig receptfilerna.
• Ett projektrecept stannar i sitt projekt. Det kommer in i receptbiblioteket, och i den signerade katalogen som varje NAS hämtar, bara genom en granskad ändring i själva Bucket & Code Server IDE.