diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2018-01-11 11:02:11 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-02-14 15:25:28 +0000 |
commit | a60d9e29171eaf73dc5ce70fdd2ce92ec07876ec (patch) | |
tree | a0e6b77735696cf59cc23614fe885992b10d252a /documentation/overview-manual | |
parent | 00f87f84165964f262f8bb97378cfbef4b0c325a (diff) | |
download | poky-a60d9e29171eaf73dc5ce70fdd2ce92ec07876ec.tar.gz |
overview-manual, ref-manual: Moved auto added runtime deps section
Fixes [YOCTO #12370]
The "Automatically Added Runtime Dependencies" section moved from the
ref-manual to the overview-manual. This topic is concepts and needs
to live in the new overview-manual's concepts chapter. Fixed some
links in the ref-manual and one in the dev-manual.
(From yocto-docs rev: fa3e12030ce867cb81feed453d35c3a3643decd2)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/overview-manual')
-rw-r--r-- | documentation/overview-manual/overview-concepts.xml | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/documentation/overview-manual/overview-concepts.xml b/documentation/overview-manual/overview-concepts.xml index 2d704923fa..9fb3283fee 100644 --- a/documentation/overview-manual/overview-concepts.xml +++ b/documentation/overview-manual/overview-concepts.xml | |||
@@ -1106,6 +1106,153 @@ | |||
1106 | </section> | 1106 | </section> |
1107 | </section> | 1107 | </section> |
1108 | 1108 | ||
1109 | <section id='automatically-added-runtime-dependencies'> | ||
1110 | <title>Automatically Added Runtime Dependencies</title> | ||
1111 | |||
1112 | <para> | ||
1113 | The OpenEmbedded build system automatically adds common types of | ||
1114 | runtime dependencies between packages, which means that you do not | ||
1115 | need to explicitly declare the packages using | ||
1116 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>. | ||
1117 | Three automatic mechanisms exist (<filename>shlibdeps</filename>, | ||
1118 | <filename>pcdeps</filename>, and <filename>depchains</filename>) | ||
1119 | that handle shared libraries, package configuration (pkg-config) | ||
1120 | modules, and <filename>-dev</filename> and | ||
1121 | <filename>-dbg</filename> packages, respectively. | ||
1122 | For other types of runtime dependencies, you must manually declare | ||
1123 | the dependencies. | ||
1124 | <itemizedlist> | ||
1125 | <listitem><para> | ||
1126 | <filename>shlibdeps</filename>: | ||
1127 | During the | ||
1128 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
1129 | task of each recipe, all shared libraries installed by the | ||
1130 | recipe are located. | ||
1131 | For each shared library, the package that contains the | ||
1132 | shared library is registered as providing the shared | ||
1133 | library. | ||
1134 | More specifically, the package is registered as providing | ||
1135 | the | ||
1136 | <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink> | ||
1137 | of the library. | ||
1138 | The resulting shared-library-to-package mapping | ||
1139 | is saved globally in | ||
1140 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink> | ||
1141 | by the | ||
1142 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink> | ||
1143 | task.</para> | ||
1144 | |||
1145 | <para>Simultaneously, all executables and shared libraries | ||
1146 | installed by the recipe are inspected to see what shared | ||
1147 | libraries they link against. | ||
1148 | For each shared library dependency that is found, | ||
1149 | <filename>PKGDATA_DIR</filename> is queried to | ||
1150 | see if some package (likely from a different recipe) | ||
1151 | contains the shared library. | ||
1152 | If such a package is found, a runtime dependency is added | ||
1153 | from the package that depends on the shared library to the | ||
1154 | package that contains the library.</para> | ||
1155 | |||
1156 | <para>The automatically added runtime dependency also | ||
1157 | includes a version restriction. | ||
1158 | This version restriction specifies that at least the | ||
1159 | current version of the package that provides the shared | ||
1160 | library must be used, as if | ||
1161 | "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)" | ||
1162 | had been added to | ||
1163 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>. | ||
1164 | This forces an upgrade of the package containing the shared | ||
1165 | library when installing the package that depends on the | ||
1166 | library, if needed.</para> | ||
1167 | |||
1168 | <para>If you want to avoid a package being registered as | ||
1169 | providing a particular shared library (e.g. because the library | ||
1170 | is for internal use only), then add the library to | ||
1171 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></ulink> | ||
1172 | inside the package's recipe. | ||
1173 | </para></listitem> | ||
1174 | <listitem><para> | ||
1175 | <filename>pcdeps</filename>: | ||
1176 | During the | ||
1177 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
1178 | task of each recipe, all pkg-config modules | ||
1179 | (<filename>*.pc</filename> files) installed by the recipe | ||
1180 | are located. | ||
1181 | For each module, the package that contains the module is | ||
1182 | registered as providing the module. | ||
1183 | The resulting module-to-package mapping is saved globally in | ||
1184 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink> | ||
1185 | by the | ||
1186 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink> | ||
1187 | task.</para> | ||
1188 | |||
1189 | <para>Simultaneously, all pkg-config modules installed by | ||
1190 | the recipe are inspected to see what other pkg-config | ||
1191 | modules they depend on. | ||
1192 | A module is seen as depending on another module if it | ||
1193 | contains a "Requires:" line that specifies the other module. | ||
1194 | For each module dependency, | ||
1195 | <filename>PKGDATA_DIR</filename> is queried to see if some | ||
1196 | package contains the module. | ||
1197 | If such a package is found, a runtime dependency is added | ||
1198 | from the package that depends on the module to the package | ||
1199 | that contains the module. | ||
1200 | <note> | ||
1201 | The <filename>pcdeps</filename> mechanism most often | ||
1202 | infers dependencies between <filename>-dev</filename> | ||
1203 | packages. | ||
1204 | </note> | ||
1205 | </para></listitem> | ||
1206 | <listitem><para> | ||
1207 | <filename>depchains</filename>: | ||
1208 | If a package <filename>foo</filename> depends on a package | ||
1209 | <filename>bar</filename>, then <filename>foo-dev</filename> | ||
1210 | and <filename>foo-dbg</filename> are also made to depend on | ||
1211 | <filename>bar-dev</filename> and | ||
1212 | <filename>bar-dbg</filename>, respectively. | ||
1213 | Taking the <filename>-dev</filename> packages as an | ||
1214 | example, the <filename>bar-dev</filename> package might | ||
1215 | provide headers and shared library symlinks needed by | ||
1216 | <filename>foo-dev</filename>, which shows the need | ||
1217 | for a dependency between the packages.</para> | ||
1218 | |||
1219 | <para>The dependencies added by | ||
1220 | <filename>depchains</filename> are in the form of | ||
1221 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>. | ||
1222 | <note> | ||
1223 | By default, <filename>foo-dev</filename> also has an | ||
1224 | <filename>RDEPENDS</filename>-style dependency on | ||
1225 | <filename>foo</filename>, because the default value of | ||
1226 | <filename>RDEPENDS_${PN}-dev</filename> (set in | ||
1227 | <filename>bitbake.conf</filename>) includes | ||
1228 | "${PN}". | ||
1229 | </note></para> | ||
1230 | |||
1231 | <para>To ensure that the dependency chain is never broken, | ||
1232 | <filename>-dev</filename> and <filename>-dbg</filename> | ||
1233 | packages are always generated by default, even if the | ||
1234 | packages turn out to be empty. | ||
1235 | See the | ||
1236 | <ulink url='&YOCTO_DOCS_REF_URL;#var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></ulink> | ||
1237 | variable for more information. | ||
1238 | </para></listitem> | ||
1239 | </itemizedlist> | ||
1240 | </para> | ||
1241 | |||
1242 | <para> | ||
1243 | The <filename>do_package</filename> task depends on the | ||
1244 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink> | ||
1245 | task of each recipe in | ||
1246 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> | ||
1247 | through use of a | ||
1248 | <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename> | ||
1249 | declaration, which guarantees that the required | ||
1250 | shared-library/module-to-package mapping information will be available | ||
1251 | when needed as long as <filename>DEPENDS</filename> has been | ||
1252 | correctly set. | ||
1253 | </para> | ||
1254 | </section> | ||
1255 | |||
1109 | <section id='x32'> | 1256 | <section id='x32'> |
1110 | <title>x32 psABI</title> | 1257 | <title>x32 psABI</title> |
1111 | 1258 | ||