Twój pierwszy własny przepis: program, którego nie ma w bibliotece, jako pakiet QTS

Biblioteka przepisów App Builder buduje długą listę programów. Gdy Twojego programu na niej nie ma, projekt może zawierać własny przepis: dwa pliki w folderze recipes/, w formacie biblioteki. Ten poradnik pakuje cmatrix 2.0, mały program terminalowy, który potrzebuje ncurses z biblioteki, jako pakiet QTS dla NAS-ów x86_64 i ARM 64-bit.

1. ProjektPakiet ze źródeł
2. Przepisrecipe.json, build.sh
3. Sprawdzeniekontrola w edytorze
4. Budowaniedwie aplikacje, dwa procesory
5. Pakietmake qpkg

Zrzuty ekranu pochodzą z panelu i z edytora Bucket & Code Server IDE, a każdy krok wykonano tak, jak opisuje ten poradnik. Folder danych to /share/ZFS530_DATA/BucketVS.

01Utwórz projekt

Na stronie Projekty kreator Nowy projekt najpierw pyta o szablon. Wybierz Pakiet ze źródeł: pakiet QTS z programami, które kompilujesz ze źródeł własnymi przepisami, dla x86_64 i arm64.

Nazwij projekt cmatrix. Ta nazwa staje się nazwą pakietu. Zapisana małymi literami, bez znaków niedozwolonych w nazwie przepisu, jest też nazwą przepisu startowego i obu aplikacji. Krok Usługa określa, co pakiet robi, gdy działa. Narzędzie wiersza poleceń, wybrane od razu przy otwarciu kroku, dowiązuje bin/cmatrix pakietu do /usr/bin, dopóki pakiet jest uruchomiony. Folder projektu zawiera wtedy:

Makefile buduje dwie aplikacje: <name> dla procesora tego NAS-a i <name>-arm64 dla NAS-ów ARM 64-bit; na NAS-ie x86_64 ta druga powstaje przez kompilację skrośną. Obie budują się w środowisku builder z Ubuntu 24.04 i są linkowane statycznie. Jeśli tego środowiska brakuje, utworzysz je przyciskiem Utwórz to środowisko na stronie Toolchainy. W tym szablonie opcja Zbuduj zaraz po utworzeniu jest wyłączona: przepis startowy wskazuje źródło zastępcze z sumą sha256 złożoną z 64 zer, więc kompilacja kończy się błędem, dopóki przepis nie wskaże Twojego programu.

02Przepis startowy

Otwórz w edytorze w widoku projektu otwiera folder projektu w edytorze. Plik recipe.json mówi, co zbudować, a build.sh, jak to zrobić.

build.sh definiuje trzy fazy, a każda z nich uruchamia się w rozpakowanych źródłach. W przepisie startowym są to fazy dla CMake. Komentarze pokazują, jak każda z nich wygląda dla autoconf i 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 i meson_std przekazują prefiks aplikacji, tryb linkowania, a w aplikacji ARM także cel kompilacji skrośnej, więc ten sam plik służy obu aplikacjom.

03Źródło Twojego programu

Znajdź adres archiwum wydania i w terminalu edytora oblicz jego sumę sha256:

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

cmatrix buduje się przez CMake, a do rysowania używa ncurses, które jest w bibliotece przepisów. Skrypt CMake programu znajduje ncurses jako plik libncurses.a. W aplikacji statycznej CMake dopisuje wtedy za tym plikiem opcję -Wl,-Bdynamic, więc linker zażądałby współdzielonej libc i się zatrzymał. Funkcja do_configure z przepisu startowego utrzymuje linkowanie statyczne do końca wiersza, więc build.sh zostaje bez zmian:

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

W recipe.json jako sprawdzenie wpisz bin/cmatrix -V: ta opcja wypisuje wersję cmatrix 2.0 (na --version program odpowiada tekstem pomocy):

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

• W folderze przepisu są tylko recipe.json, build.sh i ewentualnie plik vendor wskazany w recipe.json. Łatkę wpisujesz do build.sh jako here-document.
• recipes.txt zawiera już przepis startowy. Przepisy z biblioteki, od których on zależy, dołączą do kompilacji same, we właściwej kolejności.

04Sprawdź przepis

Po każdym zapisaniu pliku przepisu przepisy projektu są sprawdzane, a uwagi pojawiają się w widoku Problemy, każda przy swoim pliku i wierszu. Sprawdzenie czyta recipe.json i analizuje build.sh przez bash -n; nigdy nie uruchamia przepisu. 64 zera z przepisu startowego dają właśnie taką uwagę: ostrzeżenie przy wierszu sha256, dopóki nie wpiszesz prawdziwej sumy.

To samo sprawdzenie działa w terminalu i w zadaniu CI:

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

