More chapters.

7 files changed, 207 insertions, 1 deletions

diff --git a/chunk.toc b/chunk.toc
index 7c88d4e..d1634bd 100644
--- a/chunk.toc
+++ b/chunk.toc
@@ -18,6 +18,10 @@
     <d:tocentry linkend="general-concepts.install-destinations"><?dbhtml filename="general-concepts/install-destinations/index.html"?></d:tocentry>
     <d:tocentry linkend="general-concepts.licenses"><?dbhtml filename="general-concepts/licenses/index.html"?></d:tocentry>
     <d:tocentry linkend="general-concepts.mirrors"><?dbhtml filename="general-concepts/mirrors/index.html"?></d:tocentry>
+    <d:tocentry linkend="general-concepts.overlay"><?dbhtml filename="general-concepts/overlay/index.html"?></d:tocentry>
+    <d:tocentry linkend="general-concepts.portage-cache"><?dbhtml filename="general-concepts/portage-cache/index.html"?></d:tocentry>
+    <d:tocentry linkend="general-concepts.sandbox"><?dbhtml filename="general-concepts/sandbox/index.html"?></d:tocentry>
+    <d:tocentry linkend="general-concepts.slotting"><?dbhtml filename="general-concepts/slotting/index.html"?></d:tocentry>
   </d:tocentry>
 </toc>
 
diff --git a/content/general-concepts.xmli b/content/general-concepts.xmli
index 217661e..05f0c3d 100644
--- a/content/general-concepts.xmli
+++ b/content/general-concepts.xmli
@@ -28,5 +28,9 @@
   <xi:include parse="xml" href="general-concepts/licenses.xmli" />
   <!-- <xi:include parse="xml" href="general-concepts/linguas.xmli" /> -->
   <xi:include parse="xml" href="general-concepts/mirrors.xmli" />
+  <xi:include parse="xml" href="general-concepts/overlay.xmli" />
+  <xi:include parse="xml" href="general-concepts/portage-cache.xmli" />
+  <xi:include parse="xml" href="general-concepts/sandbox.xmli" />
+  <xi:include parse="xml" href="general-concepts/slotting.xmli" />
 
 </part>
diff --git a/content/general-concepts/dependencies.xmli b/content/general-concepts/dependencies.xmli
index e7333db..39e04f3 100644
--- a/content/general-concepts/dependencies.xmli
+++ b/content/general-concepts/dependencies.xmli
@@ -207,7 +207,7 @@ DEPEND=">=dev-libs/openssl-0.9.7d"
     </section>
   </section>
 
-  <section>
+  <section xml:id="general-concepts.dependencies.slot-dependencies">
     <title>SLOT Dependencies</title>
 
     <para>
