| 1 |
commit: 7bf32833ba1bf2157cfe0cdaa7b459e8608a783e |
| 2 |
Author: Sam James <sam <AT> gentoo <DOT> org> |
| 3 |
AuthorDate: Sat Apr 10 03:01:26 2021 +0000 |
| 4 |
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org> |
| 5 |
CommitDate: Tue Jul 6 08:42:39 2021 +0000 |
| 6 |
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7bf32833 |
| 7 |
|
| 8 |
general-concepts/slotting: add new 'ABI breakage' subsection |
| 9 |
|
| 10 |
This details the concept of ABI breakage, how to understand it, how to |
| 11 |
approach it within ebuilds, and how to solve it. |
| 12 |
|
| 13 |
Closes: https://github.com/gentoo/devmanual/pull/225 |
| 14 |
Signed-off-by: Sam James <sam <AT> gentoo.org> |
| 15 |
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org> |
| 16 |
|
| 17 |
general-concepts/slotting/text.xml | 149 +++++++++++++++++++++++++++++++++---- |
| 18 |
1 file changed, 133 insertions(+), 16 deletions(-) |
| 19 |
|
| 20 |
diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml |
| 21 |
index 9b12d84..d797429 100644 |
| 22 |
--- a/general-concepts/slotting/text.xml |
| 23 |
+++ b/general-concepts/slotting/text.xml |
| 24 |
@@ -60,9 +60,110 @@ automatically rebuilt</uri> when the subslot of a runtime dependency changes. |
| 25 |
</p> |
| 26 |
|
| 27 |
<p> |
| 28 |
-For example, suppose package <c>foo</c> installs a library whose SONAME is |
| 29 |
-different for different versions. It would be reasonable to use the SONAME version |
| 30 |
-as the sub-slot name: |
| 31 |
+If an ebuild does not explicitly declare a sub-slot, the regular slot is used |
| 32 |
+as the value of the sub-slot by default. |
| 33 |
+</p> |
| 34 |
+ |
| 35 |
+<p> |
| 36 |
+You may wish to review the |
| 37 |
+<uri link="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Subslots"> |
| 38 |
+QA team's documentation on subslots</uri>. |
| 39 |
+</p> |
| 40 |
+ |
| 41 |
+<note> |
| 42 |
+Care must be taken when using sub-slots in a library ebuild for the first time. |
| 43 |
+Adding sub-slots will trigger rebuilds for all the packages that already use |
| 44 |
+slot-operator dependencies (e.g. switching from SLOT="0" to SLOT="0/14" in |
| 45 |
+<c>media-libs/libpng</c> and package <c>foo</c> depends on <c>libpng:0=</c>). |
| 46 |
+Therefore, it's best if you start using sub-slots in the library when the |
| 47 |
+existing library interface changes. |
| 48 |
+</note> |
| 49 |
+</body> |
| 50 |
+ |
| 51 |
+<subsection> |
| 52 |
+<title>ABI breakage</title> |
| 53 |
+<body> |
| 54 |
+ |
| 55 |
+<p> |
| 56 |
+There are two ways a library can break compatibility with its consumers. |
| 57 |
+</p> |
| 58 |
+ |
| 59 |
+<dl> |
| 60 |
+ <dd> |
| 61 |
+ ABI (Application Binary Interface): this affects binaries built before the |
| 62 |
+ change. Applications linked against a library pre-ABI break may not work |
| 63 |
+ correctly after the break. These changes are related to internal structure, |
| 64 |
+ such as the size of a <c>struct</c> or the type of an argument (e.g. |
| 65 |
+ integer width). Fixing this requires a <e>rebuild</e> of all consumers. |
| 66 |
+ </dd> |
| 67 |
+ <dd> |
| 68 |
+ API (Application Programming Interface): this affects consumers at compile |
| 69 |
+ time and usually occurs when a library has deprecated and then removed a |
| 70 |
+ function. Fixing this requires a <e>code change</e> in consumers. |
| 71 |
+ </dd> |
| 72 |
+</dl> |
| 73 |
+ |
| 74 |
+<p> |
| 75 |
+Note that subslots are not used exclusively for this purpose. While they form |
| 76 |
+the majority of uses in the Gentoo tree, subslots may have a meaning that |
| 77 |
+is completely divorced from SONAMEs or ABI breakage. Check the usage in the |
| 78 |
+relevant packages before using a subslot operator! |
| 79 |
+</p> |
| 80 |
+ |
| 81 |
+<p> |
| 82 |
+When made aware of ABI breakage, change the subslot. Note that the subslot does |
| 83 |
+not have to strictly be the SONAME and therefore could be an arbitrary string |
| 84 |
+(following naming rules). |
| 85 |
+</p> |
| 86 |
+ |
| 87 |
+<p> |
| 88 |
+Be aware that some upstreams may make releases without verifying if binary |
| 89 |
+compatibility has been broken in a minor release. You should check using |
| 90 |
+tools like <c>dev-util/libabigail</c> or <e>ABI Laboratory</e> (available |
| 91 |
+in Gentoo as <c>dev-util/abi-compliance-checker</c> if you prefer the non-web |
| 92 |
+version). |
| 93 |
+</p> |
| 94 |
+ |
| 95 |
+<p> |
| 96 |
+Generally, consumers <e>which link against</e> a library possessing a subslot |
| 97 |
+that <e>represents SONAME or binary compatibility</e> should subscribe to |
| 98 |
+it (request to be rebuilt when the subslot changes) with <c>:=</c>. Also, see |
| 99 |
+the QA Policy Guide for information on |
| 100 |
+<uri link="https://projects.gentoo.org/qa/policy-guide/dependencies.html#proactive-use-of-slot-operators"> |
| 101 |
+proactively subscribing to subslots</uri> before they are defined. |
| 102 |
+</p> |
| 103 |
+</body> |
| 104 |
+ |
| 105 |
+<subsubsection> |
| 106 |
+<title>General naming of a sub-slot</title> |
| 107 |
+<body> |
| 108 |
+ |
| 109 |
+<p> |
| 110 |
+As a simple rule of thumb, the SONAME is usually a function of the library's |
| 111 |
+linking filename <c>libfoo.so</c> and its <b>first version component</b>. |
| 112 |
+The remaining version components are useful for ensuring a monotonic upgrade |
| 113 |
+path of consumers, but aren't incorporated into the library's SONAME, which in |
| 114 |
+this case would be <c>libfoo.so.1</c>. |
| 115 |
+</p> |
| 116 |
+ |
| 117 |
+<p> |
| 118 |
+The SONAME being incremented implies that the library's ABI has been broken. |
| 119 |
+</p> |
| 120 |
+ |
| 121 |
+<p> |
| 122 |
+As a result of the aforementioned convention, ebuilds usually expose the current |
| 123 |
+ABI version as the subslot. For this <e>libfoo</e> example, if the library is |
| 124 |
+<c>libfoo.so.1.2</c>, the ebuild might set: |
| 125 |
+</p> |
| 126 |
+ |
| 127 |
+<codesample lang="ebuild"> |
| 128 |
+SLOT="0/1" |
| 129 |
+</codesample> |
| 130 |
+ |
| 131 |
+<p> |
| 132 |
+Further, suppose the package <c>foo</c> installs a library whose SONAME is |
| 133 |
+different for different versions. It would be reasonable to use the SONAME |
| 134 |
+version as the sub-slot name: |
| 135 |
</p> |
| 136 |
|
| 137 |
<ul> |
| 138 |
@@ -77,26 +178,42 @@ Other ebuilds that install binaries which link to <c>libfoo-2</c> (or <c>libfoo< |
| 139 |
can then request to be automatically rebuilt when the installed version of |
| 140 |
<c>foo:2</c> or <c>foo:1</c> changes sub-slots <d/> for example, when the user |
| 141 |
upgrades from <c>foo-2.0</c> to <c>foo-2.1</c>. |
| 142 |
-If an ebuild does not explicitly declare a sub-slot, the regular slot is used |
| 143 |
-as the value of the sub-slot by default. |
| 144 |
</p> |
| 145 |
+</body> |
| 146 |
+</subsubsection> |
| 147 |
+ |
| 148 |
+<subsubsection> |
| 149 |
+<title>Multiple libraries within a single package</title> |
| 150 |
+<body> |
| 151 |
|
| 152 |
<p> |
| 153 |
-You may wish to review the |
| 154 |
-<uri link="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Subslots"> |
| 155 |
-QA team's documentation on subslots</uri>. |
| 156 |
+A package might need to install several libraries. The canonical example |
| 157 |
+of this is <c>media-video/ffmpeg</c>: |
| 158 |
</p> |
| 159 |
|
| 160 |
-<note> |
| 161 |
-Care must be taken when using sub-slots in a library ebuild for the first time. |
| 162 |
-Adding sub-slots will trigger rebuilds for all the packages that already use sub-slot |
| 163 |
-dependencies (e.g. Switching from SLOT="0" to SLOT="0/14" in <c>media-libs/libpng</c> and |
| 164 |
-package <c>foo</c> depends on <c>libpng:0=</c>). |
| 165 |
-Therefore, it's best if you start using sub-slots in the library when the existing library |
| 166 |
-interface changes. |
| 167 |
-</note> |
| 168 |
+<codesample lang="ebuild"> |
| 169 |
+# Subslot: <libavutil_major>.<libavcodec_major>.<libavformat_major> |
| 170 |
+# Since FFmpeg ships several libraries, subslot is kind of limited here. |
| 171 |
+# Most consumers will use those three libraries, if a "less used" library |
| 172 |
+# changes its soname, consumers will have to be rebuilt the old way |
| 173 |
+# (preserve-libs) - which should not be relied upon. |
| 174 |
+# If, for example, a package does not link to libavformat and only libavformat |
| 175 |
+# changes its ABI then this package will be rebuilt needlessly. Hence, such a |
| 176 |
+# package is free _not_ to := depend on FFmpeg but I would strongly encourage |
| 177 |
+# doing so since such a case is unlikely. |
| 178 |
+SLOT="0/56.58.58" |
| 179 |
+</codesample> |
| 180 |
+ |
| 181 |
+<p> |
| 182 |
+In such cases, make the subslot a composite of the major SONAMEs of each of |
| 183 |
+the installed libraries. This emphasises a point made above <d/> subslots do |
| 184 |
+not need to be equal to the exact SONAME of installed libraries, they only need |
| 185 |
+to represent in some way ABI compatibility. |
| 186 |
+</p> |
| 187 |
|
| 188 |
</body> |
| 189 |
+</subsubsection> |
| 190 |
+</subsection> |
| 191 |
</section> |
| 192 |
|
| 193 |
<section> |
Archives