From 4856c6ef67150b9fee2571640011a3a130a4f26f Mon Sep 17 00:00:00 2001 From: Marius Mauch Date: Sat, 6 Oct 2007 13:49:08 +0000 Subject: [PATCH] Add some documentation about set configuration svn path=/main/trunk/; revision=7978 --- doc/config.docbook | 4 ++ doc/config/sets.docbook | 114 ++++++++++++++++++++++++++++++++++++++++ doc/portage.docbook | 3 ++ 3 files changed, 121 insertions(+) create mode 100644 doc/config.docbook create mode 100644 doc/config/sets.docbook diff --git a/doc/config.docbook b/doc/config.docbook new file mode 100644 index 000000000..39c560080 --- /dev/null +++ b/doc/config.docbook @@ -0,0 +1,4 @@ + +Configuration +&config_set; + diff --git a/doc/config/sets.docbook b/doc/config/sets.docbook new file mode 100644 index 000000000..5657b2cdc --- /dev/null +++ b/doc/config/sets.docbook @@ -0,0 +1,114 @@ + + 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_OVERLAYthat 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 it's 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. 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 + is missing. 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.files.WorldSet + + # 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. + + + 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/* + + + + + + diff --git a/doc/portage.docbook b/doc/portage.docbook index 1ca868722..ac1061310 100644 --- a/doc/portage.docbook +++ b/doc/portage.docbook @@ -8,6 +8,8 @@ + + ]> @@ -27,6 +29,7 @@ &date; +&config; &qa; -- 2.26.2