[gentoo-commits] proj/devmanual:master commit in: general-concepts/dependencies/, general-concepts/slotting/, ebuild-writing/eapi/

["Markos Chandras" <hwoarang@gentoo.org>]

commit:     9c3bba54f96fc96c0f3e4929b3bc84a3d84d0aa9
Author:     Alexandre Rostovtsev <tetromino <AT> gentoo <DOT> org>
AuthorDate: Mon Dec 10 14:20:00 2012 +0000
Commit:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
CommitDate: Sat Jan 19 10:20:10 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=9c3bba54

eapi: Improve sub-slot and slot operator documentation, bug #446740

Add sub-slots to the Slotting chapter. Update the slot name sections
to match current portage versions (as noted by Arfrever). Add slot
operators to the Dependencies chapter, and describe sub-slot
dependencies (as suggested by Arfrever). Rephrase the slot operator
documentation in the EAPI Usage chapter to be a bit more readable
and a bit less PMS-like, explain sub-slot dependencies in more detail,
and add brief examples.

---
 ebuild-writing/eapi/text.xml           |   34 +++++++++++++++---
 general-concepts/dependencies/text.xml |   39 +++++++++++++++++++++
 general-concepts/slotting/text.xml     |   59 ++++++++++++++++++++++++++++---
 3 files changed, 121 insertions(+), 11 deletions(-)

diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml
index a871067..ec5652f 100644
--- a/ebuild-writing/eapi/text.xml
+++ b/ebuild-writing/eapi/text.xml
@@ -704,21 +704,45 @@ REQUIRED_USE="|| ( foo bar baz )"
 		</p>
 	</li>
 	<li>
-		<p><b>Dependency atom slot operators</b></p>
+		<p><b>Slot operators and sub-slots in dependencies</b></p>
 		<p>
-		A slot dependency may contain an optional sub-slot part that follows the regular slot and is delimited by a <c>/</c> character. An operator slot dependency consists of a colon followed by one of the following operators:
+		A slot dependency may contain an optional sub-slot part that follows the regular slot and is delimited by a <c>/</c> character. This can be useful for packages installing pre-built binaries that require a library with a specific soname version which corresponds to the sub-slot. For example:
+		</p>
+		<codesample lang="ebuild">
+RDEPEND="dev-libs/foo:0/3"
+		</codesample>
+		<p>
+		Dependency atoms can use <b>slot operators</b> to clarify what should happen if the slot and/or sub-slot of a runtime dependency changes:
 		</p>
 		<ul>
 			<li>
-			<c>*</c> Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package will not break if the matched package is uninstalled and replaced by a different matching package in a different slot.
+			<c>:*</c> Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package specifying the dependency will not break if the package matching the dependency is replaced by a different matching package with a different slot and/or sub-slot.
 			</li>
 			<li>
-			<c>=</c> Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package will break unless a matching package with slot and sub-slot equal to the slot and sub-slot of the best installed version at the time the package was installed is available.
+			<c>:=</c> Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package specifying the dependency will break unless there is available a package matching the dependency and whose slot and sub-slot are equal to the slot and sub-slot of the best installed version that had matched this dependency at the time when the package specifying this dependency had been installed.
 			</li>
 			<li>
-			<c>slot=</c> Indicates that only a specific slot value is acceptable, and otherwise behaves identically to the plain equals slot operator.
+			<c>:slot=</c> Indicates that only a specific slot value is acceptable, and otherwise behaves identically to the <c>:=</c> operator.
+				<note>
+				use <c>:slot/subslot</c> without a <c>=</c> to depend on a specific slot and sub-slot pair; it's a syntax error to use <c>:slot/subslot=</c> in an ebuild.
+				</note>
 			</li>
 		</ul>
+		<p>
+		The <c>:slot</c> dependency syntax continues to behave like in EAPI=4 or earlier, i.e. it indicates that only the specific slot value is acceptable, but the package will not break when the version matching the runtime dependency is replaced by a version with a different sub-slot.
+		</p>
+		<p>
+		For example:
+		</p>
+		<codesample lang="ebuild">
+RDEPEND="dev-libs/foo:2=
+	&gt;=dev-libs/bar-0.9:=
+	media-gfx/baz:*
+	x11-misc/wombat:0"
+		</codesample>
+		<p>
+		means that the package should be rebuilt when <c>foo:2</c> or <c>&gt;=bar-0.9</c> are upgraded to versions with different subslots, but that changes in subslots of <c>baz</c> or <c>wombat:0</c> should be ignored.
+		</p>
 	</li>
 </ul>
 </body>

diff --git a/general-concepts/dependencies/text.xml b/general-concepts/dependencies/text.xml
index ba4a46c..ce25fa7 100644
--- a/general-concepts/dependencies/text.xml
+++ b/general-concepts/dependencies/text.xml
@@ -267,6 +267,45 @@ DEPEND="qt3? ( x11-libs/qt:3 )
     gtk? ( x11-libs/gtk+:2 )
 </codesample>
 
