LegendaryOS-Builder

Table of Contents

• Co potrafi
• Instalacja
• Szybki start
• Komputery i telefony
• Wymagana struktura projektu
• Komendy
• Zależności (Bit.hk)
• Bezpieczeństwo user.hk
• Rozwój
• Licencja

Narzędzie do budowy dystrybucji LegendaryOS — Linuksa bazującego na HackerOS — dla komputerów (amd64, arm64) i telefonów (arm64). Własny branding, ta sama filozofia narzędziowa: konfiguracja w .hk, hooki w Hacker Lang (.hl), a pod spodem zwykły Debianowy live-build — LegendaryOS-Builder jest jego nakładką, nie zamiennikiem.

Napisane w H#, budowane i zarządzane przez bit. Używa bibliotek z bit.io:

• colors — kolorowy, spójny interfejs CLI (use "bit → colors"),

• nidus — czytelne raporty błędów config.hk z podświetlonym fragmentem pliku (use "bit → nidus" from "nidus").

Co potrafi

Komputery	ISO hybrydowe (BIOS + UEFI) dla amd64, ISO UEFI dla arm64, instalator Calamares z brandingiem LegendaryOS.
Telefony	Obraz rootfs + surowy obraz dysku z U-Bootem (PinePhone, PinePhone Pro, Librem 5) albo boot.img + rootfs.img dla fastboot (eksperymentalne). Środowisko: Phosh.
Kilka celów naraz	→ targets ⇒ [pc:amd64, pc:arm64, phone:arm64:pinephone] buduje wszystko jednym poleceniem, każdy cel w osobnym katalogu roboczym.
Cross-build	arm64 na hoście amd64 (i odwrotnie) przez qemu-user-static — wykrywany i konfigurowany automatycznie.
Baza HackerOS	Lokalne lustro + migawka per build; import list pakietów / hooków / includes do nakładki; commit bazy w notatkach wydania.
Branding	5 obrazów trafia do Calamares, Plymouth, GRUB i splash-a bootloaderów live; generowane są też pliki, które je aktywują (branding.desc, motyw Plymouth, konfiguracja GRUB, hook chroot).
Tożsamość systemu	os-release, lsb-release, issue, motd, hostname z config.hk.
Walidacja	Struktura, nagłówki obrazów (PNG/JPEG), wartości w config.hk, literówki w kluczach, spójność architektura ↔ urządzenie. Błędy pokazuje nidus.
CI-friendly	Poprawne kody wyjścia, --strict, --dry-run, NO_COLOR, styl github w Actions.

Instalacja

Wymagania do zbudowania buildera:

• h# — kompilator H# (https://github.com/HackerOS-Linux-System/H-Sharp)

• bit — menedżer pakietów H# (https://github.com/bit-io/bit)

Wymagania do budowania systemów (sprawdza je legendaryos-builder doctor):

• live-build, git, hl (Hacker Lang), xz, tar

• telefony: e2fsprogs (≥ 1.43), parted (+ mkbootimg dla Androida)

• cross-build: qemu-user-static, binfmt-support

• lb build wymaga roota

git clone https://github.com/LegendaryOS/LegendaryOS-Builder.git
cd LegendaryOS-Builder
hl build.hl

build.hl: bit install (colors, nidus) → h# check → bit build --release → selftest → instalacja do /usr/bin/legendaryos-builder + dopełnianie komend (bash/zsh/fish). Usunięcie: hl uninstall.hl.

Szybki start

legendaryos-builder new MojeOS --kind both --device pinephone
cd MojeOS
# podmień pliki w branding/ na docelową grafikę
# uzupełnij user.hk (organizacja + token)
legendaryos-builder validate .
legendaryos-builder doctor .
legendaryos-builder sync-base
sudo legendaryos-builder build .

Gotowe artefakty (ISO, obrazy, sumy SHA-256, notatki wydania) lądują w build/out/. Pełny, gotowy do wglądu przykład (z prawdziwą grafiką): examples/legendaryos-demo/.

Komputery i telefony

Cele zapisuje się w config.hk:

[project]
-> targets => [pc:amd64, pc:arm64, phone:arm64:pinephone]

Format: pc:<arch> albo phone:<arch>:<urządzenie>. Lista urządzeń: legendaryos-builder devices. Filtrowanie przy budowie:

sudo legendaryos-builder build . --target phone          # tylko telefony
sudo legendaryos-builder build . --arch arm64            # tylko arm64 (PC + telefon)
sudo legendaryos-builder build . --target phone:arm64:pinephone

Szczegóły (układ obrazu, offsety U-Boota, dodawanie urządzeń, ograniczenia): docs/TARGETS.md.

Wymagana struktura projektu

moj-projekt/
├── branding/              <- 5 obrazów (patrz docs/STRUKTURA.md)
├── scripts/*.hl           <- WYŁĄCZNIE Hacker Lang, żadnego shella
├── files/                 <- nakładka "after packages"
├── package-lists/         <- (opcjonalnie) własne *.list.chroot
├── build.hl               <- kroki budowy (Hacker Lang)
├── config.hk              <- metadane projektu/wydania
└── user.hk                <- organizacja + token

Pełny opis: docs/STRUKTURA.md.

Komendy

Komenda	Opis
new <nazwa> [--kind pc|phone|both] [--device ID]	Szkielet projektu.
validate [ścieżka]	Walidacja (raport nidus, kod wyjścia ≠ 0 przy błędach).
build [ścieżka]	Pełny build wszystkich celów: skrypty → (stage → lb config → lb build → artefakty) × cel → notatki wydania.
clean [ścieżka]	Usuń build/ (tylko w katalogu z config.hk).
sync-base [--ref R]	Lustro bazy HackerOS (git).
targets [ścieżka]	Cele projektu i ich obrazy.
devices	Profile telefonów.
doctor [ścieżka]	Czy środowisko ma narzędzia potrzebne dla celów projektu.
info [ścieżka]	Podsumowanie projektu.
release-notes [ścieżka]	Notatki wydania z build/out.
completions <bash|zsh|fish>	Dopełnianie komend.
selftest	Wbudowane testy (bez sieci i roota).
run-scripts, stage, lb-config, lb-build	Pojedyncze etapy builda (wołane też z build.hl projektu).

Opcje: --target, --arch, --suite, --ref, --iso-name, --no-base, --strict, --clean, --keep-going, --keep-staging, -n/--dry-run, -v/--verbose, --no-color.

Zależności (Bit.hk)

[dependencies]
-> colors => newest
-> nidus  => newest

bit install zapisuje wynik do Bit.lock — warto go commitować.

Note	Biblioteka git (hgit) nie jest zależnością — patrz CHANGELOG.md (0.7.0). Cała praca z gitem jest zamknięta w src/gitsync.h#, więc podmiana backendu nie dotyka reszty kodu.

Bezpieczeństwo user.hk

user.hk to jedyny plik z sekretem ([auth] → token) — osobny od config.hk, by trzymać go poza kontrolą wersji. new dopisuje go do .gitignore. Token można też podać zmienną LEGENDARYOS_TOKEN (CI). Do git trafia przez zmienne środowiskowe GIT_CONFIG_* — nigdy w linii poleceń ani w URL-u. Nigdy nie commituj user.hk z wypełnionym tokenem.

Rozwój

bit install
h# check src/main.h#
bit build --release
./cache/build/release/legendaryos-builder selftest

Pakiety: packaging/arch/PKGBUILD, packaging/debian/build.sh.

Licencja

MIT — patrz LICENSE.