La tua prima ricetta: un programma che manca alla libreria, come pacchetto QTS

La libreria di ricette di App Builder compila un lungo elenco di programmi. Quando il tuo non c’è, un progetto può portare con sé una ricetta propria: due file nella sua cartella recipes/, nel formato della libreria. Questa guida impacchetta cmatrix 2.0, un piccolo programma da terminale che richiede ncurses dalla libreria, come pacchetto QTS per NAS x86_64 e ARM a 64 bit.

1. ProgettoPacchetto dai sorgenti
2. Ricettarecipe.json, build.sh
3. Controlloil lint nell’editor
4. Builddue app, due processori
5. Pacchettomake qpkg

Le immagini provengono dal pannello e dall’editor di Bucket & Code Server IDE, con ogni passaggio eseguito come descritto in questa guida. La cartella dei dati è /share/ZFS530_DATA/BucketVS.

01Crea il progetto

Nella pagina Progetti, Nuovo progetto chiede prima il modello. Scegli Pacchetto dai sorgenti: un pacchetto QTS di programmi che compili dai sorgenti con le tue ricette, per x86_64 e arm64.

Chiamalo cmatrix. Il nome del progetto diventa il nome del pacchetto e, in minuscolo e senza i caratteri che il nome di una ricetta non può contenere, il nome della sua ricetta iniziale e delle sue due app. Il passaggio Servizio stabilisce cosa fa il pacchetto mentre è in esecuzione. Strumento da riga di comando, già scelto quando il passaggio si apre, collega bin/cmatrix del pacchetto in /usr/bin finché il pacchetto è avviato. La cartella del progetto contiene allora:

Il Makefile compila due app: <name> per il processore di questo NAS e <name>-arm64 per i NAS ARM a 64 bit, una compilazione incrociata su un NAS x86_64. Entrambe si compilano nel builder Ubuntu 24.04 con collegamento statico; se quell’ambiente manca, puoi crearlo con Crea questo ambiente nella pagina Toolchain. Compila subito dopo la creazione è disattivato per questo modello: la ricetta iniziale indica un sorgente segnaposto con uno sha256 di 64 zeri, quindi una build fallisce finché la ricetta non indica il tuo programma.

02La ricetta iniziale

Apri nell’editor nella vista del progetto apre la cartella del progetto nell’editor. recipe.json dice cosa compilare; build.sh dice come.

build.sh definisce tre fasi, ognuna eseguita nel sorgente decompresso. Quelle della ricetta iniziale sono per CMake, e i suoi commenti indicano per ciascuna la forma per autoconf e per 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 e meson_std passano il prefisso dell’app, la modalità di collegamento e, per un’app ARM, la destinazione della compilazione incrociata, così lo stesso file serve entrambe le app.

03Il sorgente del tuo programma

Prendi l’indirizzo dell’archivio della release e calcola il suo sha256 nel terminale dell’editor:

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

cmatrix si compila con CMake e disegna con ncurses, che è già nella libreria. Il suo script CMake trova ncurses come file, libncurses.a, e in un’app statica CMake chiude la riga di collegamento con -Wl,-Bdynamic dopo di esso, quindi il collegamento chiederebbe una libc condivisa e si fermerebbe. Il do_configure della ricetta iniziale mantiene la riga statica fino alla fine, quindi build.sh resta com’è:

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

In recipe.json il controllo diventa bin/cmatrix -V, l’opzione che stampa la versione di cmatrix 2.0 (a --version risponde con il suo testo di aiuto):

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

• La cartella di una ricetta contiene recipe.json, build.sh e il file vendor che recipe.json può indicare, e nient’altro. Una patch va in build.sh come here-document.
• recipes.txt indica già la ricetta iniziale; le ricette della libreria da cui dipende vengono aggiunte alla build nel loro ordine.

04Controllala

Ogni volta che salvi un file di una ricetta, le ricette del progetto vengono controllate e i rilievi compaiono nella vista Problemi, ciascuno con il suo file e la sua riga. Il controllo legge recipe.json e analizza build.sh con bash -n; non esegue mai la ricetta. I 64 zeri della ricetta iniziale sono uno di questi rilievi: un avviso sulla riga dello sha256, finché non inserisci la somma vera.

Lo stesso controllo si esegue anche nel terminale e in un job di CI:

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

