Package Set Configuration
sets.conf locations
There are multiple locations where portage looks for set configuration
files, which are usually named sets.conf. Not all
of these locations have to contain a sets.conf, missing files are simply
ignored.
At first it looks for the default configuration in
/usr/share/portage/config.
The default config includes sets that are expected on all systems and
often critical for normal operation, like world,
system or security.
After that it will read repository specific configurations from
PORTDIR and PORTDIR_OVERLAY that might
include definitions of sets included in the repository.
Finally a system-specific set configuration may reside in
/etc/portage to either define additional sets or
alter the default and repository sets.
sets.conf Syntax
Unlike other Portage configuration files sets.conf
uses Pythons ConfigParser module, which implements
the syntax usually found in .ini files. At its core it allows various
named sections that each can contain any number of key-value pairs, see
the Python documentation
for the full details.
In a sets.conf file, a section can define either a
single package set, or a complete class of sets. These cases are handled
in different ways, and will be explained in detail in the following sections.
Single Set Configuration
The configuration of a single set can be very simple as in most cases
it only requires a single option class to be
complete Technically the class option
isn't stricly required, but it should always be used as the default
handler might be changed in future versions..
That option defines which handler class should be used to
create the set. Other universal options available for single sets are:
name (which is usually not needed as the name
of the set is generated from the section name if name
is missing)
world-candidate, which determines if
given package should be added to the world set
Some handler classes might require additional options for their configuration,
these will be covered later in this chapter.
Here are a few examples for single sets taken from the default
configuration file:
# The classic world set
[world]
class = portage.sets.base.DummyPackageSet
world-candidate = False
packages = @selected @system
# The selected set
[selected]
class = portage.sets.files.WorldSelectedSet
world-candidate = False
# The classic system set
[system]
class = portage.sets.profiles.PackagesSystemSet
Multi Set Configuration
As configuring each single set manually could be quite annoying if
you want many sets with the same options Portage also allows to
define whole classes of sets in a single section. Like with single
sets each section still requires the class option,
but to indicate that the section should generate multiple sets it's
also necessary to set the multiset option to
true. The world-candidate
option also supported like with
single sets (they'll apply to all sets generated by the section).
As it doesn't make much sense to specify a single name for multiple sets
the name option isn't available for multiset sections.
Most handler classes will have a reasonable default for generating names,
and usually you can (but don't have to) set the
name_pattern option to change the naming rules. That
option generally has to include a (handler-specific) placeholder that
will be replaced with a unique identifier (e.g. for category sets the
category name). As with single sets handler classes might require and/or
support additional options, these will be discussed later.
Some examples for multiset configurations:
# generate a set for each file in /etc/portage/sets
# this section is also in the default configuration
[user sets]
class = portage.sets.files.StaticFileSet
multiset = true
directory = /etc/portage/sets
# Generate a set for each category that includes all installed packages
# from that category. The sets will be named <category>/*
[installed category packages]
class = portage.sets.dbapi.CategorySet
multiset = true
repository = vartree
name_pattern = $category/*
Available Set Handler Classes
The following sections contain the available handler classes that can be
used for the class option in
sets.conf, together with a description about required
and optional configuration options for single and multi set configurations.
Note that not all classes support both configuration styles.
portage.sets.files.StaticFileSet
This class implements a simple file based package set. All atoms from
configured file are used to form the set, and currently only simple and
versioned atoms are supported (no use conditionals or any-of constructs).
For descriptive purposes the file can be accompanied by a file with the
same name plus a .metadata suffix which can contain
metadata sections for description, author, location and so on. Each section
has the form key: value where value
can contain multiple lines. Therefore sections have to be separated by
blank lines. For example:
description: This is a somewhat
longer description than usual. So it
needs more than one line.
homepage: http://www.foobar.org
author: John Doe <john@doe.com>
Single Set Configuration
In a single set configuration this class supports the following options:
filename: Required. Specifies the path to the file
that should be used for the package set.
greedy: Optional, defaults to false.
Determines if atoms in the package should include all installed slots (when set to
true) or if no slot expansion is wanted (when set to
false). This option only affects packages that have multiple
slots available (e.g. sys-kernel/gentoo-sources).
Multi Set Configuration
In a multi set configuration this class supports the following options:
directory: Optional, defaults to
/etc/portage/sets. Specifies the path to a directory
containing package set files. For each file (excluding metadata files) in
that location a separate package set is created.
name_pattern: Optional, defaults to
$name. This describes the naming pattern
to be used for creating the sets. It must contain either
$name or ${name}, which
will be replaced by the filename (without any directory components).
portage.sets.files.ConfigFileSet
Similar to StaticFileSet, but uses Portage configuration files.
Namely it can work with package.use,
package.keywords, package.mask
and package.unmask. It does not support
.metadata files, but ignores the extra data (like
USE flags or keywords) typically found in those files.
Single Set Configuration
In a single set configuration this class supports the following options:
filename: See
StaticFileSet
Multi Set Configuration
In a multi set configuration this class supports the following options:
directory: Optional, defaults to
/etc/portage. Specifies the path to a directory
containing one or more of the following portage configuration files:
package.use, package.keywords,
package.mask or package.unmask.
No other files in that directory will be used.
name_pattern: Optional, defaults to
package_$suffix. This describes the naming
pattern to be used for creating the sets. It must contain either
$suffix or ${suffix},
which will be replaced by the file suffix (e.g.
use or mask).
portage.sets.files.WorldSelectedSet
A minor variation of StaticFileSet, mainly for implementation
reasons. It should never be used in user configurations as it's already configured
by default, doesn't support any options and will eventually be removed in a future version.
Single Set Configuraton
This class doesn't support any extra options.
portage.sets.profiles.PackagesSystemSet
This class implements the classic system set, based on the
packages files in the profile.
There is no reason to use this in a user configuration as it is already
confgured by default and doesn't support any options.
Single Set Configuration
This class doesn't support any extra options.
portage.sets.security.SecuritySet
The set created by this class contains all atoms that need to be installed
to apply all GLSAs in the ebuild repository, no matter if they are already
applied or no (it's equivalent to the all target of
glsa-check). Generally it should be avoided in configurations in favor of
NewAffectedSet described below.
Single Set Configuration
In single set configurations this class supports the following options:
use_emerge_resolver: Optional, defaults to
false. This option determines which resolver
strategy should be used for the set atoms. When set to
true, it will use the default emerge algorithm
and use the highest visible version that matches the GLSA. If set
to false it will use the default glsa-check
algorithm and use the lowest version that matches the GLSA and is
higher than the currently installed version (least change policy).
portage.sets.security.NewGlsaSet
Like SecuritySet,
but ignores all GLSAs that were already applied or injected previously.
Single Set Configuration
In single set configurations this class supports the following options:
use_emerge_resolver: See
SecuritySet
portage.sets.security.NewAffectedSet
Like SecuritySet,
but ignores all GLSAs that were already applied or injected previously,
and all GLSAs that don't affect the current system. Practically there
should be no difference to NewGlsaSet though.
Single Set Configuration
In single set configurations this class supports the following options:
use_emerge_resolver: See
SecuritySet
portage.sets.security.AffectedSet
Like SecuritySet,
but ignores all GLSAs that don't affect the current system. Practically
there should be no difference to SecuritySet though.
Single Set Configuration
In single set configurations this class supports the following options:
use_emerge_resolver: See
SecuritySet
portage.sets.shell.CommandOutputSet
As the name says, this class creates a package set based on the output of
a given command. The command is run once when the set is accessed
for the first time during the current session.
Single Set Configuration
In single set configurations this class supports the following options:
command: Required. Specifies the command
that should be executed to generate the package set. It should
output a newline separated list of simple and/or versioned atoms
on stdout.
portage.sets.dbapi.AgeSet
Package sets created by this class will include installed packages that
have been installed before / after a given date.
Single Set Configuration
In single set configurations this class supports the following options:
age: Optional, defaults to 7. Specifies
the number of days passed since installation to use as cut-off point.
mode: Optional, defaults to "older". Must
be either "older" or "newer" to select packages installed either
before resp. after the cut-off-date given by age.
E.g. the defaults will select all installed packages that have been
installed more than one week ago.
portage.sets.dbapi.CategorySet
This class simply creates a set with all packages in a given category.
Single Set Configuration
In single set configurations this class supports the following options:
category: Required. The name of an existing ebuild
category which should be used to create the package set.
repository: Optional, defaults to
porttree. It determines which repository class should
be used to create the package set. Valid values for this option are:
porttree (normal ebuild repository),
vartree (installed package repository)
and bintree (local binary package repository).
only_visible: Optional, defaults to true.
When set to true the set will only include visible packages,
when set to false it will also include masked packages.
It's currently only effective in combination with the porttree
repository.
Multi Set Configuration
In multi set configurations this class supports the following options:
categories: Optional, defaults to all categories.
If set it must be a space separated list of existing ebuild categories for
which package sets should be created.
repository: See previous section.
only_visible: See previous section.
name_pattern: Optional, defaults to
$category/*. This describes the naming pattern
to be used for creating the sets. It must contain either
$category or ${category}, which
will be replaced by the category name.
portage.sets.dbapi.EverythingSet
A superset of the classic world target, a set created
by this class contains SLOT atoms to match all installed packages. Note that
use of this set makes it impossible for emerge to solve blockers by automatic
uninstallation of blocked packages.
Single Set Configuration
This class doesn't support any extra options.
portage.sets.dbapi.OwnerSet
Package set which contains all packages
that own one or more files.
This class supports the following options:
files: Required. A list of file paths
that should be used to create the package set.
portage.sets.dbapi.VariableSet
Package set which contains all packages
that match specified values of specified variable.
This class supports the following options:
variable: The name of
the specified variable whose values are checked.
includes: A list of
values that must be contained within the specified
variable.
excludes: A list of
values that must not be contained within the specified
variable.
metadata-source: Optional, defaults to
"vartree". Specifies the repository to use for getting the metadata
to check.
portage.sets.dbapi.UnavailableSet
Package set which contains all installed
packages for which there are no visible ebuilds
corresponding to the same $CATEGORY/$PN:$SLOT.
This class supports the following options:
metadata-source: Optional, defaults to
"porttree". Specifies the repository to use for getting the metadata
to check.
portage.sets.dbapi.DowngradeSet
Package set which contains all packages
for which the highest visible ebuild version is lower than
the currently installed version.
This class doesn't support any extra options.
portage.sets.libs.PreservedLibraryConsumerSet
A special set used to rebuild all packages that need a preserved library that only
remains due to FEATURES="preserve-libs".
Single Set Configuration
This class supports the following option:
debug: Generate extra output useful to figure out why
certain packages are included in the set, as it's not always obvious.
Default Sets
By default, Portage already creates a few default sets that can be used
without further configuration. See
and for details on how to change those
defaults.
The default sets are:
world: uses DummySet
selected: uses WorldSelectedSet
system: uses PackagesSystemSet
security: uses NewAffectedSet with default options
installed: uses EverythingSet
preserved-rebuild: uses PreservedLibraryConsumerSet
live-rebuild: uses VariableSet
module-rebuild: uses OwnerSet
downgrade: uses DowngradeSet
unavailable: uses UnavailableSet
Additionally the default configuration includes a multi set section based on
the StaticFileSet defaults that creates a set for each
file in /etc/portage/sets for convenience.