Proposal: Artifact-oriented build variant interface

[MeteorsLiu]

Proposal: Artifact-oriented build variant interface

1. Summary

LLAR should describe selectable build variants in terms of the artifact a consumer receives, rather than exposing upstream CMake, Autotools, Meson, or Make parameters as its stable public interface.

Formulae may still use the upstream build parameters directly when producing an artifact. Those parameters are implementation and provenance facts. The stable LLAR selection surface should contain only properties that materially change how the resulting artifact is consumed.

This proposal establishes that boundary. It does not define the final CLI or Formula syntax.

2. User Stories / Motivation

1. As an LLAR user, I want to select an available artifact for a module, upstream version, and target platform without first learning that project's build-system variables.
2. As an LLAR user, I want llarhub to show which artifact variants actually exist and generate an install or build command for one concrete variant.
3. As a Formula author, I want to follow upstream build-system changes without making those internal variable names a permanent LLAR consumer contract.
4. As a maintainer debugging a build, I want the exact upstream parameters recorded so the artifact can be explained and reproduced.

The common need is a stable consumer-facing artifact identity with complete producer-side build provenance.

3. Current Situation

Formulae currently expose LLAR options and translate them into upstream build parameters. For example, the cglm Formula represents one consumer choice as:

shared=ON

and implements it with two upstream CMake values:

CGLM_SHARED=ON
CGLM_STATIC=OFF

Passing every upstream parameter through unchanged would remove this mapping, but it would also expose build implementation details and allow contradictory inputs such as enabling both the static and shared modes.

The opposite extreme, a large cross-project option vocabulary like Conan's, would require LLAR to define and maintain abstractions for project-specific choices that may not be shared by other modules.

Related work:

• Homebrew and Conan Artifact Research #121 researches Homebrew and Conan artifact and consumer metadata models.
• Proposal: Add customized matrix cli #113 defines the current matrix CLI transport.
• Proposal: Cloud Build #118 defines cloud artifact requests keyed by module, version, and matrix.
• LLARHub Website Design llarhub#220 tracks the llarhub website design.

4. Goals

• Keep upstream build-system parameters out of LLAR's stable consumer API.
• Expose only properties that distinguish consumer-visible artifact variants.
• Preserve exact upstream build parameters as build provenance.
• Let llarhub list real, available artifact variants instead of claiming to enumerate every legal upstream build configuration.
• Keep environment requirements such as OS, architecture, ABI, libc, and toolchain ownership separate from package-specific artifact properties.

5. Out of Scope

• Defining a universal catalog of LLAR package options.
• Enumerating every CMake cache variable or other upstream build parameter.
• Defining the final CLI, Formula DSL, artifact metadata schema, or llarhub UI.
• Removing Formula responsibility for dependency resolution. An upstream name such as ZLIB still has to resolve to an LLAR module such as madler/zlib.
• Deciding whether local source builds have an unstable raw-parameter escape hatch.
• Migrating existing Formulae in this proposal.

6. Proposal

6.1 Design Rule

The stable LLAR variant interface describes the resulting artifact, not the upstream build invocation.

For example, a consumer may need to distinguish these artifacts:

target: linux/arm64
linkage: static

The Formula remains responsible for producing that artifact with the correct upstream parameters:

CGLM_SHARED=OFF
CGLM_STATIC=ON
CGLM_USE_TEST=OFF

The first block is consumer-facing selection. The second block is Formula-owned build implementation.

6.2 Ownership Boundaries

Area	Owner	Responsibility
Target environment	LLAR	OS, architecture, ABI, libc/sysroot, and toolchain preparation
Artifact properties	Formula contract	Consumer-visible differences between published variants
Upstream build invocation	Formula	Exact CMake, Autotools, Meson, Make, or custom command parameters
Dependency graph	Formula and module loader	Resolve upstream dependency names to LLAR modules before building
Artifact identity and provenance	Build/artifact layer	Canonical selected variant plus the exact inputs that produced it
Available-build catalog	llarhub	List variants that have actually been published and verified

6.3 llarhub Behavior

llarhub should present available builds, not a speculative list of upstream build options. A module version may show entries such as:

linux/amd64 - static - verified
linux/amd64 - shared - verified
darwin/arm64 - static - not published

The exact upstream build parameters may be visible in an expanded build-details or provenance view, but they are not the primary selection interface.

7. Compatibility

This issue proposes a design boundary only. It does not change current CLI, Formula, matrix, cache, or artifact behavior by itself.

Any implementation must define how existing target.options Formulae are interpreted or migrated. That migration must remain compatible with both the source-based llar make path and the cloud-backed artifact path.

8. Alternatives Considered

Expose upstream parameters directly

This removes Formula-level naming and value mapping, but makes build-system details part of LLAR's public API. Upstream parameter renames become consumer breakages, and related parameters can admit contradictory selections.

Standardize all options across packages

This gives users a consistent vocabulary, but moves project-specific policy into LLAR and requires Formula authors to maintain a second option schema.

Publish only one fixed artifact per target

This avoids an option interface entirely and remains valid for modules with one canonical output. It does not cover libraries where multiple consumer-visible artifacts are intentionally published.

9. Open Questions

• What is the minimum initial set of artifact properties, if any, beyond the existing target environment?
• Should artifact properties be explicitly declared by a Formula or derived from published artifact metadata?
• How should a Formula express valid combinations without recreating a general package-option schema?
• Should llar make support raw upstream parameters as an explicitly unstable local-build feature?
• Which provenance facts must participate in artifact and cache identity?

10. Acceptance Criteria For The Design

• A user can identify and select a published artifact without seeing upstream build-system variables.
• Formula authors can record the exact parameters used to produce the artifact.
• Contradictory upstream settings cannot be expressed as a single valid published variant.
• llarhub can distinguish published, verified, missing, and unknown variants.
• The design works for both local Formula execution and cloud artifact reuse.