La scheda Ricette della vista del progetto elenca le ricette del progetto così come le usano le sue app, ognuna con il risultato del lint e i suoi rilievi. Un clic su una riga apre la cartella della ricetta nell’editor, e il menu della riga copia il comando di lint.

05Compila le due app

Compila nella vista del progetto esegue il Makefile del progetto: crea le due app se mancano e le compila una dopo l’altra. La pagina di ogni app, nella pagina App, indica il progetto da cui vengono le sue ricette, e il log della build elenca le ricette in ordine, a partire da ncurses.

• Una build legge le ricette del progetto una volta sola, quando parte. Un file salvato dopo vale solo dalla build successiva.
• Una ricetta del progetto con il nome di una ricetta della libreria sostituisce quella ricetta solo nelle app di questo progetto, e il log della build lo indica.
• Dopo l’ultima ricetta, il controllo di ogni ricetta viene eseguito di nuovo sul prefisso finito: bin/cmatrix -V per questa. Su un NAS x86_64 l’app ARM è una compilazione incrociata, e i suoi controlli vengono eseguiti solo dove qemu-user è registrato; senza di esso la build li registra come non eseguiti.

06Impacchetta e installa

licenses.txt indica cosa contiene share/licenses/ del pacchetto: una riga per ogni ricetta contenuta nel pacchetto, con la sua licenza e i file di licenza nel suo archivio dei sorgenti. La riga della ricetta iniziale indica il segnaposto. cmatrix richiede due righe, perché vi è collegata ncurses:

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

make qpkg nel terminale dell’editor impacchetta con QDK della pagina Toolchain la build riuscita più recente di ogni app, un file per architettura, e lascia fuori un’app che non ne ha. Un’app con collegamento dinamico viene rifiutata: i suoi programmi cercherebbero le loro librerie nel prefisso dell’app, che il pacchetto non crea.

make qpkg

I pacchetti finiscono in build/qpkg/build/, con il nome preso da QPKG_NAME e QPKG_VER di qpkg.cfg: cmatrix_0.1.0_x86_64.qpkg e cmatrix_0.1.0_arm_64.qpkg. Ognuno contiene bin/, sbin/, share/ (senza man, doc e info) e etc/ dell’app: qui cmatrix e ciò che ncurses vi ha installato, i suoi strumenti e il suo database dei terminali. KEEP all’inizio di scripts/make-qpkg.sh indica, al posto di questi, i percorsi che un pacchetto deve contenere, per esempio bin/cmatrix share/terminfo.

Con i file per la firma del codice in qpkg/ accanto a qpkg.cfg, o in una cartella indicata da QPKG_CERT_DIR, il pacchetto è firmato, e Deploy di prova nella vista del progetto (riservato agli admin) lo installa su questo NAS. App Center dal tuo repository mostra più in dettaglio la firma e la pubblicazione. Transmission da zero porta fino in fondo un progetto Pacchetto dai sorgenti con cinque ricette, da un NAS senza nulla di configurato al pacchetto firmato installato e raggiungibile dal browser.

07Una seconda ricetta

Bucket: New recipe aggiunge una ricetta a partire dalla stessa ricetta iniziale. Eseguilo dal Riquadro comandi (Ctrl+Shift+P) mentre è aperto un file del progetto, oppure fai clic destro sulla cartella recipes o sulla cartella di una ricetta in Esplora risorse. Chiede il nome (lettere minuscole, cifre e + . _ -), scrive recipe.json e build.sh, apre recipe.json e controlla il progetto.

• Scrivi il nuovo nome in recipes.txt per le app create da ora in poi. Un’app creata prima mantiene il suo elenco: per aggiungere la ricetta usa Cambia nella sua pagina.
• Una ricetta la cui build richiede pacchetti npm, Go o Cargo li elenca in un file vendor. npm-vendor.py, go-vendor.py e cargo-vendor.py in /usr/bin/bucketvs/share/bucketvs/tools/ scrivono quell’elenco; richiedono un runtime Python dalla pagina Toolchain.
• Le ricette dei progetti vengono eseguite come root nell’ambiente builder, come quelle della libreria, e qualsiasi developer può scriverle e compilarle. Un viewer vede i nomi delle ricette di un’app nel suo log di build, mai i file delle ricette.
• Una ricetta di un progetto resta nel suo progetto. Entra nella libreria di ricette, e nel catalogo firmato che ogni NAS riceve, solo tramite una modifica revisionata a Bucket & Code Server IDE stesso.