diff options
-rw-r--r-- | doc/config.docbook | 1 | ||||
-rw-r--r-- | doc/config/sets.docbook | 577 | ||||
-rw-r--r-- | doc/portage.docbook | 1 |
3 files changed, 0 insertions, 579 deletions
diff --git a/doc/config.docbook b/doc/config.docbook index 88009dfc6..118d98b55 100644 --- a/doc/config.docbook +++ b/doc/config.docbook @@ -1,5 +1,4 @@ <part id='config'> <title>Configuration</title> &config_bashrc; -&config_set; </part> diff --git a/doc/config/sets.docbook b/doc/config/sets.docbook deleted file mode 100644 index 95483d835..000000000 --- a/doc/config/sets.docbook +++ /dev/null @@ -1,577 +0,0 @@ -<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> diff --git a/doc/portage.docbook b/doc/portage.docbook index 999103a10..684773f40 100644 --- a/doc/portage.docbook +++ b/doc/portage.docbook @@ -22,7 +22,6 @@ <!ENTITY qa SYSTEM "qa.docbook"> <!ENTITY config SYSTEM "config.docbook"> <!ENTITY config_bashrc SYSTEM "config/bashrc.docbook"> - <!ENTITY config_set SYSTEM "config/sets.docbook"> ]> <book id="portage" lang="en"> |