public inbox for gentoo-commits@lists.gentoo.org
 help / color / mirror / Atom feed
* [gentoo-commits] proj/devmanual:master commit in: general-concepts/slotting/
@ 2021-07-06  8:42 Ulrich Müller
  0 siblings, 0 replies; 6+ messages in thread
From: Ulrich Müller @ 2021-07-06  8:42 UTC (permalink / raw
  To: gentoo-commits

commit:     51542fae88bb6675ea10013646675023dab6189f
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Apr 10 03:41:16 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Jul  6 08:42:38 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=51542fae

general-concepts/slotting: link to wiki page with information on subslots

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 general-concepts/slotting/text.xml | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml
index 870d8fa..9b12d84 100644
--- a/general-concepts/slotting/text.xml
+++ b/general-concepts/slotting/text.xml
@@ -77,11 +77,14 @@ Other ebuilds that install binaries which link to <c>libfoo-2</c> (or <c>libfoo<
 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>.
+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>
 
 <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.
+You may wish to review the
+<uri link="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Subslots">
+QA team's documentation on subslots</uri>.
 </p>
 
 <note>


^ permalink raw reply related	[flat|nested] 6+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: general-concepts/slotting/
@ 2021-07-06  8:42 Ulrich Müller
  0 siblings, 0 replies; 6+ messages in thread
From: Ulrich Müller @ 2021-07-06  8:42 UTC (permalink / raw
  To: gentoo-commits

commit:     7bf32833ba1bf2157cfe0cdaa7b459e8608a783e
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Apr 10 03:01:26 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Jul  6 08:42:39 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7bf32833

general-concepts/slotting: add new 'ABI breakage' subsection

This details the concept of ABI breakage, how to understand it, how to
approach it within ebuilds, and how to solve it.

Closes: https://github.com/gentoo/devmanual/pull/225
Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 general-concepts/slotting/text.xml | 149 +++++++++++++++++++++++++++++++++----
 1 file changed, 133 insertions(+), 16 deletions(-)

diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml
index 9b12d84..d797429 100644
--- a/general-concepts/slotting/text.xml
+++ b/general-concepts/slotting/text.xml
@@ -60,9 +60,110 @@ 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:
+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>
+
+<p>
+You may wish to review the
+<uri link="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Subslots">
+QA team's documentation on subslots</uri>.
+</p>
+
+<note>
+Care must be taken when using sub-slots in a library ebuild for the first time.
+Adding sub-slots will trigger rebuilds for all the packages that already use
+slot-operator dependencies (e.g. switching from SLOT="0" to SLOT="0/14" in
+<c>media-libs/libpng</c> and package <c>foo</c> depends on <c>libpng:0=</c>).
+Therefore, it's best if you start using sub-slots in the library when the
+existing library interface changes.
+</note>
+</body>
+
+<subsection>
+<title>ABI breakage</title>
+<body>
+
+<p>
+There are two ways a library can break compatibility with its consumers.
+</p>
+
+<dl>
+  <dd>
+    ABI (Application Binary Interface): this affects binaries built before the
+    change. Applications linked against a library pre-ABI break may not work
+    correctly after the break. These changes are related to internal structure,
+    such as the size of a <c>struct</c> or the type of an argument (e.g.
+    integer width). Fixing this requires a <e>rebuild</e> of all consumers.
+  </dd>
+  <dd>
+    API (Application Programming Interface): this affects consumers at compile
+    time and usually occurs when a library has deprecated and then removed a
+    function. Fixing this requires a <e>code change</e> in consumers.
+  </dd>
+</dl>
+
+<p>
+Note that subslots are not used exclusively for this purpose. While they form
+the majority of uses in the Gentoo tree, subslots may have a meaning that
+is completely divorced from SONAMEs or ABI breakage. Check the usage in the
+relevant packages before using a subslot operator!
+</p>
+
+<p>
+When made aware of ABI breakage, change the subslot. Note that the subslot does
+not have to strictly be the SONAME and therefore could be an arbitrary string
+(following naming rules).
+</p>
+
+<p>
+Be aware that some upstreams may make releases without verifying if binary
+compatibility has been broken in a minor release. You should check using
+tools like <c>dev-util/libabigail</c> or <e>ABI Laboratory</e> (available
+in Gentoo as <c>dev-util/abi-compliance-checker</c> if you prefer the non-web
+version).
+</p>
+
+<p>
+Generally, consumers <e>which link against</e> a library possessing a subslot
+that <e>represents SONAME or binary compatibility</e> should subscribe to
+it (request to be rebuilt when the subslot changes) with <c>:=</c>. Also, see
+the QA Policy Guide for information on
+<uri link="https://projects.gentoo.org/qa/policy-guide/dependencies.html#proactive-use-of-slot-operators">
+proactively subscribing to subslots</uri> before they are defined.
+</p>
+</body>
+
+<subsubsection>
+<title>General naming of a sub-slot</title>
+<body>
+
+<p>
+As a simple rule of thumb, the SONAME is usually a function of the library's
+linking filename <c>libfoo.so</c> and its <b>first version component</b>.
+The remaining version components are useful for ensuring a monotonic upgrade
+path of consumers, but aren't incorporated into the library's SONAME, which in
+this case would be <c>libfoo.so.1</c>.
+</p>
+
+<p>
+The SONAME being incremented implies that the library's ABI has been broken.
+</p>
+
+<p>
+As a result of the aforementioned convention, ebuilds usually expose the current
+ABI version as the subslot. For this <e>libfoo</e> example, if the library is
+<c>libfoo.so.1.2</c>, the ebuild might set:
+</p>
+
+<codesample lang="ebuild">
+SLOT="0/1"
+</codesample>
+
+<p>
+Further, suppose the 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>
@@ -77,26 +178,42 @@ Other ebuilds that install binaries which link to <c>libfoo-2</c> (or <c>libfoo<
 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>.
-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>
+</subsubsection>
+
+<subsubsection>
+<title>Multiple libraries within a single package</title>
+<body>
 
 <p>
-You may wish to review the
-<uri link="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Subslots">
-QA team's documentation on subslots</uri>.
+A package might need to install several libraries. The canonical example
+of this is <c>media-video/ffmpeg</c>:
 </p>
 
-<note>
-Care must be taken when using sub-slots in a library ebuild for the first time.
-Adding sub-slots will trigger rebuilds for all the packages that already use sub-slot
-dependencies (e.g. Switching from SLOT="0" to SLOT="0/14" in <c>media-libs/libpng</c> and
-package <c>foo</c> depends on <c>libpng:0=</c>).
-Therefore, it's best if you start using sub-slots in the library when the existing library
-interface changes.
-</note>
+<codesample lang="ebuild">
+# Subslot: &lt;libavutil_major&gt;.&lt;libavcodec_major&gt;.&lt;libavformat_major&gt;
+# Since FFmpeg ships several libraries, subslot is kind of limited here.
+# Most consumers will use those three libraries, if a "less used" library
+# changes its soname, consumers will have to be rebuilt the old way
+# (preserve-libs) - which should not be relied upon.
+# If, for example, a package does not link to libavformat and only libavformat
+# changes its ABI then this package will be rebuilt needlessly. Hence, such a
+# package is free _not_ to := depend on FFmpeg but I would strongly encourage
+# doing so since such a case is unlikely.
+SLOT="0/56.58.58"
+</codesample>
+
+<p>
+In such cases, make the subslot a composite of the major SONAMEs of each of
+the installed libraries. This emphasises a point made above <d/> subslots do
+not need to be equal to the exact SONAME of installed libraries, they only need
+to represent in some way ABI compatibility.
+</p>
 
 </body>
+</subsubsection>
+</subsection>
 </section>
 
 <section>


^ permalink raw reply related	[flat|nested] 6+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: general-concepts/slotting/
@ 2021-07-06  8:42 Ulrich Müller
  0 siblings, 0 replies; 6+ messages in thread
From: Ulrich Müller @ 2021-07-06  8:42 UTC (permalink / raw
  To: gentoo-commits

commit:     d6b8eda527e3bef34092043ba4d11c48084aa2ba
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Apr 10 03:35:56 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Jul  6 08:42:38 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d6b8eda5

general-concepts/slotting: s/soname/SONAME/

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 general-concepts/slotting/text.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml
index c675e85..870d8fa 100644
--- a/general-concepts/slotting/text.xml
+++ b/general-concepts/slotting/text.xml
@@ -60,8 +60,8 @@ 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
+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>
 


^ permalink raw reply related	[flat|nested] 6+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: general-concepts/slotting/
@ 2020-02-20 19:07 Ulrich Müller
  0 siblings, 0 replies; 6+ messages in thread
From: Ulrich Müller @ 2020-02-20 19:07 UTC (permalink / raw
  To: gentoo-commits

commit:     61f80a8527d6b64e9598e033aa4b04f920e6b12f
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Mon Feb 17 18:37:31 2020 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Feb 18 16:04:55 2020 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=61f80a85

general-concepts/slotting: SLOT 0 is not special.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 general-concepts/slotting/text.xml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml
index 5bd33b0..28e6696 100644
--- a/general-concepts/slotting/text.xml
+++ b/general-concepts/slotting/text.xml
@@ -13,7 +13,8 @@ parallel. This feature is called slotting.
 
 <p>
 Most packages have no need for slotting. These packages specify <c>SLOT="0"</c>
-in the ebuilds.
+in the ebuilds. This is purely a convention; the package manager does not treat
+<c>0</c> any different from other slot values.
 </p>
 
 <note>


^ permalink raw reply related	[flat|nested] 6+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: general-concepts/slotting/
@ 2016-08-05 16:43 Göktürk Yüksek
  0 siblings, 0 replies; 6+ messages in thread
From: Göktürk Yüksek @ 2016-08-05 16:43 UTC (permalink / raw
  To: gentoo-commits

commit:     41342f0d2038a71a1aa205a2137f482240c027d6
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Fri Aug  5 16:38:43 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Fri Aug  5 16:42:22 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=41342f0d

general-concepts/slotting: be more explicit about what an empty slot is

Reported-By: Amy Winston <amynka <AT> gentoo.org>

 general-concepts/slotting/text.xml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml
index 96aa4fc..652b444 100644
--- a/general-concepts/slotting/text.xml
+++ b/general-concepts/slotting/text.xml
@@ -13,7 +13,8 @@ parallel. This feature is called slotting.
 
 <p>
 Most packages have no need for slotting. These packages specify <c>SLOT="0"</c> in
-the ebuilds. This is <b>not</b> the same as specifying an empty slot <d/> an empty
+the ebuilds. This is <b>not</b> the same as specifying an empty slot
+(<c>SLOT=""</c>) <d/> an empty
 slot means &quot;disable slotting entirely&quot;, and should not be used.
 </p>
 


^ permalink raw reply related	[flat|nested] 6+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: general-concepts/slotting/
@ 2013-05-12 16:03 Markos Chandras
  0 siblings, 0 replies; 6+ messages in thread
From: Markos Chandras @ 2013-05-12 16:03 UTC (permalink / raw
  To: gentoo-commits

commit:     b105ca7cbfe2258c4f1e3c29e03adf4583af5e5b
Author:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
AuthorDate: Sun May 12 16:00:45 2013 +0000
Commit:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
CommitDate: Sun May 12 16:00:45 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=b105ca7c

slotting: Add sub-slots carefully to avoid useless rebuilds

Fixes bug #458838

---
 general-concepts/slotting/text.xml |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml
index bbbfad4..96aa4fc 100644
--- a/general-concepts/slotting/text.xml
+++ b/general-concepts/slotting/text.xml
@@ -80,6 +80,15 @@ 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>
 
+<note>
+Care must be taken when using sub-slots in a library ebuild for the first time.
+Adding sub-slots will trigger rebuilds for all the packages that already use sub-slot
+dependencies (e.g. Switching from SLOT="0" to SLOT="0/14" in <c>media-libs/libpng</c> and
+package <c>foo</c> depends on <c>libpng:0=</c>).
+Therefore, it's best if you start using sub-slots in the library when the existing library
+interface changes.
+</note>
+
 </body>
 </section>
 


^ permalink raw reply related	[flat|nested] 6+ messages in thread
end of thread, other threads:[~2021-07-06  8:42 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-07-06  8:42 [gentoo-commits] proj/devmanual:master commit in: general-concepts/slotting/ Ulrich Müller
  -- strict thread matches above, loose matches on Subject: below --
2021-07-06  8:42 Ulrich Müller
2021-07-06  8:42 Ulrich Müller
2020-02-20 19:07 Ulrich Müller
2016-08-05 16:43 Göktürk Yüksek
2013-05-12 16:03 Markos Chandras

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox