xdef

README

xdef

Single source of truth for shared definitions used across all ctx42 modules: label names, environment variable names, placeholder values, and helpers for reading variables from a process environment slice.

Import

import "github.com/ctx42/xdef/pkg/xdef"

Variables

Each value has up to four matching name constants, one per column below:

• C42 env (Env*) — the runtime environment variable carrying the binary's provenance; pairs one-to-one with the ldflags var.
• OCI env (EnvImg*) — the container environment variable mirroring the OCI label.
• OCI label (Lab*) — the OCI Image Spec label stamped on the image.
• ldflags var (Var*) — the Go identifier go build -ldflags -X targets to inject the value at build time; build/SCM metadata only.

The C42_* and OCI_IMAGE_* variables overlap on several values on purpose: they describe two different build events. OCI_IMAGE_* carries the image's provenance, stamped when the image is built; C42_* carries the binary's provenance, injected when the binary is built. A binary built from commit A and later packaged into an image tagged v1.2.4 reports the binary's values in C42_* and the image's in OCI_IMAGE_*, and they may legitimately differ. Read OCI_IMAGE_* to answer "which image is this?" and C42_* to answer "which binary is this?".

Concept	C42 env	OCI env	OCI label	ldflags var
build date	C42_BUILD_DATE	OCI_IMAGE_CREATED	org.opencontainers.image.created	buildDate
version tag	C42_SCM_REV	OCI_IMAGE_VERSION	org.opencontainers.image.version	scmRev
commit hash	C42_SCM_HASH	OCI_IMAGE_REVISION	org.opencontainers.image.revision	scmHash
source repository	C42_SCM_REPO	OCI_IMAGE_SOURCE	org.opencontainers.image.source	scmRepo
working-tree state	C42_SCM_STATE	—	—	scmState
CI/CD identifier	C42_CCID	OCI_IMAGE_REF_NAME	org.opencontainers.image.ref.name	ccid
title / name	C42_PROJ_NAME	OCI_IMAGE_TITLE	org.opencontainers.image.title	—
authors	—	OCI_IMAGE_AUTHORS	org.opencontainers.image.authors	—
description	—	OCI_IMAGE_DESCRIPTION	org.opencontainers.image.description	—
base image	—	OCI_IMAGE_BASE_NAME	org.opencontainers.image.base.name	—

The project layout variables (C42_PROJ_ROOT_DIR, C42_PROJ_DIST_DIR, C42_PROJ_GO_IMP_SPEC) have no ldflags or OCI counterpart; project tooling sets them to point commands at the project.

xdef.VarScmRev // "scmRev"      -> -ldflags -X main.scmRev=v1.2.3
xdef.EnvScmRev // "C42_SCM_REV" -> environment variable read at runtime

Usage

Read image metadata from a container's environment, falling back to sensible defaults when the variables are absent:

env := os.Environ()

// Returns OCI_IMAGE_CREATED value, or current UTC time in RFC3339Nano
// format (truncated to millisecond precision) if not set.
created := xdef.Created(env)

// Returns OCI_IMAGE_REF_NAME value, or a unique "no-ccid-<timestamp>"
// tag if not set.
refName := xdef.ImgRefName(env)

Placeholder constants are provided for unknown build metadata:

labels := map[string]string{
    xdef.LabImgRev:     xdef.PhHash,
    xdef.LabImgVer:     xdef.PhRev,
    xdef.LabImgCreated: xdef.PhTime,
}

License

MIT — see LICENSE.