+<subsection>
+<title>Slot Operators</title>
+<body>
+
+<p>
+In <c>EAPI="5"</c> and higher, you can use slot operators appended to the package
+name to declare whether or not your package should be rebuilt after the versions
+satisfying its runtime dependencies are updated to versions with a different slot
+or <uri link="::general-concepts/slotting#Sub-Slots">sub-slot</uri>:
+</p>
+
+<ul>
+  <li><c>:=</c> means that any slot is acceptable, and that your package should be
+  rebuilt if the version best matching the runtime dependency is updated to a
+  version with a different slot or subslot;</li>
+  <li><c>:*</c> means that any slot is acceptable, and explicitly declares that
+  changes in the slot or sub-slot can be ignored;</li>
+  <li><c>:SLOT=</c> means that only the 'SLOT' slot is acceptable, and that your
+  package should be rebuilt if the version matching the runtime dependency is
+  updated to another version with this slot but with a different subslot;</li>
+  <li><c>:SLOT</c> means that only the 'SLOT' slot is acceptable, and that changes
+  in the sub-slot can be ignored (like in previous EAPIs).</li>
+  <li><c>:SLOT/SUBSLOT</c> means a dependency on a specific slot and sub-slot pair,
+  which can be useful for packages installing pre-built binaries that require a
+  library with a particular soname version corresponding to the sub-slot.</li>
+</ul>
+
+<p>
+For example:
+</p>
+
+<codesample lang="ebuild">
+RDEPEND="media-libs/cogl:1.0=
+    gnutls? ( &gt;=net-libs/gnutls-2.8:= )"
+</codesample>
+
+</body>
+</subsection>
+
 </body>
 </section>
 

diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml
index 47816bc..bbbfad4 100644
--- a/general-concepts/slotting/text.xml
+++ b/general-concepts/slotting/text.xml
@@ -7,7 +7,7 @@
 <p>
 Packages can support having multiple versions installed simultaneously. This is
 useful for libraries which may have changed interfaces between versions <d/> for
-example, the <c>gtk+</c> package can install both versions <c>1.2</c> and <c>2.6</c> in
+example, the <c>gtk+</c> package can install both versions <c>2.24</c> and <c>3.6</c> in
 parallel. This feature is called slotting.
 </p>
 
@@ -39,15 +39,62 @@ possible that the user may have <c>foo-2.0</c> installed and no <c>foo-1.x</c> a
 To <c>DEPEND</c> upon a package in a specific slot, refer to
 <uri link="::general-concepts/dependencies#SLOT Dependencies" />.
 </p>
+</body>
+
+<section>
+<title>Sub-Slots</title>
+
+<body>
+<p>
+Sometimes a package installs a library that changes interfaces between versions,
+but it's undesirable or inconvenient to allow some of these versions to be installed
+simultaneously. In <c>EAPI=5</c> and higher, this situation can be handled by
+using sub-slots, which are delimited from the regular slot by a <c>/</c> character,
+as in <c>SLOT="slot/subslot"</c>. Packages can
+<uri link="::general-concepts/dependencies#Slot Operators">request to be
+automatically rebuilt</uri> when the subslot of a runtime dependency changes.
+</p>
+
+<p>
+For example, suppose package <c>foo</c> installs a library whose soname is
+different for different versions. It would be reasonable to use the soname version
+as the sub-slot name:
+</p>
+
+<ul>
+  <li><c>foo-1.1</c> installs <c>libfoo.so.5</c> <d/> <c>SLOT="1/5"</c></li>
+  <li><c>foo-1.2</c> installs <c>libfoo.so.6</c> <d/> <c>SLOT="1/6"</c></li>
+  <li><c>foo-2.0</c> installs <c>libfoo-2.so.0</c> <d/> <c>SLOT="2/0"</c></li>
+  <li><c>foo-2.1</c> installs <c>libfoo-2.so.1</c> <d/> <c>SLOT="2/1"</c></li>
+</ul>
 
 <p>
-Currently portage will accept an arbitrary string for the value of <c>SLOT</c>. 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) <d/> other characters may cause problems with
-future portage enhancements.
+Other ebuilds that install binaries which link to <c>libfoo-2</c> (or <c>libfoo</c>)
+can then request to be automatically rebuilt when the installed version of
+<c>foo:2</c> or <c>foo:1</c> changes sub-slots <d/> for example, when the user
+upgrades from <c>foo-2.0</c> to <c>foo-2.1</c>.
 </p>
+
+<p>
+If an ebuild does not explicitly declare a sub-slot, the regular slot is used
+as the value of the sub-slot by default.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Slot Names</title>
+
+<body>
+<p>
+Current versions of portage accept slot and sub-slot names that begin with an
+alphanumeric character or <c>'_'</c>, and contain alphanumerics and <c>'_'</c>,
+<c>'-'</c>, <c>'.'</c>, and <c>'+'</c> characters.
+</p>
+
 </body>
+</section>
 
 </chapter>
 </guide>