From: Fabian Groffen Date: Fri, 12 Oct 2007 07:59:56 +0000 (-0000) Subject: Merged from trunk 8024:8032 X-Git-Url: http://git.tremily.us/gitweb.cgi?a=commitdiff_plain;h=55a0aeb52b432136fe98846a4f34638c5e13525c;p=portage.git Merged from trunk 8024:8032 | 8025 | Start documentation of set handler classes | | genone | | | 8028 | document all options | | genone | | | 8029 | security sets actually have one option | | genone | | | 8030 | add description to security set handlers | | genone | | | 8031 | add descriptions for dbapi set classes | | genone | | | 8032 | document default sets | | genone | | svn path=/main/branches/prefix/; revision=8073 --- diff --git a/doc/config/sets.docbook b/doc/config/sets.docbook index 5657b2cdc..ff06a7bc7 100644 --- a/doc/config/sets.docbook +++ b/doc/config/sets.docbook @@ -24,6 +24,7 @@ alter the default and repository sets. + sets.conf Syntax @@ -44,7 +45,10 @@ The configuration of a single set can be very simple as in most cases it only requires a single option class to be - complete. That option defines which handler class should be used to + 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. Another universal option available for single sets is name, however it's usually not needed as the name of the set is generated from the section name if name @@ -67,6 +71,7 @@ + Multi Set Configuration @@ -111,4 +116,356 @@ + + + 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. + + + + + + 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 + sets/$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 + sets/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.WorldSet + + 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 does not support any 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 does not support any 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 inejcted 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.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 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 all installed packages. + + + + Single Set Configuration + + This class does not support any options. + + + + + + + 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: + + system: uses PackagesSystemSet + world: uses WorldSet + security: uses NewAffectedSet with default options + everything: uses EverythingSet + + 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. + +