gentooling

package module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 30, 2026 License: GPL-3.0-only Imports: 16 Imported by: 0

README

gentooling

Reusable Go libraries for Gentoo system and package tooling.

The initial API provides explicit system paths, stable package identities, and read-only installed-package inventory. Inventory scans support partial inspection with typed diagnostics and strict evidence validation for consumers that must not act on incomplete package-manager state. Independent package records are scanned and revalidated with bounded concurrency while results and diagnostics remain deterministic.

paths := gentooling.DefaultSystemPaths("/")
inventory, err := gentooling.ReadInstalled(ctx, paths, gentooling.InstalledOptions{
    Integrity: gentooling.RequireComplete,
})

profile, err := gentooling.ReadProfile(ctx, gentooling.SystemPaths{
    ActiveProfile: "/etc/portage/make.profile",
    Repositories: []gentooling.RepositoryPath{
        {Name: "gentoo", Path: "/var/db/repos/gentoo"},
    },
})

config, err := gentooling.ReadEffectiveConfig(ctx, paths, gentooling.ConfigOptions{
    Environment: os.Environ(),
})

atom, err := gentooling.ParseAtom(">=sys-kernel/gentoo-sources-6.12:6.12")
matches, err := atom.Matches(packageID, gentooling.UseState{})

use, err := config.EvaluateUse(ctx, gentooling.PackageContext{
    ID: packageID,
    DeclaredUse: installedPackage.DeclaredUse,
    Stable: true,
})

selections, err := gentooling.ReadSelections(ctx, paths)

snapshot, err := gentooling.ReadSystemSnapshot(ctx, paths, gentooling.SnapshotOptions{
    Installed: gentooling.InstalledOptions{
        Integrity: gentooling.RequireComplete,
    },
    Config: gentooling.ConfigOptions{
        Environment: os.Environ(),
    },
})

Environment is always explicit. Passing nil performs a disk-only evaluation and never imports the process environment.

Atom matching returns false, nil for an ordinary mismatch and wraps malformed input with ErrInvalidData. Effective USE evaluation only returns declared flags, sorts decisions by name, and retains applied evidence in policy precedence order. Consumers decide whether a package is stable and pass that decision explicitly.

ReadSystemSnapshot observes the Portage-compatible VDB and world fcntl locks used by Portage and Arise, then requires two consecutive complete observations to agree. This also detects configuration edits and non-cooperating writers which do not honor those locks. The call waits for cooperating writers, respects context cancellation, retries a bounded number of observations, and returns ErrConcurrentMutation rather than a mixed view when state does not stabilize.

ReadSelections independently observes the world lock while reading user selections. Profile policy remains protected by validation rather than a package-manager transaction lock because administrator edits do not participate in that lock protocol.

Run the complete validation target with:

make test

Gentooling is an interoperable library. It does not execute, replace, or modify Portage and its surrounding tools.

See COMPATIBILITY.md for the pre-1.0 API policy.

License

Gentooling is licensed under the GNU General Public License, version 3. See LICENSE.

Acknowledgment

The name Gentooling is inspired by Gentoolkit and acknowledges the established Gentoo package-tooling ecosystem that made this work possible. Gentooling is an independent project: it is not affiliated with Gentoolkit and is intended to work alongside existing Gentoo tools, not replace them.

Documentation

Overview

Package gentooling provides read-only, interoperable Gentoo system and package-state primitives for Go applications.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrIncompleteEvidence = errors.New("gentooling: incomplete evidence")
	ErrInterruptedRecord  = errors.New("gentooling: interrupted package record")
	ErrCorruptRecord      = errors.New("gentooling: corrupt package record")
	ErrUnreadableRecord   = errors.New("gentooling: unreadable package record")
	ErrConcurrentMutation = errors.New("gentooling: concurrent mutation")
)
View Source 
var ErrInvalidData = errors.New("gentooling: invalid data")
View Source 
var ErrLockObservationUnsupported = errors.New("gentooling: Portage lock observation unsupported")
View Source 
var ErrProfileCycle = errors.New("gentooling: profile parent cycle")

Functions

func PortageStateLockPath added in v0.5.0 

