summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-11 11:02:11 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:28 +0000
commita60d9e29171eaf73dc5ce70fdd2ce92ec07876ec (patch)
treea0e6b77735696cf59cc23614fe885992b10d252a /documentation
parent00f87f84165964f262f8bb97378cfbef4b0c325a (diff)
downloadpoky-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')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml8
-rw-r--r--documentation/overview-manual/overview-concepts.xml147
-rw-r--r--documentation/ref-manual/ref-tasks.xml4
-rw-r--r--documentation/ref-manual/ref-variables.xml19
-rw-r--r--documentation/ref-manual/technical-details.xml144
5 files changed, 163 insertions, 159 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 8a0d6a3222..b141498763 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2275,8 +2275,8 @@
2275 automatically add a runtime dependency to "mypackage" on 2275 automatically add a runtime dependency to "mypackage" on
2276 "example"). 2276 "example").
2277 See the 2277 See the
2278 "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>" 2278 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
2279 in the Yocto Project Reference Manual for further details. 2279 in the Yocto Project Overview Manual for further details.
2280 </para> 2280 </para>
2281 </section> 2281 </section>
2282 2282
@@ -3417,8 +3417,8 @@
3417 allows runtime dependencies between packages 3417 allows runtime dependencies between packages
3418 to be added automatically. 3418 to be added automatically.
3419 See the 3419 See the
3420 "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>" 3420 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
3421 section in the Yocto Project Reference Manual 3421 section in the Yocto Project Overview Manual
3422 for more information. 3422 for more information.
3423 </para></listitem> 3423 </para></listitem>
3424 </itemizedlist> 3424 </itemizedlist>
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
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
index a90f02b7d8..0909595834 100644
--- a/documentation/ref-manual/ref-tasks.xml
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -342,8 +342,8 @@
342 For additional information, see the 342 For additional information, see the
343 <link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link> 343 <link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link>
344 variable and the 344 variable and the
345 "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" 345 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
346 section. 346 section in the Yocto Project Overview Manual.
347 </para> 347 </para>
348 </section> 348 </section>
349 349
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 564bb38ac6..67cf8859ee 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -3263,8 +3263,9 @@
3263 add any runtime dependencies between the 3263 add any runtime dependencies between the
3264 packages produced by the two recipes. 3264 packages produced by the two recipes.
3265 However, as explained in the 3265 However, as explained in the
3266 "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" 3266 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
3267 section, runtime dependencies will often be 3267 section in the Yocto Project Overview Manual,
3268 runtime dependencies will often be
3268 added automatically, meaning 3269 added automatically, meaning
3269 <filename>DEPENDS</filename> alone is 3270 <filename>DEPENDS</filename> alone is
3270 sufficient for most recipes. 3271 sufficient for most recipes.
@@ -10407,10 +10408,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
10407 ${STAGING_DIR_HOST}/pkgdata 10408 ${STAGING_DIR_HOST}/pkgdata
10408 </literallayout> 10409 </literallayout>
10409 For examples of how this data is used, see the 10410 For examples of how this data is used, see the
10410 "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" 10411 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
10411 section and the 10412 section in the Yocto Project Overview Manual and the
10412 "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>" 10413 "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"
10413 section. 10414 section elsewhere in this manual.
10414 </para> 10415 </para>
10415 </glossdef> 10416 </glossdef>
10416 </glossentry> 10417 </glossentry>
@@ -10914,8 +10915,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
10914 10915
10915 <para> 10916 <para>
10916 For more information, see the 10917 For more information, see the
10917 "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" 10918 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
10918 section. 10919 section in the Yocto Project Overview Manual.
10919 </para> 10920 </para>
10920 </glossdef> 10921 </glossdef>
10921 </glossentry> 10922 </glossentry>
@@ -11231,8 +11232,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
11231 Therefore, most recipes do not need to set 11232 Therefore, most recipes do not need to set
11232 <filename>RDEPENDS</filename>. 11233 <filename>RDEPENDS</filename>.
11233 For more information, see the 11234 For more information, see the
11234 "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" 11235 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11235 section. 11236 section in the Yocto Project Overview Manual.
11236 </para> 11237 </para>
11237 11238
11238 <para> 11239 <para>
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 06a018b8a9..b30dfe8597 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -13,150 +13,6 @@
13 x32, Wayland support, and Licenses. 13 x32, Wayland support, and Licenses.
14 </para> 14 </para>
15 15
16<section id='automatically-added-runtime-dependencies'>
17 <title>Automatically Added Runtime Dependencies</title>
18
19 <para>
20 The OpenEmbedded build system automatically adds common types of
21 runtime dependencies between packages, which means that you do not
22 need to explicitly declare the packages using
23 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
24 Three automatic mechanisms exist (<filename>shlibdeps</filename>,
25 <filename>pcdeps</filename>, and <filename>depchains</filename>) that
26 handle shared libraries, package configuration (pkg-config) modules,
27 and <filename>-dev</filename> and <filename>-dbg</filename> packages,
28 respectively.
29 For other types of runtime dependencies, you must manually declare
30 the dependencies.
31 <itemizedlist>
32 <listitem><para>
33 <filename>shlibdeps</filename>:
34 During the
35 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
36 task of each recipe, all shared libraries installed by the
37 recipe are located.
38 For each shared library, the package that contains the shared
39 library is registered as providing the shared library.
40 More specifically, the package is registered as providing the
41 <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink>
42 of the library.
43 The resulting shared-library-to-package mapping
44 is saved globally in
45 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
46 by the
47 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
48 task.</para>
49
50 <para>Simultaneously, all executables and shared libraries
51 installed by the recipe are inspected to see what shared
52 libraries they link against.
53 For each shared library dependency that is found,
54 <filename>PKGDATA_DIR</filename> is queried to
55 see if some package (likely from a different recipe) contains
56 the shared library.
57 If such a package is found, a runtime dependency is added from
58 the package that depends on the shared library to the package
59 that contains the library.</para>
60
61 <para>The automatically added runtime dependency also includes
62 a version restriction.
63 This version restriction specifies that at least the current
64 version of the package that provides the shared library must be
65 used, as if
66 "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)"
67 had been added to
68 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
69 This forces an upgrade of the package containing the shared
70 library when installing the package that depends on the
71 library, if needed.</para>
72
73 <para>If you want to avoid a package being registered as
74 providing a particular shared library (e.g. because the library
75 is for internal use only), then add the library to
76 <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
77 inside the package's recipe.
78 </para></listitem>
79 <listitem><para>
80 <filename>pcdeps</filename>:
81 During the
82 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
83 task of each recipe, all pkg-config modules
84 (<filename>*.pc</filename> files) installed by the recipe are
85 located.
86 For each module, the package that contains the module is
87 registered as providing the module.
88 The resulting module-to-package mapping is saved globally in
89 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
90 by the
91 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
92 task.</para>
93
94 <para>Simultaneously, all pkg-config modules installed by the
95 recipe are inspected to see what other pkg-config modules they
96 depend on.
97 A module is seen as depending on another module if it contains
98 a "Requires:" line that specifies the other module.
99 For each module dependency,
100 <filename>PKGDATA_DIR</filename> is queried to see if some
101 package contains the module.
102 If such a package is found, a runtime dependency is added from
103 the package that depends on the module to the package that
104 contains the module.
105 <note>
106 The <filename>pcdeps</filename> mechanism most often infers
107 dependencies between <filename>-dev</filename> packages.
108 </note>
109 </para></listitem>
110 <listitem><para>
111 <filename>depchains</filename>:
112 If a package <filename>foo</filename> depends on a package
113 <filename>bar</filename>, then <filename>foo-dev</filename>
114 and <filename>foo-dbg</filename> are also made to depend on
115 <filename>bar-dev</filename> and <filename>bar-dbg</filename>,
116 respectively.
117 Taking the <filename>-dev</filename> packages as an example,
118 the <filename>bar-dev</filename> package might provide
119 headers and shared library symlinks needed by
120 <filename>foo-dev</filename>, which shows the need
121 for a dependency between the packages.</para>
122
123 <para>The dependencies added by <filename>depchains</filename>
124 are in the form of
125 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>.
126 <note>
127 By default, <filename>foo-dev</filename> also has an
128 <filename>RDEPENDS</filename>-style dependency on
129 <filename>foo</filename>, because the default value of
130 <filename>RDEPENDS_${PN}-dev</filename> (set in
131 <filename>bitbake.conf</filename>) includes
132 "${PN}".
133 </note></para>
134
135 <para>To ensure that the dependency chain is never broken,
136 <filename>-dev</filename> and <filename>-dbg</filename>
137 packages are always generated by default, even if the packages
138 turn out to be empty.
139 See the
140 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>
141 variable for more information.
142 </para></listitem>
143 </itemizedlist>
144 </para>
145
146 <para>
147 The <filename>do_package</filename> task depends on the
148 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
149 task of each recipe in
150 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
151 through use of a
152 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
153 declaration, which guarantees that the required
154 shared-library/module-to-package mapping information will be available
155 when needed as long as <filename>DEPENDS</filename> has been
156 correctly set.
157 </para>
158</section>
159
160<section id='fakeroot-and-pseudo'> 16<section id='fakeroot-and-pseudo'>
161 <title>Fakeroot and Pseudo</title> 17 <title>Fakeroot and Pseudo</title>
162 18