gentooling

package module
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Aug 4, 2026 License: GPL-3.0-only Imports: 19 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("/")
repositories, err := gentooling.ReadRepositories(ctx, paths)
candidateInventory, err := gentooling.ReadRepositoryCandidates(ctx, repositories,
    gentooling.CandidateOptions{Integrity: gentooling.RequireComplete})
kernelRequirements, err := gentooling.ReadKernelRequirements(ctx,
    candidateInventory.Candidates[0], repositories,
    gentooling.KernelRequirementOptions{Integrity: gentooling.AllowPartial})
evaluatedKernelRequirements, err := gentooling.EvaluateKernelRequirements(ctx,
    candidateInventory.Candidates[0], repositories,
    gentooling.KernelRequirementContext{
        Phase: "pkg_setup", KernelRelease: "6.12.31",
        EffectiveUSE: []string{"ssl"},
    })
modules, err := gentooling.ReadInstalledKernelModules(ctx, paths,
    gentooling.InstalledKernelModuleOptions{
        Integrity: gentooling.RequireComplete,
        TargetKernelRelease: "6.12.31",
    })
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)

newsState, err := gentooling.ReadNewsState(ctx, gentooling.NewsPaths{
    RepositoryName: "gentoo",
    NewsDirectory:  "/var/db/repos/gentoo/metadata/news",
    StateDirectory: "/var/lib/gentoo/news",
}, gentooling.NewsContext{
    Architecture: "amd64",
    Profile: "default/linux/amd64/23.0",
    InstalledPackages: installedIDs,
})

preserved, err := gentooling.ReadPreservedLibraries(ctx, "/",
    "/var/lib/portage/preserved_libs_registry")

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

prospective, err := snapshot.EvaluateCandidate(ctx, candidateID)

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.

Setting IncludeCandidates adds repository metadata to both stabilizing observations. SystemSnapshot.EvaluateCandidate then evaluates visibility and effective USE together from that captured policy and candidate state. Missing or ambiguous candidate evidence is an error rather than an implicit lookup outside the snapshot.

Alternate-root callers use the same absolute locations normally written in repos.conf; Gentooling rebases them beneath SystemPaths.Root and never consults the corresponding host paths. Repositories are returned master-before-child and are included in effective configuration and combined snapshots.

Repository candidate discovery reads Portage's evaluated metadata/md5-cache rather than executing ebuild shell code. It exposes version, repository, slot/subslot, EAPI, KEYWORDS, structured IUSE defaults, REQUIRED_USE, inherited eclasses, and dependency metadata. Scans are bounded, deterministic, symlink-safe, and report malformed, unreadable, or concurrently changing evidence through the same partial and strict integrity model as installed-package inventory.

Installed-package inventory preserves the VDB's REQUIRED_USE alongside its effective USE, declared IUSE, EAPI, and dependency metadata. Consumers can validate installed state without combining it with newer repository constraints.

Kernel requirement discovery and evaluation never source an ebuild or eclass. The evaluated API follows bounded static wrapper calls and computes variable state at each linux-info_pkg_setup or check_extra_config invocation. It supports multiline and local assignments, replacement and append flow, boolean USE branches, explicit target-kernel predicates, and demonstrably static arrays and loops. Unsupported active shell behavior remains explicit unresolved evidence; inactive branches and warning-only uncertainty do not block a complete active-path result. Merely inheriting linux-info is not unresolved evidence. No running-kernel, current-directory, or implicit Portage state is consulted.

Installed kernel-module inventory combines VDB INHERITED metadata with owned out-of-tree .ko artifacts. The target kernel release is explicit and is compared with the releases embedded in owned module paths. Gentooling never consults the running kernel implicitly.

Canonical multiline assignments in make.globals and make.conf, including quoted FEATURES blocks and backslash continuations, retain the source line of the assignment and reject incomplete input.

LockedAndStabilized is the default snapshot guarantee. Unprivileged inspection may explicitly request StabilizedLockless; Gentooling records that mode in the result and still requires consecutive agreeing observations. Failure to read a lock returns ErrStateLockUnavailable and never triggers an implicit lockless fallback.

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.

