Packages

A Hilde package is a directory with a manifest, hilde.toml, its modules below src, and the packages it needs below vendor/, checked in. The package commands are carried out by hilde-pkg, which lies beside the compiler; the compiler hands them on, so all are called as hilde <command>. Only get and update use the network, through git.

A new package

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

hilde new writes hilde.toml, an empty hilde.sum, a changelog in Debian's form, the ISC licence with the author git knows, README.md, .gitignore, and the module with its test file (src/Json.hih, src/Json.hiq, src/Json.test.hiq), each source with an SPDX header. --bin makes a programme with a main function, --git a git repository, --packaging scripts for Debian, OpenBSD, FreeBSD and a source package. hilde new module adds a module below src.

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

The name is the module prefix of the package. A version is vX.Y.Z, and the version in the manifest of a release is its git tag. A requirement names the least version it needs and where git finds it, and may pin the key its releases are signed with. A key or table the manifest does not know is refused, so a misspelt key is found.

Getting packages

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

get fetches every package required, directly or through another, as git tags, and chooses the versions by minimal version selection: each prefix gets the greatest version any selected package requires of it, never a newer one. One prefix has one major version; a new major is a new prefix, such as Acme.Json2. The trees go to vendor/<prefix>/ and their checksums to hilde.sum. The checksum is Go's dirhash over the files of the tree. Nothing in vendor/ or hilde.sum changes unless every package was fetched and checked.

hilde verify
hilde update --check
hilde update

verify holds vendor/ against hilde.sum without the network. update raises each requirement to the newest tag of its major version, one by one; it runs hilde test src and hilde guard and takes the raise back when one of them fails or the package declares a capability more. It never raises a major version.

Building

Inside a package the compiler finds the modules of src, of every tree in vendor/ and of the standard library by itself: hilde check, hilde test, hilde compile, hilde lsp and hilde guard need no --modules. hilde build is the same command as 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 tells for each package what its modules do that must be declared: unsafe, foreign or embed. A capability used and not named in [package] capabilities ends guard with exit status 4.

--json

Every package command takes --json and then prints one object:

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

A problem has a code from H1501 to H1534, a message and a suggestion. The exit status is 0 when the command did what it was asked, 1 for a problem, 2 for a command line it does not take. hilde test, hilde guard and hilde fmt --check take --json as well, and the compiler writes its errors as JSON with --error-format=json (the form of rustc) or --error-format=hilde-json.

C sources with [c-source]

The table [c-source] of the manifest has two keys: commit, whether the generated C is committed with the package, and dir, its directory, c by default. hilde export --with-c writes the generated C of the system it runs on into that directory.

A 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 needs a test file for every module, passing tests, and a test that calls every exported function. It compares the interfaces with those of the newest tag and refuses a version lower than the change calls for: a removed or changed declaration, a stricter requires or a weaker ensures is a major version, an added declaration a minor one. It writes llms.txt, a manual page for each module, the signature of the tree into signatures/, and the archive with its signature into dist/. hilde api-diff old new shows the same comparison between two directories.

Signatures with signify

Signatures are made in the format of signify(1) of OpenBSD.

• A package release is signed when its tree has signatures/vX.Y.Z.sig, a signature over its checksum (h1: and the dirhash). hilde export --make-key=release makes the key pair, --secret-key=release.sec signs; signify -V checks what hilde-pkg signed.
• Trust on first use: the public key of a package is taken on its first use and written into hilde.sum, as key: at the end of the package's line. Every later release of that prefix must be signed by it. A requirement can pin the key in advance with signify-key in [require], and a package names its own key with signify-key in [package]. [policy] require-signatures = true refuses an unsigned package.
• Hilde's own releases are hilde-X.Y.Z.tar.gz with hilde-X.Y.Z.tar.gz.sig; the public key hilde-1.0.pub lies in the root of the Hilde repository:

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

Documentation and installing

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

doc prints a module or a declaration with its contracts and docstring, without the network. install writes only below the staging tree: a programme into bin, a library's sources into share/hilde, the manual pages, the licence and the changelog. The example in the docstring of an exported function runs as a test whenever hilde test runs inside a package.