llar Build Matrix

An LLAR build matrix describes the artifact variants of one module version. Different matrix selections may change dependencies, build flags, commands, or installed output, so each effective selection identifies a separate artifact.

Relationship to Go Build Constraints

LLAR matrix selection is inspired by Go build constraints. Both allow one source tree to respond to build conditions, and each package uses only the conditions that affect it.

Go build constraints select source files for one compilation. LLAR matrix values select complete build combinations:

os=linux, arch=amd64, shared=OFF
os=linux, arch=arm64, shared=OFF
os=linux, arch=amd64, shared=ON

Each LLAR combination may produce a different reusable artifact.

Matrix

type Matrix struct {
    Require        map[string][]string
    Options        map[string][]string
    DefaultOptions map[string][]string
}

Require contains build-environment dimensions that propagate to dependencies, such as os, arch, ABI, libc, or toolchain. Dependencies that use the same dimension must select compatible values.

Options contains package-specific features such as shared, debug, zlib, or tests. An option affects only formulae that use it; it does not expand the artifact matrix of unrelated dependencies.

A build request supplies a flat set of matrix values. Formula usage determines whether a key is consumed through target.require or target.options.

Formula callbacks read the active selection through target:

if slices.contains(target.require["os"], "linux") {
    ...
}

if slices.contains(target.options["shared"], "ON") {
    ...
}

Defaults

defaults provides option values omitted by the request:

defaults {
    "debug": "OFF",
    "shared": "OFF",
}

Requested values override defaults with the same key. Defaults do not set required dimensions or declare every legal option value. The resolved default selection is the default prebuild combination.

Dependency Propagation

Given this request:

os=linux, arch=arm64, zlib=ON

if pnggroup/libpng uses the zlib option and depends on madler/zlib, their effective matrices are:

pnggroup/libpng: os=linux, arch=arm64 | zlib=ON
madler/zlib:     os=linux, arch=arm64

Required dimensions propagate across the dependency edge. The package option remains only where it changes build behavior. Unused request keys are not part of that module's artifact identity.

Combinations

Matrix dimensions form combinations through their Cartesian product:

os:     [linux, darwin]
arch:   [amd64, arm64]
shared: [ON, OFF]

2 x 2 x 2 = 8 artifact variants

The matrix defines distinct variants. Build policy decides which variants are prebuilt and which are built on demand.