Prospective visibility evaluation combines the candidate's repository KEYWORDS with effective ACCEPT_KEYWORDS, matching package.accept_keywords rules, and repository/profile/user package.mask/package.unmask policy. Ordinary rejection is returned as a typed result with ordered evidence; malformed policy remains an error.

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 (
	ErrLockObservationUnsupported = errors.New("gentooling: Portage lock observation unsupported")
	ErrStateLockUnavailable       = errors.New("gentooling: Portage state lock unavailable")
	ErrCandidateNotFound          = errors.New("gentooling: repository candidate not found")
)
View Source 
var ErrInvalidData = errors.New("gentooling: invalid data")
View Source 
var ErrProfileCycle = errors.New("gentooling: profile parent cycle")
View Source 
var ErrRepositoryCycle = errors.New("gentooling: repository master 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 Applicability added in v0.10.0 

type Applicability string
const (
	Applicable    Applicability = "applicable"
	Inapplicable  Applicability = "inapplicable"
	Indeterminate Applicability = "indeterminate"
)

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 CandidateInventory added in v0.8.0 

type CandidateInventory struct {
	Candidates []RepositoryCandidate
	Issues     []Issue
}

func ReadRepositoryCandidates added in v0.8.0 

func ReadRepositoryCandidates(ctx context.Context, repositories []Repository, options CandidateOptions) (CandidateInventory, error)

ReadRepositoryCandidates reads evaluated repository metadata from metadata/md5-cache. It never evaluates ebuild shell code.

type CandidateOptions added in v0.8.0 

type CandidateOptions struct {
	Integrity IntegrityMode
	Workers   int
	// contains filtered or unexported fields
}

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 DynamicKernelEvidence added in v0.9.0 

type DynamicKernelEvidence struct {
	Expression          string
	Reason              string
	Conditions          []UseCondition
	ConditionExpression string
	AssignmentOperator  string
	Function            string
	Source              PolicySource
	Origin              string
	Severity            KernelRequirementSeverity
}

type EffectiveConfig 

type EffectiveConfig struct {
	Variables         map[string]string
	Repositories      []Repository
	Profile           *Profile
	ProfileUse        []FlagChange
	UserUse           []FlagChange
	CommandUse        []FlagChange
	UserPackageUse    []PackageFlagRule
	UseExpand         []string
	UseExpandHidden   []string
	UseExpandImplicit []string
	AcceptKeywords    []KeywordChange
	PackageKeywords   []PackageKeywordRule
	PackageMasks      []PackageMaskRule
	PackageUnmasks    []PackageMaskRule
}

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.

func (EffectiveConfig) EvaluateVisibility added in v0.6.0 

func (config EffectiveConfig) EvaluateVisibility(ctx context.Context, candidate PackageVisibilityContext) (VisibilityResult, error)

EvaluateVisibility applies package masks and effective keyword policy to a prospective package. Ordinary rejection is a typed result, not an error.

type EvaluatedKernelRequirement added in v0.10.0 

type EvaluatedKernelRequirement struct {
	Symbol             string
	Expectation        KernelConfigExpectation
	Severity           KernelRequirementSeverity
	Applicability      Applicability
	Conditions         []UseCondition
	Invocation         KernelCheckInvocation
	Source             PolicySource
	Origin             string
	AssignmentOperator string
}

type EvaluatedKernelRequirements added in v0.10.0 

type EvaluatedKernelRequirements struct {
	Package      PackageID
	Requirements []EvaluatedKernelRequirement
	Unresolved   []UnresolvedKernelRequirement
	Complete     bool
}

func EvaluateKernelRequirements added in v0.10.0 

func EvaluateKernelRequirements(ctx context.Context, candidate RepositoryCandidate, repositories []Repository, evaluation KernelRequirementContext) (EvaluatedKernelRequirements, error)

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 InstalledKernelModuleInventory added in v0.9.0 

type InstalledKernelModuleInventory struct {
	Packages []InstalledKernelModulePackage
	Issues   []Issue
}

func ClassifyInstalledKernelModules added in v0.9.0 

func ClassifyInstalledKernelModules(inventory InstalledInventory, targetKernelRelease string) InstalledKernelModuleInventory

ClassifyInstalledKernelModules derives module and rebuild state from a caller-owned installed inventory.

func ReadInstalledKernelModules added in v0.9.0 

func ReadInstalledKernelModules(ctx context.Context, paths SystemPaths, options InstalledKernelModuleOptions) (InstalledKernelModuleInventory, error)

ReadInstalledKernelModules classifies installed out-of-tree kernel-module packages from VDB eclass and file-ownership evidence. TargetKernelRelease is explicit; Gentooling never consults uname.

type InstalledKernelModuleOptions added in v0.9.0 

type InstalledKernelModuleOptions struct {
	Integrity           IntegrityMode
	Workers             int
	TargetKernelRelease string
}

type InstalledKernelModulePackage added in v0.9.0 

type InstalledKernelModulePackage struct {
	Package      PackageID
	Modules      []KernelModuleFile
	Evidence     []KernelModuleEvidence
	TargetKernel string
	Rebuild      KernelModuleRebuildState
	NeedsRebuild bool
}

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
	RequiredUse  string
	EnabledUse   []string
	DeclaredUse  []UseDeclaration
	Inherited    []string
	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"
	IssueDynamicKernelPolicy IssueCode = "dynamic_kernel_policy"
)

