hbuild

Wprowadzenie

hbuild to narzędzie budowania zaprojektowane wyłącznie dla HackerOS Linux. Zastępuje make, cmake, meson i ninja jednym spójnym interfejsem obsługującym ponad 20 języków programowania, zaawansowane zarządzanie zależnościami (git, lokalne, binarne, systemowe), budowanie w efemerycznych kontenerach, sandbox oparty o Linux namespaces + seccomp, oraz system pluginów (Lua / WASM / dynlib).

hbuild jest wbudowany w HackerOS — nie wymaga żadnej dodatkowej instalacji.

Quickstart

# Zainicjuj projekt (tworzy hbuild.config w aktualnym katalogu)
hbuild setup

# Zbuduj projekt (domyślny profil: release)
hbuild make

# Zbuduj z profilem debug
hbuild make --profile debug

# Zbuduj w izolowanym kontenerze
hbuild make --container

# Zbuduj w sandboxie (namespaces + seccomp)
hbuild make --sandbox

# Cross-kompilacja na aarch64
hbuild make --target aarch64-unknown-linux-gnu

# Wyczyść artefakty
hbuild clean

# Wyczyść i zbuduj od nowa
hbuild remake

# Zainstaluj do systemu (lub ~/.local gdy nie root)
hbuild install

# Spakuj do .deb lub .tar.gz
hbuild bundle

# Wygeneruj dokumentację
hbuild doc

# Zaktualizuj hbuild z repozytorium
hbuild self-update

Podkomendy i opcje

Opcje globalne

Profile budowania

Formaty pliku konfiguracyjnego

hbuild przeszukuje katalog projektu w następującej kolejności:

Format .hk — HackerLang

Format .hk używa składni podobnej do TOML, ale z własnym operatorem przypisania -> klucz => wartość.

Kompletny przykład — hbuild.config

[metadata]
-> name    => "my_app"
-> version => "1.0.0"
-> authors => "HackerOS Team <hackeros068@gmail.com>"
-> license => "GPL-3.0"

[description]
-> summary => "Krótki opis projektu"
-> long    => "Dłuższy opis projektu widoczny w pakiecie .deb."

[specs]
-> c++      => "g++"
-> dependencies {
    -> zlib    => ">=1.2.11"
    -> libcurl => ">=7.80.0"
    -> my_lib {
        -> path => "../my_lib"
    }
    -> some_git_dep {
        -> git     => "https://github.com/example/dep.git"
        -> version => "abc123def456abc123def456abc123def456abc1"
    }
}

[runtime]
-> priority     => "normal"
-> auto-restart  => false

[build]
-> target           => "my_app"
-> sources          => ["src/*.cpp", "src/**/*.cpp"]
-> include_dirs     => ["include"]
-> compiler         => "g++"
-> standard         => "c++20"
-> optimize         => "O2"
-> cflags           => "-Wall -Wextra"
-> ldflags          => "-lpthread"
-> lib_dirs         => ["build/lib"]
-> libs             => ["z", "curl"]
-> pkg_dependencies => ["zlib", "libcurl"]
-> build_type       => "executable"
-> native           => true
-> container        => false
.hk

Składnia .hk w skrócie

Sekcje konfiguracji

[metadata]

[description]

[specs]

Deklaracja języków i zależności zewnętrznych.

[runtime]

[build]

Sekcja wymagana dla języków kompilowanych (C/C++, Fortran, Ada, Pascal, …). Języki z własnym systemem budowania (Rust/Cargo, Go/go build, Java/Maven) mogą ją pominąć lub podać tylko target i build_type.

Obsługiwane języki

Zarządzanie zależnościami

hbuild obsługuje cztery typy źródeł zależności. Wszystkie rozwiązane zależności są zapisywane do pliku hbuild.lock (patrz Lockfile).

Systemowe (pkg-config)

-> dependencies {
    -> zlib    => ">=1.2.11"  # weryfikacja przez pkg-config
    -> libcurl => ">=7.80.0"
}

Git

-> my_dep {
    -> git     => "https://github.com/user/repo.git"
    -> version => "a1b2c3d4e5f6..."  # hash commitu lub tag
}

Lokalne

-> my_lib {
    -> path => "../my_lib"  # relatywna lub absolutna ścieżka
}

Binarne (z weryfikacją SHA-256)

-> prebuilt_tool {
    -> binary => "https://example.com/tool-v1.0-linux.tar.gz"
    -> sha256 => "e3b0c44298fc1c149afbf4c8996fb924..."
}

Tymczasowe kontenery budowania

hbuild może uruchamiać cały krok budowania wewnątrz efemerycznego kontenera overlay opartego o Linux user namespaces i overlay-mount. Kontener jest tworzony tuż przed kompilacją i automatycznie niszczony po jej zakończeniu — żadnych pozostałości na dysku.

Jak włączyć

W pliku konfiguracyjnym:

[build]
-> container => true
# ... reszta sekcji build

Lub przez CLI (nadpisuje ustawienie z pliku):

hbuild make --container

Co dzieje się wewnątrz

Kontener tworzy warstwowany system plików:

• Warstwa dolna (read-only): /usr, /bin, /lib, /lib64, /etc z hosta + katalog projektu.
• Warstwa górna (read-write): katalog build/ — artefakty kompilacji trafiają tutaj i są widoczne na hoście.
• Brak dostępu do sieci (nowy network namespace).
• Brak dostępu do innych procesów (nowy mount namespace).

Połączenie z sandboxem

Sandbox (izolacja procesu)

Tryb sandbox (--sandbox) uruchamia kompilatory w nowym namespace sieciowym i montażowym (Linux namespaces). Przy kompilacji z featurem sandbox dodawane są również filtry seccomp (blokada syscalli) i Landlock (ograniczenie dostępu do systemu plików).

# Buduj z sandboxem
hbuild make --sandbox

# Zbuduj hbuild z pełnym sandboxem (seccomp + Landlock)
cargo build --release --features sandbox

Cross-kompilacja

Przekaż triple docelowej architektury przez --target:

# C++ na ARM64
hbuild make --target aarch64-unknown-linux-gnu

# Rust na ARM64 (rustup target instalowany automatycznie)
hbuild make --target aarch64-unknown-linux-gnu

# Go cross-compile (GOOS/GOARCH)
hbuild make --target linux/arm64

# Zig — natywne cross-compile
hbuild make --target aarch64-linux-musl

System pluginów

Pluginy są ładowane z ~/.hbuild/plugins/. Obsługiwane typy:

Przykład pluginu Lua

-- ~/.hbuild/plugins/notify.lua
hooks = {}

function hooks.pre_build(config)
  print("Budowanie: " .. config.name)
end

function hooks.post_build(config)
  os.execute("notify-send 'hbuild' 'Budowanie zakończone: " .. config.name .. "'")
end

Dostępne hooki

Dokumentacja i artefakty

Pełna referencja pól konfiguracji

Typy wartości .hk

Lockfile (hbuild.lock)

Po rozwiązaniu zależności hbuild zapisuje plik hbuild.lock w katalogu projektu. Commit go do systemu kontroli wersji, aby zapewnić reprodukowalne buildy.

// hbuild.lock (JSON)
{
  "version": 1,
  "dependencies": {
    "my_dep": {
      "source": { "type": "git", "url": "...", "commit": "abc123..." },
      "version": "abc123...",
      "sha256": null
    }
  }
}

Zmienne środowiskowe