kiwi

Documentation

Overview

Package kiwi provides utilities for interacting with the kiwi-ng image builder tool.

Index

• Constants
• func CheckPrerequisites(ctx opctx.Ctx) error
• func ParseResult(fs opctx.FS, targetDir string) ([]string, error)
• type RepoOptions
• type RepoSourceType
• type ResultEntry
• type Runner
  • func NewRunner(ctx opctx.Ctx, descriptionDir string) *Runner
  • func (r *Runner) AddLocalRepo(repoPath string, options *RepoOptions) *Runner
  • func (r *Runner) AddRemoteRepo(repoURI string, options *RepoOptions) error
  • func (r *Runner) Build(ctx context.Context) error
  • func (r *Runner) Clone() *Runner
  • func (r *Runner) DescriptionDir() string
  • func (r *Runner) Profile() string
  • func (r *Runner) TargetArch() string
  • func (r *Runner) TargetDir() string
  • func (r *Runner) WithProfile(profile string) *Runner
  • func (r *Runner) WithTargetArch(arch string) *Runner
  • func (r *Runner) WithTargetDir(targetDir string) *Runner

Constants

const (
	// KiwiBinary is the name of the kiwi executable.
	KiwiBinary = "kiwi"

	// ResultFilename is the name of the JSON result file that kiwi-ng produces.
	ResultFilename = "kiwi.result.json"
)

Functions

func CheckPrerequisites

func CheckPrerequisites(ctx opctx.Ctx) error

CheckPrerequisites verifies that required tools are available for running kiwi-ng. This checks for sudo, kiwi, and sgdisk (used by kiwi for disk partitioning).

func ParseResult

func ParseResult(fs opctx.FS, targetDir string) ([]string, error)

ParseResult reads and parses the kiwi result JSON file from the given target directory to get artifact paths. Returns a slice of absolute paths to the built artifacts.

Types

type RepoOptions

type RepoOptions struct {
	// Alias is a descriptive name for the repository. If empty, a default alias
	// is generated (e.g., "local-1", "remote-1").
	Alias string

	// Priority is the repository priority number. If 0, a default is used
	// (1 for local repos, 50 for remote repos). Lower numbers mean higher priority.
	Priority int

	// ImageInclude sets imageinclude=true, indicating the repository is part of the
	// system image repository setup. If false, the field is omitted (kiwi-ng default).
	ImageInclude bool

	// DisablePackageGPGCheck explicitly sets package_gpgcheck=false, disabling package
	// signature validation. If false, the field is omitted (kiwi-ng default).
	DisablePackageGPGCheck bool

	// SigningKeys is a list of signing key URIs. Each key must be in URI format.
	// If empty, the field is omitted.
	SigningKeys []string

	// DisableRepoGPGCheck explicitly sets repo_gpgcheck=false, disabling repository
	// signature validation. If false, the field is omitted (kiwi-ng default).
	DisableRepoGPGCheck bool

	// SourceType specifies how the source path is interpreted.
	// If empty ([RepoSourceTypeDefault]), the field is omitted (kiwi-ng defaults to baseurl).
	SourceType RepoSourceType
}

RepoOptions configures per-repository settings for kiwi-ng's --add-repo flag. Fields use Go zero values to indicate "use the kiwi-ng default" (the field is omitted from the --add-repo value). Non-zero values explicitly set the corresponding field.

The fields correspond to the positional parameters in kiwi-ng's --add-repo format:

<source>,<type>,<alias>,<priority>,<imageinclude>,<package_gpgcheck>,
{signing_keys},<components>,<distribution>,<repo_gpgcheck>,<repo_sourcetype>

See: https://osinside.github.io/kiwi/commands/system_build.html

type RepoSourceType

type RepoSourceType string

RepoSourceType specifies how kiwi-ng interprets the repository source path.

const (
	// RepoSourceTypeDefault uses the kiwi-ng default (baseurl).
	RepoSourceTypeDefault RepoSourceType = ""

	// RepoSourceTypeBaseURL interprets the source path as a simple URI.
	RepoSourceTypeBaseURL RepoSourceType = "baseurl"

	// RepoSourceTypeMetalink interprets the source path as a metalink URI.
	RepoSourceTypeMetalink RepoSourceType = "metalink"

	// RepoSourceTypeMirrorlist interprets the source path as a mirrorlist file.
	RepoSourceTypeMirrorlist RepoSourceType = "mirrorlist"
)

type ResultEntry

type ResultEntry struct {
	Filename     string `json:"filename"`
	Compress     bool   `json:"compress"`
	Shasum       bool   `json:"shasum"`
	UseForBundle bool   `json:"use_for_bundle"` //nolint:tagliatelle // kiwi-ng uses snake_case
}

ResultEntry represents a single artifact entry in kiwi's result JSON. The JSON tags match kiwi-ng's output format which uses snake_case.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner encapsulates options for invoking kiwi-ng.

func NewRunner

func NewRunner(ctx opctx.Ctx, descriptionDir string) *Runner

NewRunner constructs a new Runner that can be used to invoke kiwi-ng. The descriptionDir is the directory containing the kiwi description file (e.g., config.xml).

func (*Runner) AddLocalRepo

func (r *Runner) AddLocalRepo(repoPath string, options *RepoOptions) *Runner

AddLocalRepo adds a path to a local RPM repository to include during build. Local repositories are added with highest priority (priority 1 by default). Pass nil for options to use all defaults.

func (*Runner) AddRemoteRepo

func (r *Runner) AddRemoteRepo(repoURI string, options *RepoOptions) error

AddRemoteRepo adds a URI to a remote RPM repository (http:// or https://) to include during build. Remote repositories are added with lower priority than local repositories (priority 50 by default). Pass nil for options to use all defaults. Returns an error if the URI is invalid or uses an unsupported scheme.

func (*Runner) Build

func (r *Runner) Build(ctx context.Context) error

Build invokes kiwi-ng via sudo to build an image.

func (*Runner) Clone

func (r *Runner) Clone() *Runner

Clone creates a deep copy of the provided Runner instance.

func (*Runner) DescriptionDir

func (r *Runner) DescriptionDir() string

DescriptionDir retrieves the description directory configured for this Runner.

func (*Runner) Profile

func (r *Runner) Profile() string

Profile retrieves the kiwi profile configured for this Runner.

func (*Runner) TargetArch

func (r *Runner) TargetArch() string

TargetArch retrieves the target architecture configured for this Runner.

func (*Runner) TargetDir

func (r *Runner) TargetDir() string

TargetDir retrieves the target directory configured for this Runner.

func (*Runner) WithProfile

func (r *Runner) WithProfile(profile string) *Runner

WithProfile sets the profile that kiwi will use to build the image.

func (*Runner) WithTargetArch

func (r *Runner) WithTargetArch(arch string) *Runner

WithTargetArch sets the target architecture to build for (e.g., "x86_64" or "aarch64"). If left empty, the host architecture will be used.

func (*Runner) WithTargetDir

func (r *Runner) WithTargetDir(targetDir string) *Runner

WithTargetDir sets the target directory where kiwi will write build output.