func PortageStateLockPath(path string) string

PortageStateLockPath mirrors portage.locks.lockdir. A state path or directory is protected by a sibling .<basename>.portage_lockfile.

func SortedRepositoryNames 

func SortedRepositoryNames(repositories []RepositoryPath) []string

SortedRepositoryNames provides deterministic diagnostics for configured repository maps.

Types

type Atom 

type Atom struct {
	Op       Op
	Category string
	Package  string
	Version  *Version
	Slot     string
	Subslot  string
	SlotOp   SlotOp
	Repo     string
	UseFlags []UseFlag
}

Atom is a parsed Gentoo package dependency atom.

func Parse 

func Parse(raw string) (*Atom, error)

Parse accepts either a package atom or a bare CPV identity.

func ParseAtom 

func ParseAtom(raw string) (Atom, error)

ParseAtom parses a package dependency atom. A version requires an operator.

func ParsePackageAtom 

func ParsePackageAtom(raw string) (*Atom, error)

ParsePackageAtom is the pointer-returning compatibility form of ParseAtom.

func ParsePackageVersion 

func ParsePackageVersion(raw string) (Atom, error)

ParsePackageVersion parses a CPV. Unlike ParseAtom, it accepts a version without a dependency operator.

func (Atom) Matches 

func (atom Atom) Matches(packageID PackageID, use UseState) (bool, error)

Matches reports whether a package and its USE state satisfy the atom.

func (Atom) String 

func (atom Atom) String() string

type BuildMetadata 

type BuildMetadata struct {
	Time        int64
	ID          string
	Counter     int64
	PhaseEnvABI string
}

type ConfigOptions 

type ConfigOptions struct {
	// Environment is command input, not the process environment. Only
	// documented Portage variables and active USE_EXPAND variables are used.
	Environment []string
}

type DependencyMetadata 

type DependencyMetadata struct {
	Depend  string
	RDepend string
	BDepend string
	IDepend string
	PDepend string
}

type EffectiveConfig 

type EffectiveConfig struct {
	Variables         map[string]string
	Profile           *Profile
	ProfileUse        []FlagChange
	UserUse           []FlagChange
	CommandUse        []FlagChange
	UserPackageUse    []PackageFlagRule
	UseExpand         []string
	UseExpandHidden   []string
	UseExpandImplicit []string
}

func ReadEffectiveConfig 

func ReadEffectiveConfig(ctx context.Context, paths SystemPaths, options ConfigOptions) (EffectiveConfig, error)

ReadEffectiveConfig loads make.globals, the active profile graph, user make.conf/package.use, and an explicit command environment. It never reads the process environment or paths absent from SystemPaths.

func (EffectiveConfig) EvaluateUse 

func (config EffectiveConfig) EvaluateUse(ctx context.Context, packageContext PackageContext) (UseEvaluation, error)

EvaluateUse computes effective USE for one package. It only returns flags declared by IUSE and retains every applied policy input in precedence order.

type FlagChange 

type FlagChange struct {
	Name    string
	Enabled bool
	Source  PolicySource
	Layer   string
}

type InstalledInventory 

type InstalledInventory struct {
	Packages []InstalledPackage
	Issues   []Issue
}

func ReadInstalled 

func ReadInstalled(ctx context.Context, paths SystemPaths, options InstalledOptions) (InstalledInventory, error)

ReadInstalled reads Portage's installed-package database. AllowPartial returns stable records alongside typed issues. RequireComplete returns the same diagnostic result plus ErrIncompleteEvidence when any evidence is incomplete. The scan detects observed mutations without claiming an atomic snapshot in the absence of a package-manager transaction lock.

type InstalledOptions 

type InstalledOptions struct {
	Integrity       IntegrityMode
	IncludeContents bool
	// Workers bounds concurrent record reads. Zero chooses a safe runtime-based
	// default. Negative values are invalid.
	Workers int
	// contains filtered or unexported fields
}

type InstalledPackage 

type InstalledPackage struct {
	ID           PackageID
	EAPI         string
	EnabledUse   []string
	DeclaredUse  []UseDeclaration
	Dependencies DependencyMetadata
	Build        BuildMetadata
	Contents     string
}