Karta Przepisy w widoku projektu pokazuje przepisy projektu w takiej postaci, w jakiej biorą je jego aplikacje, każdy z wynikiem sprawdzenia i uwagami. Kliknięcie wiersza otwiera folder przepisu w edytorze, a menu wiersza kopiuje polecenie kontroli.

05Zbuduj obie aplikacje

Przycisk Zbuduj w widoku projektu uruchamia Makefile projektu: tworzy obie aplikacje, jeśli ich brakuje, i buduje je po kolei. Strona każdej aplikacji (Aplikacje) podaje projekt, z którego pochodzą jej przepisy, a log kompilacji wymienia przepisy w kolejności budowania, najpierw ncurses.

• Kompilacja czyta przepisy projektu raz, na starcie. Plik zapisany później czeka na następną kompilację.
• Przepis projektu o takiej samej nazwie jak przepis z biblioteki zastępuje tamten przepis, ale tylko w aplikacjach tego projektu. Log kompilacji to odnotowuje.
• Po ostatnim przepisie sprawdzenie każdego przepisu uruchamia się jeszcze raz, na gotowym prefiksie; tutaj jest to bin/cmatrix -V. Na NAS-ie x86_64 aplikacja ARM powstaje przez kompilację skrośną, a jej sprawdzenia działają tylko wtedy, gdy zarejestrowano qemu-user. Bez niego kompilacja zapisuje je jako niewykonane.

06Spakuj i zainstaluj

licenses.txt określa zawartość share/licenses/ pakietu: jeden wiersz na każdy przepis, który zawiera pakiet, z jego licencją i plikami licencji z jego archiwum źródeł. Wiersz z przepisu startowego wskazuje źródło zastępcze. cmatrix potrzebuje dwóch wierszy, bo jest z nim zlinkowane ncurses:

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

make qpkg w terminalu edytora pakuje przez QDK (ze strony Toolchainy) najnowszą udaną kompilację każdej aplikacji, jeden plik na architekturę. Aplikację bez udanej kompilacji pomija. Aplikację linkowaną dynamicznie odrzuca, bo jej programy szukałyby bibliotek w prefiksie aplikacji, którego pakiet nie tworzy.

make qpkg

Pakiety trafiają do build/qpkg/build/, z nazwami według QPKG_NAME i QPKG_VER z qpkg.cfg: cmatrix_0.1.0_x86_64.qpkg i cmatrix_0.1.0_arm_64.qpkg. Każdy zawiera katalogi bin/, sbin/, share/ (bez man, doc i info) i etc/ aplikacji: tutaj cmatrix oraz to, co zainstalowało tam ncurses, czyli jego narzędzia i bazę danych terminali. KEEP na początku scripts/make-qpkg.sh wskazuje ścieżki, które pakiet ma zawierać zamiast tego, na przykład bin/cmatrix share/terminfo.

Gdy pliki do podpisywania kodu leżą w qpkg/ obok qpkg.cfg albo w folderze wskazanym przez QPKG_CERT_DIR, pakiet zostaje podpisany, a Wdrożenie testowe w widoku projektu (admin) instaluje go na tym NAS-ie. App Center z własnego repozytorium pokazuje dokładniej podpisywanie i publikowanie. Transmission od zera pokazuje cały projekt typu Pakiet ze źródeł z pięcioma przepisami: od NAS-a, na którym nic jeszcze nie skonfigurowano, do podpisanego pakietu, który jest zainstalowany i odpowiada w przeglądarce.

07Drugi przepis

Bucket: New recipe dodaje przepis z tego samego wzoru co przepis startowy. Uruchom to polecenie z palety poleceń (Ctrl+Shift+P), gdy jest otwarty plik projektu, albo kliknij prawym przyciskiem folder recipes lub folder przepisu w Eksploratorze. Polecenie pyta o nazwę (małe litery, cyfry i + . _ -), zapisuje recipe.json i build.sh, otwiera recipe.json i sprawdza projekt.

• Dopisz nową nazwę do recipes.txt; to wystarczy dla aplikacji tworzonych od teraz. Aplikacja utworzona wcześniej ma własną listę: przepis dodasz do niej przyciskiem Zmień na jej stronie.
• Przepis, którego kompilacja potrzebuje pakietów npm, Go lub Cargo, wymienia je w pliku vendor. Tę listę zapisują npm-vendor.py, go-vendor.py i cargo-vendor.py z /usr/bin/bucketvs/share/bucketvs/tools/; potrzebują środowiska uruchomieniowego Python ze strony Toolchainy.
• Przepisy projektu działają jako root w środowisku buildera, tak jak przepisy biblioteki, a każde konto z rolą developer może je pisać i budować. Konto z rolą viewer widzi nazwy przepisów aplikacji w jej logu kompilacji, nigdy pliki przepisów.
• Przepis projektu zostaje w swoim projekcie. Do biblioteki przepisów i do podpisanego katalogu, który pobiera każdy NAS, może trafić tylko jako przejrzana zmiana w samym Bucket & Code Server IDE.