type KernelCheckInvocation added in v0.9.0 

type KernelCheckInvocation struct {
	Function            string
	Conditions          []UseCondition
	ConditionExpression string
	Source              PolicySource
	Origin              string
}

type KernelConfigExpectation added in v0.9.0 

type KernelConfigExpectation uint8
const (
	KernelConfigEnabled KernelConfigExpectation = iota
	KernelConfigDisabled
)

type KernelConfigRequirement added in v0.9.0 

type KernelConfigRequirement struct {
	Symbol              string
	Expectation         KernelConfigExpectation
	Severity            KernelRequirementSeverity
	Conditions          []UseCondition
	ConditionExpression string
	AssignmentOperator  string
	Function            string
	Source              PolicySource
	Origin              string
}

func (KernelConfigRequirement) Validate added in v0.9.0 

func (requirement KernelConfigRequirement) Validate() error

type KernelFunctionCall added in v0.10.0 

type KernelFunctionCall struct {
	Caller string
	Callee string
	Source PolicySource
}

type KernelModuleEvidence added in v0.9.0 

type KernelModuleEvidence struct {
	Kind  KernelModuleEvidenceKind
	Value string
}

type KernelModuleEvidenceKind added in v0.9.0 

type KernelModuleEvidenceKind string
const (
	KernelModuleOwnedFile      KernelModuleEvidenceKind = "owned_module_file"
	KernelModuleInheritedClass KernelModuleEvidenceKind = "inherited_module_eclass"
)

type KernelModuleFile added in v0.9.0 

type KernelModuleFile struct {
	Path          string
	KernelRelease string
}

type KernelModuleRebuildState added in v0.9.0 

type KernelModuleRebuildState string
const (
	KernelModuleRebuildNotEvaluated KernelModuleRebuildState = "not_evaluated"
	KernelModuleCurrent             KernelModuleRebuildState = "current"
	KernelModuleTargetMissing       KernelModuleRebuildState = "target_missing"
	KernelModuleNoArtifacts         KernelModuleRebuildState = "no_module_artifacts"
)

func (KernelModuleRebuildState) Validate added in v0.9.0 

func (state KernelModuleRebuildState) Validate() error

type KernelRequirementContext added in v0.10.0 

type KernelRequirementContext struct {
	Phase         string
	KernelRelease string
	Architecture  string
	MergeType     MergeType
	InstalledUSE  []string
	EffectiveUSE  []string
}

type KernelRequirementOptions added in v0.9.0 

type KernelRequirementOptions struct {
	Integrity IntegrityMode
}

type KernelRequirementSet added in v0.9.0 

type KernelRequirementSet struct {
	Package      PackageID
	Requirements []KernelConfigRequirement
	Dynamic      []DynamicKernelEvidence
	Invocations  []KernelCheckInvocation
	Calls        []KernelFunctionCall
}

