diff options
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-01-05 01:37:01 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-01-05 01:37:01 +0000
commit0c6af1874d3044ca6883ae0a6630cae6fe7317ac (patch)
parent95c0a8dc6a3905117fcefde8f33192482fe2523d (diff)
Document sets
4 files changed, 100 insertions, 4 deletions
diff --git a/NEWS b/NEWS
index e0dc15e..f762477 100644
--- a/NEWS
+++ b/NEWS
@@ -21,6 +21,8 @@ of every change, see the ChangeLog.
* qualudis now supports --archs and --exclude-archs.
+ * Documentation on sets is now provided.
* The merge and unmerge utilities are now called with an explicit path.
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8190bf8..6ef72a4 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -22,17 +22,19 @@ htmlfiles = \
cachefiles.html \
configuration.html \
portagedifferences.html \
- programmingwithpaludis.html
+ programmingwithpaludis.html \
+ sets.html
EXTRA_DIST = doxygen.conf.in header.html footer.html paludis.css \
$(docfiles) $(tagfiles) htaccess \
news.html.skel index.html.skel changelog.html.skel licence.html.skel authors.html.skel \
faq.html.skel htmlheader.html htmlfooter.html migration.html.skel cachefiles.html.skel \
- configuration.html.skel portagedifferences.html.skel programmingwithpaludis.html.skel
+ configuration.html.skel portagedifferences.html.skel programmingwithpaludis.html.skel \
+ sets.html.skel
CLEANFILES = *~ news.html index.html changelog.html licence.html authors.html faq.html \
migration.html cachefiles.html configuration.html portagedifferences.html programmingwithpaludis.html \
- cleannews cleanchangelog cleanauthors cleanfaqtoc cleanbasiccppapp cleanbasicrubyapp
+ sets.html cleannews cleanchangelog cleanauthors cleanfaqtoc cleanbasiccppapp cleanbasicrubyapp
MAINTAINERCLEANFILES = Makefile.in $(tagfiles)
@@ -141,6 +143,13 @@ configuration.html : configuration.html.skel htmlheader.html htmlfooter.html
-e '/@FOOTER@/d' \
< $(srcdir)/configuration.html.skel > configuration.html
+sets.html :sets.html.skel htmlheader.html htmlfooter.html
+ sed -e '/@HEADER@/r htmlheader.html' \
+ -e '/@HEADER@/d' \
+ -e '/@FOOTER@/r htmlfooter.html' \
+ -e '/@FOOTER@/d' \
+ < $(srcdir)/sets.html.skel >sets.html
migration.html : migration.html.skel htmlheader.html htmlfooter.html
sed -e '/@HEADER@/r htmlheader.html' \
-e '/@HEADER@/d' \
diff --git a/doc/index.html.skel b/doc/index.html.skel
index 58d8335..d78dd52 100644
--- a/doc/index.html.skel
+++ b/doc/index.html.skel
@@ -36,7 +36,8 @@
<li>There is <a href="configuration.html">documentation on the
configuration files</a> and <a href="cachefiles.html">the
- various optional caches</a> used by Paludis.</li>
+ various optional caches</a> used by Paludis. There is also documentation on
+ <a href="sets.html">sets (including how user defined sets work)</a>.</li>
<li><strong>Support</strong> is available via <code>#paludis</code> on
<code>irc.freenode.net</code> or the <a
diff --git a/doc/sets.html.skel b/doc/sets.html.skel
new file mode 100644
index 0000000..ea60bc6
--- /dev/null
+++ b/doc/sets.html.skel
@@ -0,0 +1,84 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html lang="en" xml:lang="en">
+<title>Paludis, the Other Package Mangler</title>
+<link rel="stylesheet" href="paludis.css" type="text/css" />
+<h1>Paludis, the Other Package Mangler</h1>
+<p>This document explains the concept known to Paludis as a 'set', and describes the standard
+internal sets and how to create new sets.</p>
+<h3>Formal Set Description</h3>
+<p>Internally, a set is a name with an associated dependency-style specification. In most cases
+the dependency specification will be an 'all-of' collection of package dependencies, although
+this is not a hard restriction.</p>
+<p>There are multiple origins for sets:</p>
+ <li>Some environment classes define their own package sets (possibly via user configuration
+ files). A set defined by the environment <em>overrides</em> any later set of the same name.</li>
+ <li>Most repositories define their own package sets. Some of these are defined internally --
+ examples include <code>everything</code>, <code>system</code>, <code>world</code> and
+ <code>security</code>. Repository classes may also provide a way for additional sets to be
+ defined by the repository maintainer. If multiple repositories define a named set, the
+ resulting set is all of these repository sets merged using an 'all-of' composite. The
+ <code>everything</code> and <code>world</code> sets automatically contain <code>system</code>.</li>
+ <li>Finally, the <code>everything</code>, <code>system</code>, <code>world</code> and
+ <code>security</code> sets always exist, even if no repositories nor the environment defines
+ them.</li>
+<p><strong>Important:</strong> a set is a named collecion of <em>dependency specifications</em>, not
+a collection of packages.</p>
+<h3>User Defined Sets</h3>
+<p>The <code>DefaultEnvironment</code> environment class allows user defined package sets via
+text files. These should be named <code><em>setname</em>.conf</code> and placed in
+<code><em>confdir</em>/sets/</code>, where <code><em>confdir</em></code> is the configuration directory
+in which <code>use.conf</code> et al. reside. The format is as follows:</p>
+ <li>Comments lines start with a <code>#</code>. These, and blank lines, are ignored.</li>
+ <li>Lines consist of a symbol, followed by whitespace, followed by a package dependency
+ atom.</li>
+ <li>The symbol <code>*</code> should be used to mean "include this package dependency atom in
+ the set".</li>
+ <li>The symbol <code>?</code> should be used to mean "include this package dependency atom in
+ the set if and only if the package part of the atom is matched by an installed package". For
+ example, the line <code>? &gt;=app-editors/vim-7</code> means requires <code>vim-7</code> if
+ and only if <code>app-editors/vim</code> (any version) is already installed.</li>
+<p>Most users will only have use for <code>*</code> lines.</p>
+<h3>Portage Repositories Defined Sets</h3>
+<p>Portage format repositories can supply their own sets. The <code>system</code> and
+<code>security</code> sets are defined programmatically; other sets are defined by a file
+named <code>sets/<em>setname</em>.conf</code>, which should be in the format described for
+user defined sets above.</p>
+<h3>Using Sets</h3>
+<p>Sets can currently be used as targets for <code>paludis --query</code> and
+<code>paludis --install</code>. In future they may be allowed in <code>use.conf</code> etc.,
+but this is currently unsupported.</p>