doc/config/sets.docbook

<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 reads the default configuration from all of the files
		located in <filename>/usr/share/portage/config/sets</filename>
		directory.
		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 configurations located in repositories
		configured in <filename>repos.conf</filename>.
		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 strictly 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>
			</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.base.DummyPackageSet
			packages = @selected @system

			# The selected set
			[selected]
			class = portage.sets.files.WorldSelectedSet

			# 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>
			option 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 &lt;category&gt;/*
			[installed category packages]
			class = portage.sets.dbapi.CategorySet
			multiset = true
			repository = vartree
			name_pattern = $category/*
			</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 &lt;john@doe.com&gt;
		</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-WorldSelectedSet'>
		<title>portage.sets.files.WorldSelectedSet</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>repository</varname>: Optional, defaults to 
				<parameter>porttree</parameter>. It determines which repository class should
				be used to create the package set. Valid values for this option are:
				<parameter>porttree</parameter> (normal ebuild repository), 
				<parameter>vartree</parameter> (installed package repository)
				and <parameter>bintree</parameter> (local binary package repository).</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>
		<sect2 id='config-set-classes-PreservedLibraryConsumerSet'>
		<title>portage.sets.libs.PreservedLibraryConsumerSet</title>
		<para>
		A special set used to rebuild all packages that need a preserved library that only
		remains due to <varname>FEATURES="preserve-libs"</varname>.
		</para>

			<sect3>
			<title>Single Set Configuration</title>
			<para>
			This class supports the following option:
			</para>
			<itemizedlist>
			<listitem><para><varname>debug</varname>: Generate extra output useful to figure out why
				certain packages are included in the set, as it's not always obvious.</para>
			</listitem>
			</itemizedlist>
			</sect3>
		</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>world</varname>: uses <classname>DummySet</classname></para></listitem>
	<listitem><para><varname>selected</varname>: uses <classname>WorldSelectedSet</classname></para></listitem>
	<listitem><para><varname>system</varname>: uses <classname>PackagesSystemSet</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>preserved-rebuild</varname>: uses <classname>PreservedLibraryConsumerSet</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>