+++ /dev/null
-<chapter id='config-set'>
- <title>Package Set Configuration</title>
- <sect1 id='config-set-locations'>
- <title>sets.conf locations</title>
- <para>
- There are multiple locations where portage looks for set configuration
- files, which are usually named <filename>sets.conf</filename>. Not all
- of these locations have to contain a sets.conf, missing files are simply
- ignored.
- </para>
- <para>
- At first it looks for the default configuration in
- <filename>/usr/share/portage/config</filename>.
- The default config includes sets that are expected on all systems and
- often critical for normal operation, like <varname>world</varname>,
- <varname>system</varname> or <varname>security</varname>.
- <!-- TODO: Add reference to currently non-existing documentation about
- set usage and default sets -->
- After that it will read repository specific configurations from
- <envar>PORTDIR</envar> and <envar>PORTDIR_OVERLAY</envar> that might
- include definitions of sets included in the repository.
- Finally a system-specific set configuration may reside in
- <filename>/etc/portage</filename> to either define additional sets or
- alter the default and repository sets.
- </para>
- </sect1>
-
- <sect1 id='config-set-syntax'>
- <title>sets.conf Syntax</title>
- <para>
- Unlike other Portage configuration files <filename>sets.conf</filename>
- uses Pythons <classname>ConfigParser</classname> 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 <ulink url="http://doc.python.org/lib/module-ConfigParser.html" type="text/html">Python documentation</ulink>
- for the full details.
- </para>
- <para>
- In a <filename>sets.conf</filename> 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.
- </para>
- <sect2 id='config-set-syntax-single'>
- <title>Single Set Configuration</title>
- <para>
- The configuration of a single set can be very simple as in most cases
- it only requires a single option <varname>class</varname> to be
- complete <footnote><para>Technically the <varname>class</varname> option
- isn't stricly required, but it should always be used as the default
- handler might be changed in future versions.</para></footnote>.
- That option defines which handler class should be used to
- create the set. Other universal options available for single sets are:
- </para>
- <itemizedlist>
- <listitem><para><varname>name</varname> (which is usually not needed as the name
- of the set is generated from the section name if <varname>name</varname>
- is missing)</para></listitem>
- <listitem><para><varname>world-candidate</varname>, which determines if
- given package should be added to the <varname>world</varname> set</para></listitem>
- <listitem><para><varname>extend</varname> to include the contents of other package sets</para>
- </listitem>
- <listitem><para><varname>remove</varname> to remove the contents of other package sets</para>
- </listitem>
- <listitem><para><varname>intersect</varname> to only include packages that are also
- included in one or more other package sets</para></listitem>
- </itemizedlist>
- <para>
- Some handler classes might require additional options for their configuration,
- these will be covered later in this chapter.
- </para>
- <para>
- Here are a few examples for single sets taken from the default
- configuration file:
- <programlisting>
- # The classic world set
- [world]
- class = portage.sets.files.WorldSet
- world-candidate = False
-
- # The classic system set
- [system]
- class = portage.sets.profiles.PackagesSystemSet
- </programlisting>
- <!-- TODO: reference list of available set handler classes here -->
- </para>
- </sect2>
-
- <sect2 id='config-set-syntax-multi'>
- <title>Multi Set Configuration</title>
- <para>
- 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 <varname>class</varname> option,
- but to indicate that the section should generate multiple sets it's
- also necessary to set the <varname>multiset</varname> option to
- <parameter>true</parameter>. The <varname>world-candidate</varname>,
- <varname>extend</varname>, <varname>remove</varname> and
- <varname>intersect</varname> options are also supported like with
- single sets (they'll apply to all sets generated by the section).
- </para>
- <para>
- As it doesn't make much sense to specify a single name for multiple sets
- the <varname>name</varname> 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
- <varname>name_pattern</varname> 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.
- </para>
- <para>
- Some examples for multiset configurations:
- <programlisting>
- # 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
- name_pattern = $category/*
- intersect = installed
- </programlisting>
- </para>
- <!-- TODO: reference list of available set handler classes here -->
- </sect2>
- </sect1>
-
- <sect1 id='config-set-classes'>
- <title>Available Set Handler Classes</title>
- <para>
- The following sections contain the available handler classes that can be
- used for the <varname>class</varname> option in
- <filename>sets.conf</filename>, 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.
- </para>
-
- <sect2 id='config-set-classes-StaticFileSet' xreflabel='StaticFileSet'>
- <title>portage.sets.files.StaticFileSet</title>
- <para>
- 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 <filename>.metadata</filename> suffix which can contain
- metadata sections for description, author, location and so on. Each section
- has the form key: value where <varname>value</varname>
- can contain multiple lines. Therefore sections have to be separated by
- blank lines. For example:
- <programlisting>
- 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>
- </programlisting>
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- In a single set configuration this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>filename</varname>: Required. Specifies the path to the file
- that should be used for the package set.</para></listitem>
- <listitem><para><varname>greedy</varname>: Optional, defaults to <parameter>false</parameter>.
- Determines if atoms in the package should include all installed slots (when set to
- <parameter>true</parameter>) or if no slot expansion is wanted (when set to
- <parameter>false</parameter>). This option only affects packages that have multiple
- slots available (e.g. <parameter>sys-kernel/gentoo-sources</parameter>).</para></listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title>Multi Set Configuration</title>
- <para>
- In a multi set configuration this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>directory</varname>: Optional, defaults to
- <filename>/etc/portage/sets</filename>. 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.</para>
- </listitem>
- <listitem><para><varname>name_pattern</varname>: Optional, defaults to
- <parameter>$name</parameter>. This describes the naming pattern
- to be used for creating the sets. It must contain either
- <parameter>$name</parameter> or <parameter>${name}</parameter>, which
- will be replaced by the filename (without any directory components).</para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-ConfigFileSet'>
- <title>portage.sets.files.ConfigFileSet</title>
- <para>
- Similar to <classname>StaticFileSet</classname>, but uses Portage configuration files.
- Namely it can work with <filename>package.use</filename>,
- <filename>package.keywords</filename>, <filename>package.mask</filename>
- and <filename>package.unmask</filename>. It does not support
- <filename>.metadata</filename> files, but ignores the extra data (like
- USE flags or keywords) typically found in those files.
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- In a single set configuration this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>filename</varname>: See
- <xref linkend='config-set-classes-StaticFileSet'/>StaticFileSet</para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title>Multi Set Configuration</title>
- <para>
- In a multi set configuration this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>directory</varname>: Optional, defaults to
- <filename>/etc/portage</filename>. Specifies the path to a directory
- containing one or more of the following portage configuration files:
- <filename>package.use</filename>, <filename>package.keywords</filename>,
- <filename>package.mask</filename> or <filename>package.unmask</filename>.
- No other files in that directory will be used.</para>
- </listitem>
- <listitem><para><varname>name_pattern</varname>: Optional, defaults to
- <parameter>package_$suffix</parameter>. This describes the naming
- pattern to be used for creating the sets. It must contain either
- <parameter>$suffix</parameter> or <parameter>${suffix}</parameter>,
- which will be replaced by the file suffix (e.g.
- <parameter>use</parameter> or <parameter>mask</parameter>).</para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-WorldSet'>
- <title>portage.sets.files.WorldSet</title>
- <para>
- A minor variation of <classname>StaticFileSet</classname>, 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.
- </para>
-
- <sect3>
- <title>Single Set Configuraton</title>
- <para>
- This class doesn't support any extra options.
- </para>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-PackagesSystemSet'>
- <title>portage.sets.profiles.PackagesSystemSet</title>
- <para>
- This class implements the classic <parameter>system</parameter> set, based on the
- <filename>packages</filename> files in the profile.
- <!-- TODO: Add reference to profile documentation regarding "packages" -->
- There is no reason to use this in a user configuration as it is already
- confgured by default and doesn't support any options.
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- This class doesn't support any extra options.
- </para>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-SecuritySet' xreflabel='SecuritySet'>
- <title>portage.sets.security.SecuritySet</title>
- <para>
- 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 <parameter>all</parameter> target of
- glsa-check). Generally it should be avoided in configurations in favor of
- <classname>NewAffectedSet</classname> described below.
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- In single set configurations this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>use_emerge_resolver</varname>: Optional, defaults to
- <parameter>false</parameter>. This option determines which resolver
- strategy should be used for the set atoms. When set to
- <parameter>true</parameter>, it will use the default emerge algorithm
- and use the highest visible version that matches the GLSA. If set
- to <parameter>false</parameter> 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).</para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-NewGlsaSet'>
- <title>portage.sets.security.NewGlsaSet</title>
- <para>
- Like <xref linkend='config-set-classes-SecuritySet'/>SecuritySet,
- but ignores all GLSAs that were already applied or injected previously.
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- In single set configurations this class supports the following options:
- <itemizedlist>
- <listitem><para><varname>use_emerge_resolver</varname>: See
- <xref linkend='config-set-classes-SecuritySet'/>SecuritySet</para>
- </listitem>
- </itemizedlist>
- </para>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-NewAffectedSet'>
- <title>portage.sets.security.NewAffectedSet</title>
- <para>
- Like <xref linkend='config-set-classes-SecuritySet'/>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 <classname>NewGlsaSet</classname> though.
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- In single set configurations this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>use_emerge_resolver</varname>: See
- <xref linkend='config-set-classes-SecuritySet'/>SecuritySet</para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-AffectedSet'>
- <title>portage.sets.security.AffectedSet</title>
- <para>
- Like <xref linkend='config-set-classes-SecuritySet'/>SecuritySet,
- but ignores all GLSAs that don't affect the current system. Practically
- there should be no difference to <classname>SecuritySet</classname> though.
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- In single set configurations this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>use_emerge_resolver</varname>: See
- <xref linkend='config-set-classes-SecuritySet'/>SecuritySet</para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-CommandOutputSet'>
- <title>portage.sets.shell.CommandOutputSet</title>
- <para>
- 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.
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- In single set configurations this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>command</varname>: 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.</para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-AgeSet'>
- <title>portage.sets.dbapi.AgeSet</title>
- <para>
- Package sets created by this class will include installed packages that
- have been installed before / after a given date.
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- In single set configurations this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>age</varname>: Optional, defaults to 7. Specifies
- the number of days passed since installation to use as cut-off point.</para>
- </listitem>
- <listitem><para><varname>mode</varname>: Optional, defaults to "older". Must
- be either "older" or "newer" to select packages installed either
- before resp. after the cut-off-date given by <varname>age</varname>.
- E.g. the defaults will select all installed packages that have been
- installed more than one week ago.</para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-CategorySet'>
- <title>portage.sets.dbapi.CategorySet</title>
- <para>
- This class simply creates a set with all packages in a given category.
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- In single set configurations this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>category</varname>: Required. The name of an existing ebuild
- category which should be used to create the package set.</para>
- </listitem>
- <listitem><para><varname>only_visible</varname>: Optional, defaults to <parameter>true</parameter>.
- When set to <parameter>true</parameter> the set will only include visible packages,
- when set to <parameter>false</parameter> it will also include masked packages.
- It's currently only effective in combination with the <parameter>porttree</parameter>
- repository.</para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title>Multi Set Configuration</title>
- <para>
- In multi set configurations this class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>categories</varname>: 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.</para>
- </listitem>
- <listitem><para><varname>repository</varname>: See previous section.</para></listitem>
- <listitem><para><varname>only_visible</varname>: See previous section.</para></listitem>
- <listitem><para><varname>name_pattern</varname>: Optional, defaults to
- <parameter>$category/*</parameter>. This describes the naming pattern
- to be used for creating the sets. It must contain either
- <parameter>$category</parameter> or <parameter>${category}</parameter>, which
- will be replaced by the category name.</para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
-
- <sect2 id='config-set-classes-EverythingSet'>
- <title>portage.sets.dbapi.EverythingSet</title>
- <para>
- A superset of the classic <parameter>world</parameter> 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.
- </para>
-
- <sect3>
- <title>Single Set Configuration</title>
- <para>
- This class doesn't support any extra options.
- </para>
- </sect3>
- </sect2>
- <sect2 id='config-set-classes-OwnerSet'>
- <title>portage.sets.dbapi.OwnerSet</title>
- <para>
- Package set which contains all packages
- that own one or more files.
- This class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>files</varname>: Required. A list of file paths
- that should be used to create the package set.</para>
- </listitem>
- </itemizedlist>
- </sect2>
- <sect2 id='config-set-classes-VariableSet'>
- <title>portage.sets.dbapi.VariableSet</title>
- <para>
- Package set which contains all packages
- that match specified values of specified variable.
- This class supports the following options:
- </para>
- <itemizedlist>
- <listitem><para><varname>variable</varname>: The name of
- the specified variable whose values are checked.</para>
- </listitem>
- <listitem><para><varname>includes</varname>: A list of
- values that must be contained within the specified
- variable.</para>
- </listitem>
- <listitem><para><varname>excludes</varname>: A list of
- values that must not be contained within the specified
- variable.</para>
- </listitem>
- <listitem><para><varname>metadata-source</varname>: Optional, defaults to
- "vartree". Specifies the repository to use for getting the metadata
- to check.</para></listitem>
- </itemizedlist>
- </sect2>
- <sect2 id='config-set-classes-UnavailableSet'>
- <title>portage.sets.dbapi.UnavailableSet</title>
- <para>
- 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:
- </para>
- <itemizedlist>
- <listitem><para><varname>metadata-source</varname>: Optional, defaults to
- "porttree". Specifies the repository to use for getting the metadata
- to check.</para></listitem>
- </itemizedlist>
- </sect2>
- <sect2 id='config-set-classes-DowngradeSet'>
- <title>portage.sets.dbapi.DowngradeSet</title>
- <para>
- 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.
- </para>
- </sect2>
- </sect1>
-
- <sect1 id='config-set-defaults'>
- <title>Default Sets</title>
- <para>
- By default, Portage already creates a few default sets that can be used
- without further configuration. See <xref linkend='config-set-locations'/>
- and <xref linkend='config-set-syntax'/> for details on how to change those
- defaults.
- </para>
- <para>
- The default sets are:
- </para>
- <itemizedlist>
- <listitem><para><varname>system</varname>: uses <classname>PackagesSystemSet</classname></para></listitem>
- <listitem><para><varname>world</varname>: uses <classname>WorldSet</classname></para></listitem>
- <listitem><para><varname>security</varname>: uses <classname>NewAffectedSet</classname> with default options</para></listitem>
- <listitem><para><varname>installed</varname>: uses <classname>EverythingSet</classname></para></listitem>
- <listitem><para><varname>live-rebuild</varname>: uses <classname>VariableSet</classname></para></listitem>
- <listitem><para><varname>module-rebuild</varname>: uses <classname>OwnerSet</classname></para></listitem>
- <listitem><para><varname>downgrade</varname>: uses <classname>DowngradeSet</classname></para></listitem>
- <listitem><para><varname>unavailable</varname>: uses <classname>UnavailableSet</classname></para></listitem>
- </itemizedlist>
- <para>Additionally the default configuration includes a multi set section based on
- the <classname>StaticFileSet</classname> defaults that creates a set for each
- file in <filename>/etc/portage/sets</filename> for convenience.</para>
- </sect1>
-</chapter>
projects / portage.git / commitdiff