diff --git a/content/general-concepts/overlay.xmli b/content/general-concepts/overlay.xmli
new file mode 100644
index 0000000..406b091
--- /dev/null
+++ b/content/general-concepts/overlay.xmli
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xl="http://www.w3.org/1999/xlink"
+	 xmlns:xi="http://www.w3.org/2001/XInclude"
+	 xml:id="general-concepts.overlay">
+
+  <title>Overlay</title>
+
+  <para>
+    Portage can look in multiple places for packages by using an overlay. The locations of overlays are controlled by
+    the <varname>PORTDIR_OVERLAY</varname> variable, which should contain a space-separated list of paths.
+  </para>
+
+  <para>
+    The overlay should contain the same directory structure as <varname>PORTDIR</varname> (although only the necessary
+    directories need be included). For example, a simple overlay might have a directory structure like:
+  </para>
+
+  <programlisting><![CDATA[
+overlay
+|-- dev-util
+    `-- gengetopt
+        |-- Manifest
+        |-- files
+        |   `-- gengetopt-2.13-foobar.patch
+        `-- gengetopt-2.13.ebuild
+]]></programlisting>
+
+  <para>
+    An overlay can be used to 'add' items to the tree (although you must ensure that
+    <filename>/etc/portage/categories</filename> is used if any new categories are added) or to override existing
+    entries.
+  </para>
+
+  <section>
+    <title>Overlay and Eclasses</title>
+
+    <para>
+      Be very careful when using eclasses in an overlay. Portage will not do cache updates when an overlay eclass is
+      changed, nor will it do cache updates when a main Portage tree eclass which is used by an overlay ebuild
+      changes. You may also encounter bogus 'illegal inherit' notices when working with eclasses in an overlay (see
+      <xref linkend="appendices.common-problems.eclass-inherited-illegally"/>).  To be safe, manually
+      <command>touch</command> all relevant overlay files after updating overlay eclasses.
+    </para>
+  </section>
+
+</chapter>
diff --git a/content/general-concepts/portage-cache.xmli b/content/general-concepts/portage-cache.xmli
new file mode 100644
index 0000000..939a1f7
--- /dev/null
+++ b/content/general-concepts/portage-cache.xmli
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xl="http://www.w3.org/1999/xlink"
+	 xmlns:xi="http://www.w3.org/2001/XInclude"
+	 xml:id="general-concepts.portage-cache">
+
+  <title>The Portage Cache</title>
+
+  <para>
+    Portage uses a cache for most top-level variables (<varname>DEPEND</varname>, <varname>DESCRIPTION</varname>,
+    <varname>SRC_URI</varname> and so on). This cache may be generated on a different machine, so these variables must
+    be either static or generated using only unchanging 'version / name' variables (<varname>P</varname>,
+    <varname>PN</varname>, <varname>PV</varname>, <varname>PR</varname>, <varname>PVR</varname> and
+    <varname>PF</varname>).
+  </para>
+
+  <para>
+    So, the following will not work:
+  </para>
+
+  <programlisting language="ebuild"><![CDATA[
+# DO NOT DO THIS!
+if ! has_version "x11-libs/gtk+" ; then
+    DEPEND="${DEPEND}
+            gtk?  ( &gt;=x11-libs/gtk+-2 )
+            !gtk? ( =x11-libs/gtk+-1.2* )"
+fi
+]]></programlisting>
+
+  <para>
+    However, this is legal, since <varname>versionator.eclass</varname> works upon <varname>PV</varname>, and
+    <varname>PV</varname> and <varname>PN</varname> are both static:
+  </para>
+
+  <programlisting language="ebuild"><![CDATA[
+inherit versionator
+
+if [[ $(get_major_version) -ge 7 ]] ; then
+    IUSE="${IUSE} tcltk mzscheme"
+    DEPEND="${DEPEND}
+        tcltk?    ( dev-lang/tcl )
+        mzscheme? ( dev-lisp/mzscheme )"
+    RDEPEND="${RDEPEND}
+        tcltk?    ( dev-lang/tcl )
+        mzscheme? ( dev-lisp/mzscheme )"
+
+    if [[ "${MY_PN}" != "vim-core" ]] ; then
+        RDEPEND="${RDEPEND} !&lt;app-vim/align-30-r1"
+    fi
+fi
+]]></programlisting>
+
+  <section>
+    <title>Conditional Inherits</title>
+
+    <para>
+      Because eclasses modify various cached variables, conditional inheritance is not allowed except where the same
+      results will always be obtained on every system.  For example, inherits based upon <varname>USE</varname> flags
+      are illegal, but inherits based solely upon <varname>PN</varname> are allowed.
+    </para>
+
+    <para>
+      As an example of a legal and possibly useful conditional inherit, some eclasses do:
+    </para>
+
+    <programlisting language="ebuild"><![CDATA[
+if [[ "${PN##*-}" == "cvs" ]] ; then
+    inherit cvs
+fi
+]]></programlisting>
+
+    <para>
+      This allows the same eclass to be used for both regular and <package>-cvs</package> packages.
+    </para>
+  </section>
+</chapter>
diff --git a/content/general-concepts/sandbox.xmli b/content/general-concepts/sandbox.xmli
new file mode 100644
index 0000000..dcf68cf
--- /dev/null
+++ b/content/general-concepts/sandbox.xmli
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xl="http://www.w3.org/1999/xlink"
+	 xmlns:xi="http://www.w3.org/2001/XInclude"
+	 xml:id="general-concepts.sandbox">
+  <title>Sandbox</title>
+
+  <para>
+    During the <function>src_unpack</function>, <function>src_compile</function>, <function>src_test</function> and
+    <function>src_install</function> phases, <filename>ebuild.sh</filename> operates inside a
+    <emphasis>sandbox</emphasis>. This is a special environment which attempts to help prevent badly written ebuilds (or
+    ebuilds working with badly written build systems) accidentally writing outside of permitted locations.
+  </para>
+
+  <para>
+    <emphasis>All packages must build correctly when sandbox is active.</emphasis> Packages must not achieve this by
+    using sneaky tricks to make sandbox warnings not show up — the sandbox is there to ensure that binary packages will
+    work correctly, and that a badly written <filename>Makefile</filename> won't cause problems. Using
+    <command>addwrite</command> is generally <emphasis>not</emphasis> the correct solution.
+  </para>
+
+  <para>
+    See <xref linkend="function-reference.sandbox-functions"/> for details on sandbox-related functions. See <xref
+    linkend="appendices.common-problems.access-violations"/> for suggestions on fixing sandbox-related build problems.
+  </para>
+</chapter>
diff --git a/content/general-concepts/slotting.xmli b/content/general-concepts/slotting.xmli
new file mode 100644
index 0000000..c80b09c
--- /dev/null
+++ b/content/general-concepts/slotting.xmli
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xl="http://www.w3.org/1999/xlink"
+	 xmlns:xi="http://www.w3.org/2001/XInclude"
+	 xml:id="general-concepts.slotting">
+  <title>Slotting</title>
+
+  <para>
+    Packages can support having multiple versions installed simultaneously. This is useful for libraries which may have
+    changed interfaces between versions — for example, the <package>gtk+</package> package can install both versions
+    <literal>1.2</literal> and <literal>2.6</literal> in parallel. This feature is called slotting.
+  </para>
+
+  <para>
+    Most packages have no need for slotting. These packages specify <literal>SLOT="0"</literal> in the ebuilds. This is
+    <emphasis>not</emphasis> the same as specifying an empty slot — an empty slot means "disable slotting entirely", and
+    should not be used.
+  </para>
+
+  <para>
+    Portage permits at most one instance of a package installation <emphasis>per <varname>SLOT</varname>
+    value</emphasis>.  For example, say we have the following:
+  </para>
+
+  <itemizedlist>
+    <listitem><para><package>foo-1.1</package> with <literal>SLOT="1"</literal></para></listitem>
+    <listitem><para><package>foo-1.2</package> with <literal>SLOT="1"</literal></para></listitem>
+    <listitem><para><package>foo-2.0</package> with <literal>SLOT="2"</literal></para></listitem>
+    <listitem><para><package>foo-2.1</package> with <literal>SLOT="2"</literal></para></listitem>
+  </itemizedlist>
+
+  <para>
+    Then the user could have, say, <package>foo-1.2</package> and <package>foo-2.0</package> installed in parallel,
+    but <emphasis>not</emphasis> <package>foo-1.1</package> and <package>foo-1.2</package>. Note that it is entirely
+    possible that the user may have <package>foo-2.0</package> installed and no <package>foo-1.x</package> at all.
+  </para>
+
+  <para>
+    To <varname>DEPEND</varname> upon a package in a specific slot, refer to <xref
+    linkend="general-concepts.dependencies.slot-dependencies"/>.
+  </para>
+
+  <para>
+    Currently portage will accept an arbitrary string for the value of <varname>SLOT</varname>. For future
+    compatibility, it is recommended that slots contain only characters which are allowed in an ebuild name or version
+    (alphanumerics, hypens, full stops, underscores, the plus character) — other characters may cause problems with
+    future portage enhancements.
+  </para>
+</chapter>