PORTAGE-NG(1)

#NAME

portage-ng - a Prolog-based package dependency resolver and build system for Gentoo

#SYNOPSIS

portage-ng [--mode MODE] [OPTIONS] [TARGETS ...]

portage-ng --mode standalone --shell

portage-ng --sync [REPOSITORY ...]

#DESCRIPTION

portage-ng is a dependency resolver, planner, and build orchestrator for Gentoo Linux package trees. It reads Gentoo ebuild metadata (md5-cache), resolves dependency graphs using inductive proof search, generates ordered build plans, and optionally executes them by invoking the standard ebuild(1) command.

The resolver supports the full PMS (Package Manager Specification) dependency language, including USE-conditional dependencies, slot operators, blockers, sub-slots, and PDEPEND (post-merge dependencies).

portage-ng can operate in several modes: standalone (default, all in-process), client-server (distributed proving via Pengines), or as a daemon serving IPC clients.

#MODES

#ACTIONS

Actions control what portage-ng does with the given targets. Exactly one action is performed per invocation.

#Dependency resolution (default)

#Building

#Package management

#Information

#Repository management

#VDB queries

#Maintenance

#OPTIONS

#Dependency resolution options

#Binary package options

#Build options

#Plan explanation (requires LLM)

#Upstream version checking

#Snapshot and rollback

#Resolver hints

#Convenience presets

#Output options

#Network options (client/server modes)

#Lifecycle options (daemon/server modes)

#Build prefix

#TARGETS

Targets identify which packages to operate on. Several formats are supported:

#PACKAGE SETS

Package sets expand to concrete target atoms before proving. File-backed sets (@world, @system, and files under the sets directory) come from preference configuration. Computed sets are derived on demand from the VDB and/or portage tree via sets:expand/2 (Source/Domain/Gentoo/Preference/sets.pl). Use --list-sets to see every name registered on the current host.

An empty computed set is not an error: with --ci --pretend @set, portage-ng prints an informational message and exits 0.

#File-backed / preference sets

#Computed sets (VDB / tree)

Related flags (not sets): --changed-deps applies the same outdated-deps test while resolving other targets; config:subslot_rebuild/1 plans same-version reverse-dep rebuilds when a := provider's subslot changes (transaction-driven; complementary to @preserved-rebuild).

#SEARCH SYNTAX

The --search flag accepts two kinds of queries:

1. Structured queries -- one or more key=value arguments combined conjunctively (AND). Each argument has the form key comparator value.

2. Semantic queries -- free-form natural-language text (e.g. text editor with syntax highlighting). When the query does not parse as a structured expression, portage-ng falls back to semantic search: the query is embedded using a locally running Ollama model and matched against a pre-built vector index of all package descriptions. The index is built with --train-model (requires Ollama with nomic-embed-text). On Apple Silicon machines, embedding generation is GPU-accelerated via Metal.

#Search keys

#Comparators

#Search examples

# Find all versions of packages named gcc
portage-ng -s name=gcc

# Find gcc in the sys-devel category
portage-ng -s category=sys-devel name=gcc

# Find packages with "python" anywhere in the name
portage-ng -s name:=*python*

# Fuzzy match — finds gcc despite the typo
portage-ng -s name~gkc

# Find all packages that declare the wayland USE flag
portage-ng -s iuse=wayland

# Find packages with the amd64 keyword on EAPI 8 or later
portage-ng -s keywords=amd64 eapi>=8

# List masked packages in dev-lang
portage-ng -s masked=true category=dev-lang

# Find python packages in slot 0
portage-ng -s slot=0 name=python

#EBUILD PHASES

When --build is active, portage-ng executes the following ebuild phases via the ebuild(1) command:

clean → setup → unpack → prepare → configure → compile → test → install → merge

When --buildpkg is also active, the package phase is inserted between install and merge:

clean → ... → install → package → merge

The merge phase is a composite operation that internally runs pkg_preinst, merges files to the live filesystem, unmerges the old version (for updates and downgrades), and runs pkg_postinst.

When --resume is active, the clean phase is omitted so that the work directory from the previous attempt is preserved.

#DOWNLOADING

portage-ng downloads source archives (distfiles) from a local HTTP mirror using the GLEP 75 layout. When the mirror download fails, it falls back to the upstream SRC_URI.

mirror:// URIs in SRC_URI are resolved through the portage tree's profiles/thirdpartymirrors file.