type IntegrityError 

type IntegrityError struct {
	Issues []Issue
}

func (*IntegrityError) Error 

func (e *IntegrityError) Error() string

func (*IntegrityError) Unwrap 

func (e *IntegrityError) Unwrap() error

type IntegrityMode 

type IntegrityMode uint8
const (
	AllowPartial IntegrityMode = iota
	RequireComplete
)

type Issue 

type Issue struct {
	Code    IssueCode
	Path    string
	Package *PackageID
	Message string
	Cause   error
}

func (Issue) Error 

func (i Issue) Error() string

func (Issue) Unwrap 

func (i Issue) Unwrap() error

type IssueCode 

type IssueCode string
const (
	IssueMalformedIdentity  IssueCode = "malformed_identity"
	IssueInterruptedRecord  IssueCode = "interrupted_record"
	IssueCorruptRecord      IssueCode = "corrupt_record"
	IssueUnreadableRecord   IssueCode = "unreadable_record"
	IssueInvalidMetadata    IssueCode = "invalid_metadata"
	IssueConcurrentMutation IssueCode = "concurrent_mutation"
)

type Op 

type Op string

Op is a Gentoo package atom version operator. 

const (
	OpNone   Op = ""
	OpLess   Op = "<"
	OpLessEq Op = "<="
	OpEq     Op = "="
	OpEqGlob Op = "=*"
	OpTilde  Op = "~"
	OpGtEq   Op = ">="
	OpGt     Op = ">"
)

type PackageContext 

type PackageContext struct {
	ID          PackageID
	DeclaredUse []UseDeclaration
	Stable      bool
}

PackageContext is the package-specific evidence required for USE policy evaluation. Stable is explicit because keyword acceptance is consumer policy.

type PackageFlagRule 

type PackageFlagRule struct {
	Atom   string
	Flags  []string
	Source PolicySource
}

type PackageID 

type PackageID struct {
	Category   string
	Name       string
	Version    string
	Slot       string
	Subslot    string
	Repository string
}

PackageID is the stable identity of one package version.

func ParsePackageID 

func ParsePackageID(value string) (PackageID, error)

ParsePackageID parses a category/package-version identity. It deliberately does not accept dependency atom operators.

func (PackageID) CP 

func (p PackageID) CP() string

func (PackageID) CPV 

func (p PackageID) CPV() string

type PolicySource 

type PolicySource struct {
	Path string
	Line int
}

type Profile 

type Profile struct {
	ActivePath            string
	Directories           []string
	Layers                []ProfileLayer
	MakeDefaults          map[string]string
	System                []string
	PackageProvided       []string
	UseForce              []string
	UseMask               []string
	UseStableForce        []string
	UseStableMask         []string
	PackageUse            []PackageFlagRule
	PackageUseForce       []PackageFlagRule
	PackageUseMask        []PackageFlagRule
	PackageUseStableForce []PackageFlagRule
	PackageUseStableMask  []PackageFlagRule
}

func ReadProfile 

func ReadProfile(ctx context.Context, paths SystemPaths) (Profile, error)

ReadProfile loads the active Portage profile in root-to-leaf order. All cross-repository parents are resolved from explicit repository paths.

type ProfileLayer 

type ProfileLayer struct {
	Path                  string
	Parents               []string
	MakeDefaults          map[string]string
	System                []string
	PackageProvided       []string
	UseForce              []string
	UseMask               []string
	UseStableForce        []string
	UseStableMask         []string
	PackageUse            []PackageFlagRule
	PackageUseForce       []PackageFlagRule
	PackageUseMask        []PackageFlagRule
	PackageUseStableForce []PackageFlagRule
	PackageUseStableMask  []PackageFlagRule
}

type RepositoryPath 

type RepositoryPath struct {
	Name string
	// Path is the repository root containing profiles/, metadata/, and ebuilds.
	Path string
}

type Selection added in v0.5.0 

type Selection struct {
	Value  string
	Kind   SelectionKind
	Atom   *Atom
	Source PolicySource
}

Selection is one ordered world or system entry with source provenance.

type SelectionKind added in v0.5.0 

type SelectionKind uint8

