Usar paquetes

Hive es el gestor de paquetes de Larva, integrado en larva como larva hive. Un paquete es una biblioteca con nombre Author/Name (por ejemplo Antril-Organization/SDL3). Vive en un registro de paquetes: el público en https://www.antril.org/hive-api, otro servidor HTTPS o una carpeta.

[project] es un archivo .queen o una carpeta que contiene uno; si lo omites, se usa la carpeta actual. Cómo crear paquetes se explica en Publicar paquetes.

Elige un registro de paquetes

Un proyecto indica sus registros de paquetes con provider: en su chunk HIVE:

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

Un proyecto que no indica ninguno usa la configuración de tu máquina. Los instaladores la apuntan al registro público, salvo que hayas elegido --no-hive:

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

Varios registros se separan con comas, sin espacios: Hive los prueba en orden y toma cada paquete del primero que lo tenga. Un proveedor puede ser:

Una carpeta es un registro completo: consulta la estructura del registro. Resulta práctica para una carpeta compartida del equipo, o para probar paquetes sin red.

Agrega un paquete

Desde la carpeta del proyecto:

$ 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

Esto agrega la dependencia al archivo .queen (y un chunk DEPS si no hay uno):

chunk DEPS:
   package: Ana/Greetings@^1.0

A partir de ahí, el programa puede usar los espacios de nombres del paquete:

import System;
import Greetings;

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

$ larva run
Hello, Hive!

larva build y larva run usan los paquetes instalados y nunca acceden a la red; el editor hace lo mismo. Un paquete que no está instalado produce un error que indica qué ejecutar:

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`)

Para escribir la entrada package: a mano, ponla en DEPS (consulta DEPS) y ejecuta larva hive install.

Versiones

Una entrada package: puede indicar, después de @, qué versiones le sirven:

Se permite una v antes del número (@^v1.2). Las partes que faltan cuentan como cero, así que 1.2 y 1.2.0 son la misma versión.

Para cada paquete, Hive elige la versión más reciente que cumple todos los requisitos: los del proyecto y los de los paquetes que este usa. Cuando no se pueden cumplir todos, indica quién pide qué:

$ 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 escribe la entrada antes de instalar, así que después de un error como este, corrige o quita la entrada en el archivo .queen.

Un paquete sin código fuente

Algunos paquetes traen una biblioteca compilada en otro lugar en vez de código fuente de Antril, como un binding a una biblioteca nativa (por ejemplo Antril-Organization/SDL3). Se usan como cualquier otro paquete: larva hive add los instala, y larva build compila contra su biblioteca y copia su biblioteca nativa junto al programa. Cómo crear uno se explica en Publicar paquetes.

Qué tiene un registro de paquetes

$ 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

Cada línea es una versión, la clave que la firmó (los primeros 16 dígitos de su huella) y los paquetes que necesita. Una versión yanked fue retirada por su autor: Hive no la elige, salvo que hive.lock ya la fije. Cuando ningún registro tiene el paquete, info lo indica y termina con el código de salida 1.

hive.lock

larva hive install escribe hive.lock junto al archivo .queen. Para cada paquete fija la versión, el SHA-256 de su archivo, su clave de firma, el registro del que vino y lo que necesita:

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

Guárdalo junto con tu código fuente. Mientras una versión fijada siga cumpliendo los requisitos, larva hive install la conserva, aunque existan versiones más nuevas. Para pasar a las versiones más recientes, borra hive.lock e instala de nuevo:

$ 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 instala exactamente lo que dice hive.lock y rechaza un archivo cuyo hash no sea el que fijó. Úsalo en una máquina nueva o en un servidor de compilación:

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

La caché

Los paquetes instalados se guardan en la caché de Hive del usuario, una carpeta por versión (packages/Author/Name/Version), desempaquetados y verificados. Un paquete que ya está ahí con el mismo archivo no se vuelve a descargar.

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

Qué se verifica al instalar

Instalar no ejecuta nada del paquete: descarga, verifica y desempaqueta. Para cada paquete:

• El SHA-256 del archivo debe ser el que da el índice del registro (y, para restore, el que fija hive.lock).
• El archivo debe ser un paquete válido: un manifiesto, hive.json, que enumera cada archivo con su tamaño y su SHA-256; cada archivo debe coincidir; no puede haber nada más; ninguna ruta puede salir de la carpeta del paquete; y el paquete debe respetar los límites de tamaño (512 MB desempaquetado, 20.000 archivos).
• El paquete debe ser el que se pidió: el nombre y la versión del manifiesto deben ser los del índice.
• La firma (ECDSA P-256 sobre el manifiesto) debe corresponder a la clave que el índice da para esa versión.
• La clave debe ser una en la que confíes para ese paquete (ver más abajo).

De forma predeterminada, los paquetes deben estar firmados. Un proyecto que acepta paquetes sin firmar lo indica con verify: hashes en HIVE: los hashes se siguen verificando, pero las firmas no son obligatorias.

$ 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

Un archivo que fue modificado se rechaza:

$ 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

Claves de confianza

La primera clave con la que se instala un paquete queda registrada en la caché (keys.json). Una versión posterior firmada por otra clave se rechaza, incluso si viene de otro registro:

$ 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`

Cuando el autor te avise que cambió de clave (confirma la huella con él), acepta la nueva:

$ 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

La clave anterior sigue siendo de confianza. Una huella es el SHA-256 de la clave pública: 64 dígitos hexadecimales.

Mira dentro de un archivo de paquete

larva hive verify verifica un archivo .hive igual que al instalar, e indica qué contiene:

$ 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

Con --key y la clave pública del autor (en base64, como la imprime larva hive key), también verifica la firma:

$ 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

Los paquetes compiled traen bibliotecas de Larva compiladas para un modo de GC (aquí default); los paquetes source traen código fuente y se compilan con tu proyecto. Consulta Paquetes compilados y de código fuente.