llard Service Specification

GET artifact

Request

GET /v1/artifacts/<module>@<version>?<matrix query>

• <module> — package module identifier (e.g. madler/zlib).
• <version> — version string (e.g. v1.3.1).
• <matrix query> — build matrix parameters (e.g. arch=amd64&os=linux&debug=false), used to select a specific build variant of the artifact.

Examples:

GET /v1/artifacts/madler/zlib@v1.3.1?arch=amd64&os=linux
GET /v1/artifacts/pnggroup/libpng@v1.6.47?arch=amd64&os=linux&debug=false

Response

• Content type: application/x-cmdjsonl. See github.com/qiniu/x/cmdjsonl for the line format (Command <space> JSON object, newline-delimited).

The response is a stream of commands, each on its own line, describing the progress and result of resolving and building the requested artifact. Three commands are currently supported: info, error, and artifact.

info

Reports human-readable progress information about the build process. Carries a single string payload.

info "fetching source for madler/zlib@v1.3.1"
info "configuring build (arch=amd64, os=linux)"
info "compiling..."

• Payload: a JSON string containing a free-form, human-readable message.
• Clients may display these messages to the user as progress updates but should not depend on their content for control flow.
• Multiple info lines may be emitted over the course of a single response.

error

Reports an error encountered while resolving or building the artifact. Carries a single string payload.

error "module madler/zlib@v1.3.1 not found"
error "build failed: missing dependency pnggroup/libpng"

• Payload: a JSON string containing a human-readable error message.
• An error line indicates the request has failed. No artifact line should be expected for the failing module after this point.
• A response may still contain artifact lines for dependencies that were successfully resolved before the error occurred.

artifact

Reports a successfully resolved/built artifact, including its location and (optionally) its dependency graph.

artifact {"id": "<module-id>", "type": "zip | tar.gz | ...", "source": {"type": "<artifact-source-type>", "url": "<artifact-binary-download-url>"}, "deps": ["<dep-module-id1>", "<dep-module-id2>", ...]}

Fields:

Field	Type	Required	Description
id	string	yes	The module ID of this artifact, in the form <module>@<version>?<matrix query> (e.g. madler/zlib@v1.3.1?arch=amd64&os=linux). This is the same identifier format used in the request path/query.
type	string	yes	The archive format of the artifact binary, e.g. "zip", "tar.gz".
source	object	yes	Download source for the artifact binary.
source.type	string	yes	Artifact source type, e.g. "ghcr".
source.url	string	yes	Download URL for the artifact binary, in the format/archive given by type.
deps	string[]	no	A list of module IDs (same <module>@<version>?<matrix query> format as id) that this artifact depends on. If omitted or empty, the artifact has no dependencies. Each dependency should itself appear as a separate artifact line in the response (possibly with its own deps).

Every artifact archive contains LLAR metadata at .llar/metadata.json:

{
  "metadata": "-I{{.InstallDir}}/include -L{{.InstallDir}}/lib -lz"
}

{{.InstallDir}} is replaced with the local install directory after extraction.

C/C++ archive layout example:

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

Notes:

• A single response may contain multiple artifact lines: one for the requested module, and one for each (transitive) dependency in its build graph.
• There is no fixed ordering requirement between artifact lines, but dependencies are typically emitted before or alongside the modules that depend on them.
• id and entries in deps use the module-id format <module>@<version>?<matrix query>, exactly as used to address artifacts via GET /v1/artifacts/<module>@<version>?<matrix query>. This allows clients to recursively resolve any dependency by issuing the same kind of request against its id.
• deps is optional. Artifacts with no dependencies may omit the field entirely.

Example response streams

Artifact with no dependencies:

info "resolving madler/zlib@v1.3.1 (arch=amd64, os=linux)"
info "no dependencies required"
artifact {"id": "madler/zlib@v1.3.1?arch=amd64&os=linux", "type": "tar.gz", "source": {"type": "ghcr", "url": "https://ghcr.io/v2/llar-artifacts/madler/zlib/blobs/sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"}}

Artifact with dependencies:

info "resolving pnggroup/libpng@v1.6.47 (arch=amd64, os=linux, debug=false)"
info "dependency required: madler/zlib"
artifact {"id": "madler/zlib@v1.3.1?arch=amd64&os=linux&debug=false", "type": "tar.gz", "source": {"type": "ghcr", "url": "https://ghcr.io/v2/llar-artifacts/madler/zlib/blobs/sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"}}
info "compiling libpng..."
artifact {"id": "pnggroup/libpng@v1.6.47?arch=amd64&os=linux&debug=false", "type": "tar.gz", "source": {"type": "ghcr", "url": "https://ghcr.io/v2/llar-artifacts/pnggroup/libpng/blobs/sha256:486ea46224d1bb4fb680f34f7c9ad96a8f24ec88be73ea8e5a6c65260e9cb8a7"}, "deps": ["madler/zlib@v1.3.1?arch=amd64&os=linux&debug=false"]}

Error response:

info "resolving unknown/foo@v1.0.0"
error "module unknown/foo@v1.0.0 not found"