llar Artifact Binary Format

LLAR Binary Artifact

Archive

artifact.tar.gz
  .llar/
    metadata.json
  ...

The default archive type is tar.gz. The archive root is the artifact install directory. .llar/ is reserved for LLAR files. Other files are package payload.

C/C++ example:

artifact.tar.gz
  .llar/
    metadata.json
  include/
    zlib.h
    zconf.h
  lib/
    libz.a
    pkgconfig/
      zlib.pc

GHCR Storage

GHCR stores LLAR artifacts as OCI artifacts. One package stores all versions of one module. One tag stores all matrix variants of one version.

package = ghcr.io/<owner>/<module>
tag     = <version>
matrix  = OCI index manifest annotation org.llar.matrix = <MatrixStr>
blob    = artifact archive layer

Storage layout:

ghcr.io/<owner>/<module>:<version>
  OCI image index
    manifest entry
      annotations:
        org.llar.matrix = <MatrixStr>
      platform:
        os           = <os>
        architecture = <arch>
      image manifest
        layer
          media type = application/vnd.oci.image.layer.v1.tar+gzip
          content    = artifact.tar.gz

platform.os and platform.architecture should be filled when the selected matrix has those values. Artifact matching uses org.llar.matrix.

The artifact URL points to the archive blob:

https://ghcr.io/v2/<owner>/<module>/blobs/sha256:<digest>

llar install detects GHCR downloads from the URL host and uses GHCR download handling. Public GHCR blob downloads use:

Authorization: Bearer Qq==

.llar/metadata.json

{
  "metadata": "-I{{.InstallDir}}/include -L{{.InstallDir}}/lib -lz",
  "deps": [
    "madler/zlib@v1.3.1"
  ]
}

Field	Type	Required	Description
metadata	string	yes	LLAR build metadata, same semantic value as formula.BuildResult.Metadata().
deps	string[]	no	Artifact dependencies in module@version form.

No version field is defined.

Path Placeholder

Use {{.InstallDir}} for this artifact's install directory inside metadata.

/tmp/llard/work/madler/zlib/install/include
{{.InstallDir}}/include

llar install expands it to the local install directory before writing .cache.json.

Rules

Producer:

• archive the install directory as the archive root;
• include .llar/metadata.json;
• replace this artifact's build-time install directory with {{.InstallDir}}.

Installer:

• verify and extract the archive;
• read .llar/metadata.json;
• expand {{.InstallDir}};
• write metadata into .cache.json.

Invalid Artifacts

Case	Reason
missing .llar/metadata.json	no LLAR metadata
invalid .llar/metadata.json	cannot decode metadata
missing metadata	cannot determine this artifact's usage information, such as include paths and libraries, for the selected matrix