func ReadKernelRequirements added in v0.9.0 

func ReadKernelRequirements(ctx context.Context, candidate RepositoryCandidate, repositories []Repository, options KernelRequirementOptions) (KernelRequirementSet, error)

ReadKernelRequirements extracts conservative static Kconfig evidence from an ebuild and its inherited eclasses. Shell is never executed. Any runtime check or expression that cannot be represented statically is retained as Dynamic evidence for the consumer to resolve or reject.

type KernelRequirementSeverity added in v0.9.0 

type KernelRequirementSeverity uint8
const (
	KernelRequirementFatal KernelRequirementSeverity = iota
	KernelRequirementWarning
)

type KeywordChange added in v0.6.0 

type KeywordChange struct {
	Keyword string
	Enabled bool
	Source  PolicySource
	Layer   string
}

KeywordChange is one ordered ACCEPT_KEYWORDS policy operation.

type MergeType added in v0.10.0 

type MergeType string
const (
	MergeSource    MergeType = "source"
	MergeBinary    MergeType = "binary"
	MergeBuildOnly MergeType = "buildonly"
)

type NewsContext added in v0.11.0 

type NewsContext struct {
	Architecture      string
	Profile           string
	InstalledPackages []PackageID
	Language          string
}

NewsContext contains the explicit system state used for GLEP 42 relevance.

type NewsItem added in v0.11.0 

type NewsItem struct {
	ID                 string
	Path               string
	Title              string
	Author             string
	Date               string
	Revision           int
	Format             string
	DisplayIfInstalled []string
	DisplayIfProfile   []string
	DisplayIfKeyword   []string
	Body               string
}

NewsItem is one parsed GLEP 42 repository news item.

type NewsPaths added in v0.11.0 

type NewsPaths struct {
	RepositoryName string
	NewsDirectory  string
	StateDirectory string
}

NewsPaths identifies one repository's GLEP 42 news and Portage state.

type NewsState added in v0.11.0 

type NewsState struct {
	Items      []NewsItem
	Relevant   []NewsItem
	Unread     []NewsItem
	UnreadPath string
	SkipPath   string
}

NewsState separates repository contents, relevant items, and Portage's authoritative unread subset.

func ReadNewsState added in v0.11.0 

func ReadNewsState(ctx context.Context, paths NewsPaths, newsContext NewsContext) (NewsState, error)

ReadNewsState reads GLEP 42 news without modifying Portage state. Repeated restrictions of the same kind are ORed and different kinds are ANDed.

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 PackageKeywordRule added in v0.6.0 

type PackageKeywordRule struct {
	Atom    string
	Changes []string
	Source  PolicySource
}

PackageKeywordRule is one package.accept_keywords entry. An empty Changes slice accepts the host testing keyword, matching Portage behavior.

type PackageMaskRule added in v0.6.0 

type PackageMaskRule struct {
	Atom   string
	Source PolicySource
	Reason string
}

PackageMaskRule is one effective package mask or unmask with its rationale.

type PackageVisibilityContext added in v0.6.0 

type PackageVisibilityContext struct {
	ID       PackageID
	Keywords []string
}

PackageVisibilityContext describes a prospective repository package.

type PolicySource 

type PolicySource struct {
	Path string
	Line int
}

type PreservedLibraryRecord added in v0.11.0 

type PreservedLibraryRecord struct {
	Key         string
	Owner       PackageID
	Counter     string
	Paths       []string
	RootedPaths []string
}

PreservedLibraryRecord is one Portage preserved-libraries owner record.

func ReadPreservedLibraries added in v0.11.0 

func ReadPreservedLibraries(ctx context.Context, root, registryPath string) ([]PreservedLibraryRecord, error)

ReadPreservedLibraries validates and reads Portage's preserved library registry. A missing, empty, or whitespace-only registry is an empty state.

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 ProspectiveCandidateEvaluation added in v0.9.0 

type ProspectiveCandidateEvaluation struct {
	Candidate  RepositoryCandidate
	Visibility VisibilityResult
	Use        UseEvaluation
}