For live ebuilds (version 9999, inheriting git-r3), portage-ng clones or fetches the upstream git repository into a local bare cache under distdir/git3-src/, with real-time progress display.

Fetch-restricted ebuilds (RESTRICT=fetch) are detected and reported as requiring manual download.

#CONFIGURATION

#Machine-specific configuration

Source/Config/<hostname>.pl — Per-machine configuration: portage tree location, md5-cache path, VDB path, and repository registration.

#Portage configuration

Source/Config/gentoo.pl — Reads standard Gentoo /etc/portage files: make.conf, package.use, package.mask, etc.

#Build configuration

#EXIT STATUS

#EXAMPLES

# Resolve dependencies for vim in pretend mode
portage-ng --mode standalone --pretend vim

# Build irssi with live progress (oneshot, do not add to world)
portage-ng --mode standalone --build --oneshot irssi

# Build gcc and create a binary package
portage-ng --mode standalone --build --buildpkg gcc

# Resume a previously interrupted build
portage-ng --mode standalone --resume

# Resume, skipping two packages
portage-ng --mode standalone --resume --skip dev-lang/python-3.12.0 --skip sys-apps/portage-2.3.99

# Same, using positional arguments
portage-ng --mode standalone --resume dev-lang/python-3.12.0 sys-apps/portage-2.3.99

# Fetch sources only, without building
portage-ng --mode standalone --fetchonly firefox

# Synchronise the portage tree
portage-ng --mode standalone --sync

# Start an interactive Prolog shell
portage-ng --mode standalone --shell

# CI run with 60-second timeout
portage-ng --mode standalone --ci --pretend --timeout 60 kde-apps-meta

# Show variant plans with auto-detected pivot points
portage-ng --pretend --variants auto dev-libs/gtk+

# Explore how toggling wayland and X affects a plan
portage-ng --pretend --variants wayland,X dev-libs/gtk+

# Ask why a package is in the plan
portage-ng --pretend --explain "Why is dev-libs/openssl in the plan?" vim

# Interactive plan explanation
portage-ng --pretend --explain @world

# Merge vim with a snapshot (auto-generated ID)
portage-ng --snapshot vim

# Merge with a named snapshot
portage-ng --snapshot before-kde-update --update @world

# List available snapshots
portage-ng --snapshots

# Preview what a rollback would change
portage-ng --pretend --rollback 20260309-143022

# Execute a rollback
portage-ng --rollback 20260309-143022

# Start a chat session with the default LLM
portage-ng --llm

# Chat with a specific LLM service
portage-ng --llm grok

# Metacircular diagnose of a failed build (confirm before applying feedback)
portage-ng --diagnose cat/pkg

# Diagnose with an explicit build log
portage-ng --diagnose --log /var/tmp/portage-ng/logs/cat--pkg-1.2.3.log cat/pkg

# Check upstream versions for specific packages
portage-ng --upstream sys-apps/portage dev-lang/python

# Check upstream versions for the world set
portage-ng --upstream @world

# Build the semantic search index (requires Ollama)
portage-ng --train-model

# Semantic search: find packages by description
portage-ng --search text editor with syntax highlighting

# Find packages similar to vim
portage-ng --similar app-editors/vim

# Estimate build time for packages
portage-ng --estimate dev-qt/qtcore sys-devel/gcc

# Search Bugzilla for bugs matching a term
portage-ng --search-bugs "openssl segfault"

# Upgrade the world set
portage-ng --mode standalone --upgrade

# List available sets (file-backed and computed)
portage-ng --mode standalone --list-sets

# Pretend a GLSA security upgrade set
portage-ng --mode standalone --ci --pretend @security

# Rebuild consumers of preserve-libs leftovers
portage-ng --mode standalone --ci --pretend @preserved-rebuild

# Rebuild packages whose installed RDEPEND/PDEPEND drifted from the tree
portage-ng --mode standalone --ci --pretend @changed-deps

# Same comparison while updating other targets
portage-ng --mode standalone --pretend --deep --changed-deps @world

#FILES

#ARCHITECTURE

portage-ng follows a pipeline architecture:

#SEE ALSO

emerge(1), ebuild(1), ebuild(5), make.conf(5), portage(5)

#AUTHORS

Pieter Van den Abeele pvdabeel@mac.com

#COPYRIGHT

Copyright (c) 2005-2026 Pieter Van den Abeele. Distributed under the terms of the LICENSE file in the project root.