Using packages

Hive is Larva's package manager, built into larva as larva hive. A package is a library named Author/Name (for example Antril-Organization/SDL3). It lives in a registry: the public one at https://www.antril.org/hive-api, another HTTPS server, or a folder.

[project] is a .queen file or a folder that holds one; without it, the current folder. Making packages is in Publishing packages.

Choose a registry

A project names its registries with provider: in its HIVE chunk:

chunk HIVE:
   provider: https://www.antril.org/hive-api

A project that names none uses your machine's setting. The installers set it to the public registry, unless you chose --no-hive:

$ larva config hive.provider https://www.antril.org/hive-api
hive.provider: https://www.antril.org/hive-api

Several registries are separated by commas, with no spaces: Hive tries them in order and takes a package from the first one that has it. A provider can be:

A folder is a whole registry: see the registry layout. It is handy for a team share, or to try packages without the network.

Add a package

From the project's folder:

$ larva hive add Ana/Greetings@^1.0
added `package: Ana/Greetings@^1.0` to Hello.queen
  fetching Ana/Greetings 1.0 from C:\work\registry
  Ana/Greetings 1.0
installed 1 package(s); pinned in hive.lock

This adds the dependency to the .queen file (and a DEPS chunk when there is none):

chunk DEPS:
   package: Ana/Greetings@^1.0

The program can then use the package's namespaces:

import System;
import Greetings;

Main()
{
	Console.WriteLine(Greeter.Greet("Hive"));
}

$ larva run
Hello, Hive!

larva build and larva run use the installed packages and never go to the network; the editor does the same. A package that is not installed is an error that says what to run:

C:\work\Hello\Hello.queen(12,13): error QN108: package Ana/Greetings@^1.0 is not installed: run `larva hive install` (or `larva hive restore`)

To write the package: entry by hand, put it in DEPS (see DEPS) and run larva hive install.

Versions

A package: entry may say which versions will do, after @:

A v before the number is allowed (@^v1.2). Missing terms count as zero, so 1.2 and 1.2.0 are the same version.

Hive picks, for each package, the newest version that meets every requirement: the project's and those of the packages it uses. When they cannot all be met, it says who wants what:

$ larva hive add Ana/Greetings@^2.0
added `package: Ana/Greetings@^2.0` to Bye.queen
larva hive: no version of Ana/Greetings in C:\work\registry fits every requirement: the project wants ^2.0; Ana/Farewells 0.3 wants ^1.0 (published: 1.0, 1.1, 2.0)

larva hive add writes the entry before it installs, so after an error like this one, fix or remove the entry in the .queen file.

A package without sources

Some packages carry a library built elsewhere instead of Antril sources, such as a binding to a native library (for example Antril-Organization/SDL3). They are used like any other package: larva hive add installs them, larva build compiles against their library and copies their native library next to the program. How to make one is in Publishing packages.

What a registry has

$ larva hive info Ana/Greetings
Ana/Greetings in C:\work\registry:
  1.0  signed a59d969b683ba7f9
  1.1 (yanked)  signed a59d969b683ba7f9
  2.0  signed a59d969b683ba7f9
$ larva hive info Ana/Farewells
Ana/Farewells in C:\work\registry:
  0.3  unsigned  needs Ana/Greetings@^1.0

Each line is a version, the key that signed it (the first 16 digits of its fingerprint) and the packages it needs. A yanked version was withdrawn by its author: Hive does not choose it, unless hive.lock already pins it. When no registry has the package, info says so and ends with the exit code 1.

hive.lock

larva hive install writes hive.lock next to the .queen file. For each package it pins the version, the SHA-256 of its file, its signing key, the registry it came from and what it needs:

{
  "format": 1,
  "packages": [
    {
      "package": "Ana/Greetings",
      "version": "1.0",
      "sha256": "2c3213cf4a1f227af46ee55d81acf9f9e455b444360d1ebd4cf99f86b5f7748b",
      "key": "a59d969b683ba7f96e9fece9d1bcf78180354d077be31daeb5b9f2ebdc7ddb2d",
      "provider": "C:\\work\\registry",
      "dependencies": []
    }
  ]
}

Keep it with your sources. While a pinned version still meets the requirements, larva hive install keeps it, even when newer versions exist. To move to the newest versions, delete hive.lock and install again:

$ larva hive install
  Ana/Greetings 1.0