SelectionKind distinguishes package atoms from named package sets. 

const (
	PackageSelection SelectionKind = iota
	SetSelection
)

type Selections added in v0.5.0 

type Selections struct {
	World  []Selection
	System []Selection
}

Selections contains explicit user world entries and effective profile system entries. Both slices are deterministic and independently owned.

func ReadSelections added in v0.5.0 

func ReadSelections(ctx context.Context, paths SystemPaths) (Selections, error)

ReadSelections reads the world file and active profile system selection.

type SlotOp 

type SlotOp string

SlotOp describes the rebuild semantics attached to an atom slot. 

const (
	SlotOpNone SlotOp = ""
	SlotOpEq   SlotOp = "="
	SlotOpStar SlotOp = "*"
)

type SnapshotOptions added in v0.5.0 

type SnapshotOptions struct {
	Installed InstalledOptions
	Config    ConfigOptions
	// Attempts is the maximum number of complete observations. Zero uses 3.
	Attempts int
	// contains filtered or unexported fields
}

SnapshotOptions configures one combined system-state observation.

type SystemPaths 

type SystemPaths struct {
	Root          string
	ConfigRoot    string
	VDB           string
	World         string
	MakeGlobals   string
	Repositories  []RepositoryPath
	ActiveProfile string
}

SystemPaths names every host location a Gentooling operation may inspect. Callers may use DefaultSystemPaths for a live system or provide fixture and alternate-root paths explicitly.

func DefaultSystemPaths 

func DefaultSystemPaths(root string) SystemPaths

type SystemSnapshot added in v0.5.0 

type SystemSnapshot struct {
	Installed  InstalledInventory
	Config     EffectiveConfig
	Selections Selections
}

SystemSnapshot is a mutually consistent view of installed packages, effective Portage policy, and world/system selections.

func ReadSystemSnapshot added in v0.5.0 

func ReadSystemSnapshot(ctx context.Context, paths SystemPaths, options SnapshotOptions) (SystemSnapshot, error)

ReadSystemSnapshot returns only after two consecutive complete observations agree while shared VDB and world locks exclude cooperating package-state writers. Persistent change is reported as ErrConcurrentMutation instead of returning mixed state.

type UseDecision 

type UseDecision struct {
	Name     string
	Enabled  bool
	Default  UseDefault
	Forced   bool
	Masked   bool
	Evidence []UseEvidence
}

UseDecision is the effective state and provenance for one declared flag.

type UseDeclaration 

type UseDeclaration struct {
	Name    string
	Default UseDefault
}

func (UseDeclaration) String 

func (d UseDeclaration) String() string

type UseDefault 

type UseDefault uint8
const (
	UseDefaultUnspecified UseDefault = iota
	UseDefaultEnabled
	UseDefaultDisabled
)

type UseEvaluation 

type UseEvaluation struct {
	Package   PackageID
	Decisions []UseDecision
}

UseEvaluation contains deterministic package-specific USE decisions.

func (UseEvaluation) Decision 

func (evaluation UseEvaluation) Decision(name string) (UseDecision, bool)

Decision returns a flag decision by name.

type UseEvidence 

type UseEvidence struct {
	Enabled bool
	Kind    string
	Source  PolicySource
	Layer   string
}

UseEvidence records one ordered input to an effective USE decision.

type UseFlag 

type UseFlag struct {
	Name        string
	Enabled     bool
	Conditional bool
	Equal       bool
	Negated     bool
	Default     *bool
}

UseDependency is one USE constraint attached to an atom.

type UseState 

type UseState struct {
	Enabled  map[string]bool
	Declared map[string]bool
	Caller   map[string]bool
}

UseState contains both enabled and declared USE state. Caller is used to evaluate conditional and equality dependencies.

type Version 

type Version struct {
	Raw      string
	Revision int
	// contains filtered or unexported fields
}

Version is a parsed Gentoo package version.

func ParseVersion 

func ParseVersion(raw string) (*Version, error)

ParseVersion parses a Gentoo version.

func (*Version) Compare 

func (version *Version) Compare(other *Version) int

Compare returns -1, 0, or 1 using Gentoo package version ordering.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.