diff options
| -rw-r--r-- | doc/config/sets.docbook | 172 | ||||
| -rw-r--r-- | doc/dependency_resolution/decision_making.docbook | 8 | ||||
| -rw-r--r-- | doc/dependency_resolution/package_modeling.docbook | 26 | ||||
| -rw-r--r-- | doc/dependency_resolution/task_scheduling.docbook | 14 | ||||
| -rw-r--r-- | doc/package/ebuild/phases.docbook | 40 |
5 files changed, 129 insertions, 131 deletions
diff --git a/doc/config/sets.docbook b/doc/config/sets.docbook index dc26b1a0c..3371c175b 100644 --- a/doc/config/sets.docbook +++ b/doc/config/sets.docbook @@ -50,19 +50,21 @@ 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><varname>name</varname> (which is usually not needed as the name + <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)</listitem> - <listitem><varname>world-candidate</varname>, which determines if - given package should be added to the <varname>world</varname> set</listitem> - <listitem><varname>extend</varname> to include the contents of other package sets + 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><varname>remove</varname> to remove the contents of other package sets + <listitem><para><varname>remove</varname> to remove the contents of other package sets</para> </listitem> - <listitem><varname>intersect</varname> to only include packages that are also - included in one or more other package sets</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> @@ -168,36 +170,36 @@ <title>Single Set Configuration</title> <para> In a single set configuration this class supports the following options: + </para> <itemizedlist> - <listitem><varname>filename</varname>: Required. Specifies the path to the file - that should be used for the package set.</listitem> - <listitem><varname>greedy</varname>: Optional, defaults to <parameter>false</parameter>. + <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>).</listitem> + slots available (e.g. <parameter>sys-kernel/gentoo-sources</parameter>).</para></listitem> </itemizedlist> - </para> </sect3> <sect3> <title>Multi Set Configuration</title> <para> In a multi set configuration this class supports the following options: + </para> <itemizedlist> - <listitem><varname>directory</varname>: Optional, defaults to + <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. + that location a separate package set is created.</para> </listitem> - <listitem><varname>name_pattern</varname>: Optional, defaults to + <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). + will be replaced by the filename (without any directory components).</para> </listitem> </itemizedlist> - </para> </sect3> </sect2> @@ -216,35 +218,35 @@ <title>Single Set Configuration</title> <para> In a single set configuration this class supports the following options: + </para> <itemizedlist> - <listitem><varname>filename</varname>: See - <xref linkend='config-set-classes-StaticFileSet'>StaticFileSet</xref> + <listitem><para><varname>filename</varname>: See + <xref linkend='config-set-classes-StaticFileSet'>StaticFileSet</xref></para> </listitem> </itemizedlist> - </para> </sect3> <sect3> <title>Multi Set Configuration</title> <para> In a multi set configuration this class supports the following options: + </para> <itemizedlist> - <listitem><varname>directory</varname>: Optional, defaults to + <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. + No other files in that directory will be used.</para> </listitem> - <listitem><varname>name_pattern</varname>: Optional, defaults to + <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>). + <parameter>use</parameter> or <parameter>mask</parameter>).</para> </listitem> </itemizedlist> - </para> </sect3> </sect2> @@ -296,18 +298,18 @@ <title>Single Set Configuration</title> <para> In single set configurations this class supports the following options: + </para> <itemizedlist> - <listitem><varname>use_emerge_resolver</varname>: Optional, defaults to + <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). + higher than the currently installed version (least change policy).</para> </listitem> </itemizedlist> - </para> </sect3> </sect2> @@ -323,8 +325,8 @@ <para> In single set configurations this class supports the following options: <itemizedlist> - <listitem><varname>use_emerge_resolver</varname>: See - <xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref> + <listitem><para><varname>use_emerge_resolver</varname>: See + <xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref></para> </listitem> </itemizedlist> </para> @@ -344,12 +346,12 @@ <title>Single Set Configuration</title> <para> In single set configurations this class supports the following options: + </para> <itemizedlist> - <listitem><varname>use_emerge_resolver</varname>: See - <xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref> + <listitem><para><varname>use_emerge_resolver</varname>: See + <xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref></para> </listitem> </itemizedlist> - </para> </sect3> </sect2> @@ -365,12 +367,12 @@ <title>Single Set Configuration</title> <para> In single set configurations this class supports the following options: + </para> <itemizedlist> <listitem><varname>use_emerge_resolver</varname>: See <xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref> </listitem> </itemizedlist> - </para> </sect3> </sect2> @@ -386,14 +388,14 @@ <title>Single Set Configuration</title> <para> In single set configurations this class supports the following options: + </para> <itemizedlist> - <listitem><varname>command</varname>: Required. Specifies the command + <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. + on stdout.</para> </listitem> </itemizedlist> - </para> </sect3> </sect2> @@ -408,18 +410,18 @@ <title>Single Set Configuration</title> <para> In single set configurations this class supports the following options: + </para> <itemizedlist> - <listitem><varname>age</varname>: Optional, defaults to 7. Specifies - the number of days passed since installation to use as cut-off point. + <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><varname>mode</varname>: Optional, defaults to "older". Must + <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. + installed more than one week ago.</para> </listitem> </itemizedlist> - </para> </sect3> </sect2> @@ -433,39 +435,39 @@ <title>Single Set Configuration</title> <para> In single set configurations this class supports the following options: + </para> <itemizedlist> - <listitem><varname>category</varname>: Required. The name of an existing ebuild - category which should be used to create the package set. + <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><varname>only_visible</varname>: Optional, defaults to <parameter>true</parameter>. + <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> + It's currently only effective in combination with the <parameter>porttree</parameter></para> repository. </listitem> </itemizedlist> - </para> </sect3> <sect3> <title>Multi Set Configuration</title> <para> In multi set configurations this class supports the following options: + </para> <itemizedlist> - <listitem><varname>categories</varname>: Optional, defaults to all categories. + <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. + which package sets should be created.</para> </listitem> - <listitem><varname>repository</varname>: See previous section.</listitem> - <listitem><varname>only_visible</varname>: See previous section.</listitem> - <listitem><varname>name_pattern</varname>: Optional, defaults to + <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. + will be replaced by the category name.</para> </listitem> </itemizedlist> - </para> </sect3> </sect2> @@ -491,12 +493,12 @@ Package set which contains all packages that own one or more files. This class supports the following options: + </para> <itemizedlist> - <listitem><varname>files</varname>: Required. A list of file paths - that should be used to create the package set. + <listitem><para><varname>files</varname>: Required. A list of file paths + that should be used to create the package set.</para> </listitem> </itemizedlist> - </para> </sect2> <sect2 id='config-set-classes-VariableSet'> <title>portage.sets.dbapi.VariableSet</title> @@ -504,23 +506,23 @@ Package set which contains all packages that match specified values of specified variable. This class supports the following options: + </para> <itemizedlist> - <listitem><varname>variable</varname>: The name of - the specified variable whose values are checked. + <listitem><para><varname>variable</varname>: The name of + the specified variable whose values are checked.</para> </listitem> - <listitem><varname>includes</varname>: A list of + <listitem><para><varname>includes</varname>: A list of values that must be contained within the specified - variable. + variable.</para> </listitem> - <listitem><varname>excludes</varname>: A list of + <listitem><para><varname>excludes</varname>: A list of values that must not be contained within the specified - variable. + variable.</para> </listitem> - <listitem><varname>metadata-source</varname>: Optional, defaults to + <listitem><para><varname>metadata-source</varname>: Optional, defaults to "vartree". Specifies the repository to use for getting the metadata - to check.</listitem> + to check.</para></listitem> </itemizedlist> - </para> </sect2> <sect2 id='config-set-classes-UnavailableSet'> <title>portage.sets.dbapi.UnavailableSet</title> @@ -529,12 +531,12 @@ packages for which there are no visible ebuilds corresponding to the same $CATEGORY/$PN:$SLOT. This class supports the following options: + </para> <itemizedlist> - <listitem><varname>metadata-source</varname>: Optional, defaults to + <listitem><para><varname>metadata-source</varname>: Optional, defaults to "porttree". Specifies the repository to use for getting the metadata - to check.</listitem> + to check.</para></listitem> </itemizedlist> - </para> </sect2> <sect2 id='config-set-classes-DowngradeSet'> <title>portage.sets.dbapi.DowngradeSet</title> @@ -556,12 +558,12 @@ <title>Single Set Configuration</title> <para> This class supports the following option: + </para> <itemizedlist> - <listitem><varname>debug</varname>: Generate extra output useful to figure out why - certain packages are included in the set, as it's not always obvious. + <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> - </para> </sect3> </sect2> </sect1> @@ -576,20 +578,20 @@ </para> <para> The default sets are: + </para> <itemizedlist> - <listitem><varname>system</varname>: uses <classname>PackagesSystemSet</classname></listitem> - <listitem><varname>world</varname>: uses <classname>WorldSet</classname></listitem> - <listitem><varname>security</varname>: uses <classname>NewAffectedSet</classname> with default options</listitem> - <listitem><varname>installed</varname>: uses <classname>EverythingSet</classname></listitem> - <listitem><varname>preserved-rebuild</varname>: uses <classname>PreservedLibraryConsumerSet</classname></listitem> - <listitem><varname>live-rebuild</varname>: uses <classname>VariableSet</classname></listitem> - <listitem><varname>module-rebuild</varname>: uses <classname>OwnerSet</classname></listitem> - <listitem><varname>downgrade</varname>: uses <classname>DowngradeSet</classname></listitem> - <listitem><varname>unavailable</varname>: uses <classname>UnavailableSet</classname></listitem> + <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>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> - Additionally the default configuration includes a multi set section based on + <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> + file in <filename>/etc/portage/sets</filename> for convenience.</para> </sect1> </chapter> diff --git a/doc/dependency_resolution/decision_making.docbook b/doc/dependency_resolution/decision_making.docbook index 5bcf84388..ffb1a4ab2 100644 --- a/doc/dependency_resolution/decision_making.docbook +++ b/doc/dependency_resolution/decision_making.docbook @@ -18,18 +18,18 @@ to satisfy constraints and minimize cost. The following package states influence the cost calculation for a given combination: + </para> <itemizedlist> <listitem> - installed + <para>installed</para> </listitem> <listitem> - selected (for installation) + <para>selected (for installation)</para> </listitem> <listitem> - not selected (for installation) + <para>not selected (for installation)</para> </listitem> </itemizedlist> - </para> <para> In cost calculations, virtual packages by themselves are considered to cost nothing since they do not directly install anything. diff --git a/doc/dependency_resolution/package_modeling.docbook b/doc/dependency_resolution/package_modeling.docbook index 37cdb6008..beada903e 100644 --- a/doc/dependency_resolution/package_modeling.docbook +++ b/doc/dependency_resolution/package_modeling.docbook @@ -8,41 +8,41 @@ <para> Dependency resolution involves satisfaction of many constraints: + </para> <itemizedlist> <listitem> - Persistent configuration parameters, like those that come from - make.profile, make.conf, and the /etc/portage directory. + <para>Persistent configuration parameters, like those that come from + make.profile, make.conf, and the /etc/portage directory.</para> </listitem> <listitem> - Current command parameters, which may include options, atoms, or sets. + <para>Current command parameters, which may include options, atoms, or sets.</para> </listitem> <listitem> - <link linkend='dependency-resolution-package-modeling-constraint-satisfaction-package-dependencies'> - Package Dependencies</link> + <para><link linkend='dependency-resolution-package-modeling-constraint-satisfaction-package-dependencies'> + Package Dependencies</link></para> </listitem> </itemizedlist> - </para> </sect2> <sect2 id='dependency-resolution-package-modeling-constraint-satisfaction-package-dependencies'> <title>Package Dependencies</title> <para> Common types of package dependencies: + </para> <itemizedlist> <listitem> - Files required for building or installing. Downloads may - be necessary to satisfy these. + <para>Files required for building or installing. Downloads may + be necessary to satisfy these.</para> </listitem> <listitem> - Other packages required to be installed for - buildtime or runtime. + <para>Other packages required to be installed for + buildtime or runtime.</para> </listitem> <listitem> - Blockers that prevent conflicting packages from being installed - simultaneously. + <para>Blockers that prevent conflicting packages from being installed + simultaneously.</para> </listitem> </itemizedlist> - </para> </sect2> </sect1> diff --git a/doc/dependency_resolution/task_scheduling.docbook b/doc/dependency_resolution/task_scheduling.docbook index c8e3608d1..8180e56da 100644 --- a/doc/dependency_resolution/task_scheduling.docbook +++ b/doc/dependency_resolution/task_scheduling.docbook @@ -24,28 +24,28 @@ rather than replaced. The following constraints protect inappropriate packages from being chosen for automatic uninstallation: + </para> <itemizedlist> <listitem> - Installed packages that have been pulled into the current dependency + <para>Installed packages that have been pulled into the current dependency graph will not be uninstalled. Due to <link linkend='dependency-resolution-package-modeling-dependency-neglection'> dependency neglection</link> and special properties of packages in the "system" set, other checks may be necessary in order - to protect inappropriate packages from being uninstalled. + to protect inappropriate packages from being uninstalled.</para> </listitem> <listitem> - An installed package that is matched by a dependency atom from the + <para>An installed package that is matched by a dependency atom from the "system" set will not be uninstalled in advance since it might not - be safe. Such a package will only be uninstalled through replacement. + be safe. Such a package will only be uninstalled through replacement.</para> </listitem> <listitem> - An installed package that is matched by a dependency atom from the + <para>An installed package that is matched by a dependency atom from the "world" set will not be uninstalled if the dependency graph does not contain a replacement package that is matched by the same dependency - atom. + atom.</para> </listitem> </itemizedlist> - </para> <para> In order to ensure that package files remain installed in a usable state whenever possible, uninstallation operations are not executed diff --git a/doc/package/ebuild/phases.docbook b/doc/package/ebuild/phases.docbook index 2cb1b4447..f3e8359ef 100644 --- a/doc/package/ebuild/phases.docbook +++ b/doc/package/ebuild/phases.docbook @@ -10,36 +10,36 @@ </para> <para> The function names for the ebuild phases, listed in order of execution: + </para> <itemizedlist> <listitem> - pkg_setup + <para>pkg_setup</para> </listitem> <listitem> - src_unpack + <para>src_unpack</para> </listitem> <listitem> - src_compile + <para>src_compile</para> </listitem> <listitem> - src_test + <para>src_test</para> </listitem> <listitem> - src_install + <para>src_install</para> </listitem> <listitem> - pkg_preinst + <para>pkg_preinst</para> </listitem> <listitem> - pkg_postinst + <para>pkg_postinst</para> </listitem> <listitem> - pkg_prerm + <para>pkg_prerm</para> </listitem> <listitem> - pkg_postrm + <para>pkg_postrm</para> </listitem> </itemizedlist> - </para> <section id='package-ebuild-phases-previous-installed'> <title>Interaction with previous installed version</title> <para> @@ -48,22 +48,20 @@ </para> <section id='package-ebuild-phases-before-2.1.5'> <title>Upgrade/downgrade order used by versions less than 2.1.5 (deprecated)</title> - <para> <itemizedlist> <listitem> - pkg_preinst + <para>pkg_preinst</para> </listitem> <listitem> - pkg_postinst + <para>pkg_postinst</para> </listitem> <listitem> - pkg_prerm + <para>pkg_prerm</para> </listitem> <listitem> - pkg_postrm + <para>pkg_postrm</para> </listitem> </itemizedlist> - </para> </section> <section id='package-ebuild-phases-after-2.1.5'> <title>Upgrade/downgrade order starting with version 2.1.5</title> @@ -71,22 +69,20 @@ The new order for upgrades and downgrades is identical to the order used for reinstall operations: </para> - <para> <itemizedlist> <listitem> - pkg_preinst + <para>pkg_preinst</para> </listitem> <listitem> - pkg_prerm + <para>pkg_prerm</para> </listitem> <listitem> - pkg_postrm + <para>pkg_postrm</para> </listitem> <listitem> - pkg_postinst + <para>pkg_postinst</para> </listitem> </itemizedlist> - </para> <para> Now that pkg_postinst is called after all other phases, it's not possible to call has_version in pkg_postinst to detect whether the current install |