type Repository added in v0.7.0 

type Repository struct {
	Name       string
	Location   string
	SyncType   string
	SyncURI    string
	CloneDepth *int
	SyncDepth  *int
	Priority   int
	AutoSync   bool
	Masters    []string
	Main       bool
	Source     PolicySource
}

Repository is one effective repos.conf section with root-aware paths.

func ReadRepositories added in v0.7.0 

func ReadRepositories(ctx context.Context, paths SystemPaths) ([]Repository, error)

ReadRepositories discovers repositories from a root-aware repos.conf file or directory and returns them in deterministic master-before-child order.

type RepositoryCandidate added in v0.8.0 

type RepositoryCandidate struct {
	ID           PackageID
	EAPI         string
	Keywords     []string
	DeclaredUse  []UseDeclaration
	Inherited    []string
	RequiredUse  string
	Dependencies DependencyMetadata
	MetadataPath string
}

RepositoryCandidate is the evaluated metadata Portage records for one repository package version.

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 SnapshotConsistency added in v0.7.0 

type SnapshotConsistency uint8

SnapshotConsistency selects an explicit system-snapshot guarantee. 

const (
	// LockedAndStabilized observes Portage-compatible VDB/world locks and then
	// requires two agreeing complete observations.
	LockedAndStabilized SnapshotConsistency = iota
	// StabilizedLockless skips lock files and requires agreeing observations.
	// It is intended for explicit unprivileged inspection, never fallback.
	StabilizedLockless
)

type SnapshotOptions added in v0.5.0 

type SnapshotOptions struct {
	Installed  InstalledOptions
	Config     ConfigOptions
	Candidates CandidateOptions
	// IncludeCandidates binds repository candidates to each stabilized
	// observation so prospective policy evaluation cannot mix snapshots.
	IncludeCandidates bool
	Consistency       SnapshotConsistency
	// 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
	ReposConf     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
	Repositories []Repository
	Candidates   CandidateInventory
	Selections   Selections
	Consistency  SnapshotConsistency
}

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. LockedAndStabilized additionally holds shared VDB and world locks. Persistent change is reported as ErrConcurrentMutation instead of returning mixed state.

func (SystemSnapshot) EvaluateCandidate added in v0.9.0 

func (snapshot SystemSnapshot) EvaluateCandidate(ctx context.Context, id PackageID) (ProspectiveCandidateEvaluation, error)

EvaluateCandidate evaluates one exact candidate using configuration and repository evidence captured by this stabilized snapshot.

type UnresolvedKernelRequirement added in v0.10.0 

type UnresolvedKernelRequirement struct {
	Applicability Applicability
	Blocking      bool
	Severity      KernelRequirementSeverity
	Category      string
	OperatorText  string
	DeveloperText string
	Conditions    []UseCondition
	Invocation    KernelCheckInvocation
	Source        PolicySource
	Origin        string
}

type UseCondition added in v0.9.0 

type UseCondition struct {
	Flag    string
	Enabled bool
}

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.

type VisibilityEvidence added in v0.6.0 

type VisibilityEvidence struct {
	Kind    string
	Value   string
	Enabled bool
	Source  PolicySource
	Layer   string
	Reason  string
}

VisibilityEvidence records one policy input relevant to the outcome.

type VisibilityResult added in v0.6.0 

type VisibilityResult struct {
	Package          PackageID
	Visible          bool
	Stable           bool
	Status           VisibilityStatus
	Architecture     string
	PackageKeywords  []string
	AcceptedKeywords []string
	Evidence         []VisibilityEvidence
}

VisibilityResult is the effective result plus an ordered explanation.

type VisibilityStatus added in v0.6.0 

type VisibilityStatus string

VisibilityStatus is the primary prospective-package visibility outcome. 

const (
	VisibilityVisible                 VisibilityStatus = "visible"
	VisibilityPackageMasked           VisibilityStatus = "package_masked"
	VisibilityKeywordMasked           VisibilityStatus = "keyword_masked"
	VisibilityUnsupportedArchitecture VisibilityStatus = "unsupported_architecture"
)

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.