Publishing packages

A package is made from a library project (type: library). larva hive pack builds it into a .hive file; larva hive publish packs it and sends it to a registry.

1. Make a signing key

Once, and keep the file private:

$ larva hive key
wrote C:\work\Greetings\hive.key: keep it private (sign packages with `sign: hive.key` in HIVE)
public key:  MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEt2nz5PDcKGyCEddkuAPfBauYEJVK4G3bfrFHnPyxn3r4UkfuUNsWCkhPMgBcQ3LBxGvu5O297PxsXhRrYvQ1UQ==
fingerprint: a59d969b683ba7f96e9fece9d1bcf78180354d077be31daeb5b9f2ebdc7ddb2d

The key is ECDSA over P-256, written as a PEM file. The public key travels in the registry's index; its fingerprint (the SHA-256 of the public key) goes in every package and every hive.lock. larva hive key never overwrites a file: name another one with -o.

Do not put the key in a public repository. Keep it outside the project, or ignore it, and name it with a relative path such as sign: ../keys/hive.key.

2. Describe the package

The package's version and description come from PROJ; how it is published from the HIVE chunk:

queen 1.0;

chunk PROJ:
   name: Greetings,
   type: library,
   version: v1.0,
   author: Ana,
   description: "Friendly greetings."

chunk HIVE:
   provider: ../registry,
   license: MIT,
   sign: hive.key

The whole .queen format is in The .queen file.

Names (Author and Name) use letters, digits, -, _ and ., start with a letter or digit, and have at most 64 characters.

3. Pack and check

$ larva hive pack
C:\Users\Ana\AppData\Local\Temp\hive-32e6cf4648ef4dafbcf245db511f0f98\Greetings.dll: 1 types (frontend 1098 ms, write 10 ms; total 1117 ms)
  2 files, 4269 bytes before compression
packed C:\work\Greetings\bin\Greetings-1.0.hive (2976 bytes)
$ 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

The same project always makes the same bytes: files are sorted, and their times fixed.

Packing refuses a project that is not a library, has no version in PROJ, does not compile, or says private: true:

$ larva hive pack
C:\Users\Ana\AppData\Local\Temp\hive-643b3b618ab5456e8a77e56788469035\Greetings.dll: 1 types (frontend 1509 ms, write 9 ms; total 1525 ms)
larva hive: Greetings is private (`private: true` in HIVE)

4. Publish

$ larva hive publish
C:\Users\Ana\AppData\Local\Temp\hive-6e89e94522794723be1a87b1fbf9508a\Greetings.dll: 1 types (frontend 1126 ms, write 8 ms; total 1143 ms)
  2 files, 4269 bytes before compression
published Ana/Greetings 1.0 to C:\work\registry (signed by a59d969b683ba7f9)

--provider publishes somewhere else than the project's first registry, for example a mirror folder: larva hive publish --provider ../mirror.

To a registry on the web

Publishing to an HTTPS registry needs an API token, in the HIVE_TOKEN environment variable. On www.antril.org you make one on your account page (see Accounts, tokens and authors). Without it, nothing is sent:

$ larva hive publish --provider http://localhost:5080/hive-api
C:\Users\Ana\AppData\Local\Temp\hive-a9bd76bf2aea4c31b059969b1b9bc57a\Greetings.dll: 1 types (frontend 1125 ms, write 8 ms; total 1139 ms)
  2 files, 4269 bytes before compression
larva hive: publishing to http://localhost:5080/hive-api/ needs your token in HIVE_TOKEN

Set it for the command, then publish:

PowerShell:  $env:HIVE_TOKEN = "hive_..."; larva hive publish
bash:        HIVE_TOKEN=hive_... larva hive publish

The registry checks that the token is yours and that you own the package's author; if it refuses, larva hive publish shows its reason. The details are in The registry API.

To a folder

A folder registry needs no token: publish writes the package file and updates Author/Name/index.json. Copy the folder to any web server and it is a registry others can install from (see A registry made of files).

Versions

The version published is version in PROJ, without its v: version: v1.0 is published as 1.0. A version is one or more numbers separated by dots; there are no pre-release tags. Users then choose versions with ranges such as @^1.0.