installed 1 package(s); pinned in hive.lock
$ del hive.lock
$ larva hive install
  fetching Ana/Greetings 1.1 from C:\work\registry
  Ana/Greetings 1.1
installed 1 package(s); pinned in hive.lock

larva hive restore installs exactly what hive.lock says, and refuses a file whose hash is not the one it pinned. Use it on a new machine or a build server:

$ larva hive restore
  fetching Ana/Greetings 1.0 from C:\work\registry
restored 1 package(s)

The cache

Installed packages are kept in the user's Hive cache, one folder per version (packages/Author/Name/Version), unpacked and checked. A package already there with the same file is not fetched again.

$ larva hive list
Ana/Greetings 1.0
1 in C:\Users\Ana\AppData\Local\Larva\hive

What installing checks

Installing runs nothing from the package: it downloads, checks and unpacks. For each package:

• The file's SHA-256 must be the one the registry's index gives (and, for restore, the one hive.lock pins).
• The file must be a valid package: a manifest, hive.json, that lists every file with its size and SHA-256; every file must match; nothing else may be there; no path may leave the package's folder; and the package must stay within the size limits (512 MB unpacked, 20,000 files).
• The package must be the one asked for: the manifest's name and version must be the index's.
• The signature (ECDSA P-256 over the manifest) must be the one of the key the index gives for that version.
• The key must be one you trust for the package (see below).

By default packages must be signed. A project that accepts unsigned packages says so with verify: hashes in HIVE: hashes are still checked, signatures are not required.

$ larva hive add Ana/Farewells
added `package: Ana/Farewells` to Bye.queen
  fetching Ana/Farewells 0.3 from C:\work\registry
larva hive: Ana/Farewells 0.3 is not signed (`verify: hashes` in HIVE accepts unsigned packages)

chunk HIVE:
   provider: ../registry,
   verify: hashes

$ larva hive install
  fetching Ana/Farewells 0.3 from C:\work\registry
  Ana/Farewells 0.3 (unsigned)
  Ana/Greetings 1.1
installed 2 package(s); pinned in hive.lock

A file that was changed is refused:

$ larva hive restore
  fetching Ana/Greetings 2.1 from C:\work\mirror
larva hive: Ana/Greetings 2.1 from C:\work\mirror does not match the hash its index gives: refusing it

Trusted keys

The first key a package is installed with is remembered in the cache (keys.json). A later version signed by another key is refused, even when it comes from another registry:

$ larva hive install
  fetching Ana/Greetings 2.1 from C:\work\mirror
larva hive: Ana/Greetings is now signed by key bc0f3c915cb3c06d, not by the key it was installed with (a59d969b683ba7f9). If its author changed keys, accept the new one with `hive trust Ana/Greetings bc0f3c915cb3c06db2e910a4f5ae662e9a89db2664453d54b7e28012c7190ec0`

When the author tells you they changed keys (check the fingerprint with them), accept the new key:

$ larva hive trust Ana/Greetings bc0f3c915cb3c06db2e910a4f5ae662e9a89db2664453d54b7e28012c7190ec0
Ana/Greetings may now be signed by bc0f3c915cb3c06d
$ larva hive install
  fetching Ana/Greetings 2.1 from C:\work\mirror
  Ana/Greetings 2.1
installed 1 package(s); pinned in hive.lock

The old key stays trusted too. A fingerprint is the SHA-256 of the public key, 64 hex digits.

Look inside a package file

larva hive verify checks a .hive file the same way installing does, and says what it is:

$ larva hive verify bin/Greetings-1.0.hive
Ana/Greetings 1.0 (compiled, gc default): 2 files, 4269 bytes
  signed by a59d969b683ba7f9 (not checked: give --key)
  every file matches its hash

With --key and the author's public key (base64, as larva hive key prints it), it also checks the signature:

$ larva hive verify bin/Greetings-1.0.hive --key MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEt2nz5PDcKGyCEddkuAPfBauYEJVK4G3bfrFHnPyxn3r4UkfuUNsWCkhPMgBcQ3LBxGvu5O297PxsXhRrYvQ1UQ==
Ana/Greetings 1.0 (compiled, gc default): 2 files, 4269 bytes
  signature good (a59d969b683ba7f9)
  every file matches its hash

compiled packages carry Larva libraries built for one GC mode (here default); source packages carry sources and compile with your project. See Compiled and source packages.