Pakete

Ein Hilde-Paket ist ein Verzeichnis mit einem Manifest namens hilde.toml, den eigenen Modulen unter src und den benötigten Paketen unter vendor/, die mit eingecheckt werden. Die Paketbefehle führt hilde-pkg aus, das neben dem Compiler installiert wird. Der Compiler reicht sie weiter, sodass alle als hilde <Befehl> aufgerufen werden. Nur get und update greifen aufs Netz zu, und zwar über git.

Ein neues Paket

hilde new Acme.Json --git --packaging
hilde new module Acme.Json.Parse

hilde new legt hilde.toml an, eine leere hilde.sum, einen Changelog im Debian-Format, die ISC-Lizenz mit dem Autor aus der git-Konfiguration, README.md, .gitignore und das Modul samt Testdatei (src/Json.hih, src/Json.hiq, src/Json.test.hiq). Jede Quelldatei bekommt einen SPDX-Kopf. Mit --bin entsteht ein Programm mit main-Funktion, mit --git ein git-Repository und mit --packaging Paketierungsskripte für Debian, OpenBSD und FreeBSD sowie ein Quellpaket. hilde new module fügt unter src ein weiteres Modul hinzu.

hilde.toml

targets = ["linux", "openbsd"]

[package]
name = "Acme.App"
version = "v0.1.0"
signify-key = "RWS..."
capabilities = ["unsafe", "embed"]

[require]
"Acme.Json" = { git = "<git address>", version = "v1.2.0" }

[c-source]
commit = true
dir = "c"

[policy]
require-signatures = true

Der Name ist das Modulpräfix des Pakets. Versionen haben die Form vX.Y.Z, und die Version im Manifest eines Releases ist zugleich sein git-Tag. Eine Abhängigkeit nennt die kleinste Version, die sie braucht, und wo git sie findet. Sie kann außerdem den Schlüssel festlegen, mit dem ihre Releases signiert sein müssen. Unbekannte Schlüssel oder Tabellen im Manifest werden abgelehnt, damit Tippfehler sofort auffallen.

Pakete holen

hilde get [email protected] --git=<git address>
hilde get

get holt jedes Paket, das direkt oder indirekt verlangt wird, über seine git-Tags. Die Versionen wählt es mit Minimal Version Selection: Jedes Präfix bekommt die höchste Version, die eines der ausgewählten Pakete verlangt, aber nie eine neuere. Zu einem Präfix gehört genau eine Hauptversion. Eine neue Hauptversion bekommt ein neues Präfix, zum Beispiel Acme.Json2. Die Quellbäume landen unter vendor/<präfix>/, ihre Prüfsummen in hilde.sum. Die Prüfsumme ist der dirhash von Go über alle Dateien des Baums. In vendor/ und hilde.sum ändert sich erst etwas, wenn alle Pakete geholt und geprüft sind.

hilde verify
hilde update --check
hilde update

verify gleicht vendor/ ohne Netzzugriff mit hilde.sum ab. update hebt jede Abhängigkeit einzeln auf den neuesten Tag ihrer Hauptversion an. Danach führt es hilde test src und hilde guard aus. Scheitert eins davon, oder braucht das Paket danach eine zusätzliche Fähigkeit, wird die Anhebung zurückgenommen. Eine neue Hauptversion wählt update nie.

Bauen

Innerhalb eines Pakets findet der Compiler die Module aus src, aus allen Bäumen unter vendor/ und aus der Standardbibliothek selbst. hilde check, hilde test, hilde compile, hilde lsp und hilde guard brauchen daher kein --modules. hilde build ist ein anderer Name für hilde compile:

hilde check src/Json.hih,src/Json.hiq
hilde test src
hilde build src/Main.hih,src/Main.hiq --entrypoint=Acme.App.Main:main --output=app

hilde guard zeigt für jedes Paket, welche seiner Module etwas tun, das angegeben werden muss: unsafe, foreign oder embed. Verwendet ein Paket eine Fähigkeit, die nicht unter capabilities in [package] steht, endet guard mit dem Exit-Status 4.