A published version never changes. Publishing it again is refused:

$ larva hive publish
C:\Users\Ana\AppData\Local\Temp\hive-a2651351c4c64e07ac1a7078873cb526\Greetings.dll: 1 types (frontend 1021 ms, write 8 ms; total 1035 ms)
  2 files, 4269 bytes before compression
larva hive: Ana/Greetings 1.0 is already published: publish a new version

Raise the version for every release. For ^ ranges to work, keep the first non-zero number for compatible changes (1.0 to 1.1) and raise it when users must change their code (1.1 to 2.0).

Dependencies of the package come from its own DEPS package: entries, with their ranges; installing a package installs what it needs:

$ larva hive info Ana/Farewells
Ana/Farewells in C:\work\registry:
  0.3  unsigned  needs Ana/Greetings@^1.0

Yanking

A registry's index can mark a version as yanked: Hive then no longer chooses it, except for projects whose hive.lock already pins it, and larva hive info shows (yanked). In a folder registry you yank by setting "yanked": true on the version in index.json. There is no command for it, and the www.antril.org registry cannot yank yet: not yet available.

Signing and keys

• A package's manifest, hive.json, lists every file with its size and SHA-256. The signature, hive.sig, is ECDSA P-256 with SHA-256 over the manifest's bytes, so it vouches for every file.

• A package's first published version brings its key to the registry. Later versions must be signed with a key the registry already has for the package:

  $ larva hive publish
  C:\Users\Ana\AppData\Local\Temp\hive-628df17051a041a182a57fceaa29da3d\Greetings.dll: 1 types (frontend 1236 ms, write 12 ms; total 1259 ms)
    2 files, 4269 bytes before compression
  larva hive: Ana/Greetings is signed with other keys (a59d969b683ba7f9): sign it with one of them
  

• Once a package is signed, an unsigned version cannot be added:

  $ larva hive publish
  note: the package is not signed (set `sign` in HIVE); projects with `verify: strict` refuse it
    2 files, 345 bytes before compression
  larva hive: Ana/Greetings is signed: an unsigned version cannot be added (set `sign` in HIVE)
  

• Users remember the first key they installed a package with, and refuse others until they run larva hive trust (see Trusted keys).

So keep your key safe and backed up: if it is lost, the registry will not take new versions signed by another key. An unsigned package can be published (larva hive pack notes it), but projects install it only with verify: hashes.

Compiled and source packages

Every package also carries package.queen: the library project a program compiles with. The standard library never travels: every installation of Larva has its own. A compiled package is the smallest and needs nothing to build it; a source package can be built for any GC mode and back end.

$ larva hive pack
  2 files, 345 bytes before compression
packed C:\work\Greetings\bin\Greetings-2.2.hive (1091 bytes)
$ larva hive verify bin/Greetings-2.2.hive
Ana/Greetings 2.2 (source): 2 files, 345 bytes
  signed by a59d969b683ba7f9 (not checked: give --key)
  every file matches its hash

A package without sources

A package can carry a library built elsewhere, such as a binding to a native library. It compiles no sources (scan: false) and names the compiled binding and the native library in DEPS. The SDL3 package:

queen 1.0;

chunk PROJ:
   name: SDL3,
   type: library,
   version: v3.5.0,
   author: "Antril Organization",
   description: "SDL 3.5 for Larva: windows, rendering, input, audio and more (SDL3.dll included)."

chunk SOURCES:
   scan: false

chunk DEPS:
   assembly: ../SDL.Bindings.dll,
   lib: ../build/SDL3.dll

chunk HIVE:
   package: Antril-Organization/SDL3,
   license: Zlib,
   sign: hive.key

The package then holds:

hive.json
hive.sig
lib/SDL.Bindings.dll
native/SDL3.dll
package.queen

and its package.queen says:

queen 1.0;

chunk PROJ:
   name: SDL3,
   type: library,
   version: v3.5.0,
   author: Antril-Organization

chunk SOURCES:
   scan: false

chunk DEPS:
   assembly: "lib/SDL.Bindings.dll",
   lib: "native/SDL3.dll"

A project that adds Antril-Organization/SDL3 compiles against the binding, and SDL3.dll is copied next to its program.