--json

Jeder Paketbefehl versteht --json und gibt dann ein JSON-Objekt aus:

{"command": "verify", "ok": true, "count": 2, "summary": "...", "problems": []}

Ein Problem besteht aus einem Code zwischen H1501 und H1534, einer Meldung und einem Vorschlag. Der Exit-Status ist 0, wenn der Befehl erledigt hat, was verlangt war, 1 bei einem Problem und 2 bei einer ungültigen Kommandozeile. Auch hilde test, hilde guard und hilde fmt --check verstehen --json. Der Compiler gibt seine Fehler mit --error-format=json im Format von rustc aus oder mit --error-format=hilde-json im eigenen Format.

C-Quellen mit [c-source]

Die Tabelle [c-source] im Manifest hat zwei Schlüssel: commit legt fest, ob das erzeugte C mit dem Paket eingecheckt wird, und dir nennt das Verzeichnis dafür, standardmäßig c. hilde export --with-c schreibt das erzeugte C für das aktuelle System in dieses Verzeichnis.

Ein Release

hilde export --make-key=release
hilde export --secret-key=release.sec
git add -A
git commit -m "release v1.3.0"
git tag v1.3.0

export verlangt für jedes Modul eine Testdatei, bestandene Tests und einen Test, der jede exportierte Funktion aufruft. Es vergleicht die Schnittstellen mit denen des letzten Tags und lehnt eine Versionsnummer ab, die zu klein für die Änderung ist. Eine entfernte oder geänderte Deklaration, ein strengeres requires oder ein schwächeres ensures verlangt eine neue Hauptversion, eine neue Deklaration eine neue Nebenversion. export schreibt llms.txt, eine Manpage je Modul, die Signatur des Baums nach signatures/ und das Archiv samt Signatur nach dist/. hilde api-diff alt neu zeigt denselben Vergleich zwischen zwei Verzeichnissen.

Signaturen mit signify

Signaturen werden im Format von signify(1) aus OpenBSD erstellt.

• Ein Paket-Release gilt als signiert, wenn sein Baum signatures/vX.Y.Z.sig enthält, eine Signatur über seine Prüfsumme (h1: und den dirhash). hilde export --make-key=release erzeugt das Schlüsselpaar, --secret-key=release.sec signiert damit. Was hilde-pkg signiert hat, lässt sich mit signify -V prüfen.
• Vertrauen beim ersten Gebrauch: Beim ersten Gebrauch eines Pakets wird sein öffentlicher Schlüssel übernommen und als key: am Ende seiner Zeile in hilde.sum eingetragen. Jedes spätere Release mit diesem Präfix muss mit demselben Schlüssel signiert sein. Eine Abhängigkeit kann den Schlüssel schon vorher mit signify-key in [require] festlegen, und ein Paket nennt seinen eigenen Schlüssel mit signify-key in [package]. Mit require-signatures = true in [policy] werden unsignierte Pakete abgelehnt.
• Hilde selbst wird als hilde-X.Y.Z.tar.gz mit hilde-X.Y.Z.tar.gz.sig veröffentlicht. Der öffentliche Schlüssel hilde-1.0.pub liegt im Hauptverzeichnis des Hilde-Repositorys:

signify -V -p hilde-1.0.pub -m hilde-1.0.1.tar.gz

Dokumentation und Installation

hilde doc Standard.Text.trim
hilde doc --man Acme.Json > Acme.Json.3
hilde install --prefix=/usr/local --destdir=stage

doc zeigt ein Modul oder eine Deklaration mit Vertrag und Docstring an, ohne Netzzugriff. install schreibt ausschließlich in den Staging-Baum: Programme nach bin, die Quellen einer Bibliothek nach share/hilde, dazu Manpages, Lizenz und Changelog. Das Beispiel im Docstring einer exportierten Funktion wird bei jedem hilde test innerhalb eines Pakets als Test ausgeführt.