summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-09-13 11:15:02 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-09-23 15:27:34 +0100
commit8bc6c1c2c817fdc4ee12e165489aab6885fa9e9c (patch)
tree0a37ea47140367bd7c69ed8edab5823c6897fd0c
parent899ea9cb4839580c7f562e1601e58ac71a6dca4e (diff)
downloadpoky-8bc6c1c2c817fdc4ee12e165489aab6885fa9e9c.tar.gz
ref-manual: New section and updates for runtime dep work
fixes [YOCTO #10248] The bulk of this change is a new section called "Automatically Added Runtime Dependencies". Additionally, changes were made to the RDEPENDS and DEPENDS variables. Some cross-referencing to the new material was also added in the do_package task entry, the do_packagedata task entry, the PKGDATA_DIR glossary entry, and the PRIVATE_LIBS glossary entry. (From yocto-docs rev: 16504cd0eb23e102322c6c6096c5b52500a04640) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/ref-manual/ref-tasks.xml13
-rw-r--r--documentation/ref-manual/ref-variables.xml146
-rw-r--r--documentation/ref-manual/technical-details.xml107
3 files changed, 196 insertions, 70 deletions
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
index b0a65a989b..fa9fca1ce3 100644
--- a/documentation/ref-manual/ref-tasks.xml
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -334,6 +334,17 @@
334 <link linkend='var-FILES'><filename>FILES</filename></link> 334 <link linkend='var-FILES'><filename>FILES</filename></link>
335 variables. 335 variables.
336 </para> 336 </para>
337
338 <para>
339 The <filename>do_package</filename> task, in conjunction with the
340 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
341 task, also saves some important package metadata.
342 For additional information, see the
343 <link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link>
344 variable and the
345 "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
346 section.
347 </para>
337 </section> 348 </section>
338 349
339 <section id='ref-tasks-package_qa'> 350 <section id='ref-tasks-package_qa'>
@@ -408,6 +419,8 @@
408 <para> 419 <para>
409 Creates package metadata used by the build system to generate the 420 Creates package metadata used by the build system to generate the
410 final packages. 421 final packages.
422 The data is saved in
423 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
411 </para> 424 </para>
412 </section> 425 </section>
413 426
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index afc36a5b14..188cd74935 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -2833,9 +2833,9 @@
2833 add any runtime dependencies between the 2833 add any runtime dependencies between the
2834 packages produced by the two recipes. 2834 packages produced by the two recipes.
2835 However, as explained in the 2835 However, as explained in the
2836 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> 2836 "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
2837 glossary entry, runtime dependencies will often 2837 section, runtime dependencies will often be
2838 be added automatically, meaning 2838 added automatically, meaning
2839 <filename>DEPENDS</filename> alone is 2839 <filename>DEPENDS</filename> alone is
2840 sufficient for most recipes. 2840 sufficient for most recipes.
2841 </para></listitem> 2841 </para></listitem>
@@ -9651,14 +9651,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
9651 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> 9651 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
9652 task packages data for each recipe and installs it into 9652 task packages data for each recipe and installs it into
9653 this temporary, shared area. 9653 this temporary, shared area.
9654 This directory defaults to the following: 9654 This directory defaults to the following, which you should
9655 not change:
9655 <literallayout class='monospaced'> 9656 <literallayout class='monospaced'>
9656 ${STAGING_DIR_HOST}/pkgdata 9657 ${STAGING_DIR_HOST}/pkgdata
9657 </literallayout> 9658 </literallayout>
9658 </para> 9659 For examples of how this data is used, see the
9659 9660 "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
9660 <para> 9661 section and the
9661 Do not change this default. 9662 "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"
9663 section.
9662 </para> 9664 </para>
9663 </glossdef> 9665 </glossdef>
9664 </glossentry> 9666 </glossentry>
@@ -10133,6 +10135,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
10133 libplds4.so" 10135 libplds4.so"
10134 </literallayout> 10136 </literallayout>
10135 </para> 10137 </para>
10138
10139 <para>
10140 For more information, see the
10141 "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
10142 section.
10143 </para>
10136 </glossdef> 10144 </glossdef>
10137 </glossentry> 10145 </glossentry>
10138 10146
@@ -10427,40 +10435,60 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
10427 10435
10428 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> 10436 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
10429 <info> 10437 <info>
10430 RDEPENDS[doc] = "Lists a package's runtime dependencies (i.e. other packages) that must be installed for the package to be built. They must be the names of other packages as listed in the PACKAGES variable, not recipe names (PN)." 10438 RDEPENDS[doc] = "Lists runtime dependencies of a package."
10431 </info> 10439 </info>
10432 <glossdef> 10440 <glossdef>
10433 <para role="glossdeffirst"> 10441 <para role="glossdeffirst">
10434<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 10442<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10435 Lists a package's runtime dependencies (i.e. other packages) 10443 Lists runtime dependencies of a package.
10436 that must be installed in order for the built package to run 10444 These dependencies are other packages that must be
10437 correctly. 10445 installed in order for the package to function correctly.
10438 If a package in this list cannot be found during the build, 10446 As an example, the following assignment declares that the
10439 you will get a build error. 10447 package <filename>foo</filename> needs the packages
10448 <filename>bar</filename> and <filename>baz</filename> to
10449 be installed:
10450 <literallayout class='monospaced'>
10451 RDEPENDS_foo = "bar baz"
10452 </literallayout>
10453 The most common types of package runtime dependencies are
10454 automatically detected and added.
10455 Therefore, most recipes do not need to set
10456 <filename>RDEPENDS</filename>.
10457 For more information, see the
10458 "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
10459 section.
10460 </para>
10461
10462 <para>
10463 The practical effect of the above
10464 <filename>RDEPENDS</filename> assignment is that
10465 <filename>bar</filename> and <filename>baz</filename>
10466 will be declared as dependencies inside the package
10467 <filename>foo</filename> when it is written out by one of
10468 the
10469 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
10470 tasks.
10471 Exactly how this is done depends on the package format used
10472 as described in the
10473 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
10474 variable.
10475 When the corresponding package manager installs the
10476 package, it will know to also install the packages on
10477 which it depends.
10440 </para> 10478 </para>
10441 10479
10442 <para> 10480 <para>
10443 When you use the <filename>RDEPENDS</filename> variable 10481 To ensure that the packages <filename>bar</filename> and
10444 in a recipe, you are essentially stating that the recipe's 10482 <filename>baz</filename> get built, the previous
10483 <filename>RDEPENDS</filename> assignment also causes a task
10484 dependency to be added.
10485 This dependency is from the recipe's
10445 <link linkend='ref-tasks-build'><filename>do_build</filename></link> 10486 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
10446 task depends on the existence of a specific package. 10487 (not to be confused with the
10447 Consider this simple example for two recipes named "a" and 10488 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>)
10448 "b" that produce similarly named IPK packages. 10489 task to the to the <filename>do_package_write_*</filename>
10449 In this example, the <filename>RDEPENDS</filename> 10490 task of the recipes that build <filename>bar</filename> and
10450 statement appears in the "a" recipe: 10491 <filename>baz</filename>.
10451 <literallayout class='monospaced'>
10452 RDEPENDS_${PN} = "b"
10453 </literallayout>
10454 Here, the dependency is such that the
10455 <filename>do_build</filename> task for recipe "a" depends
10456 on the
10457 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
10458 task of recipe "b".
10459 This means the package file for "b" must be available when
10460 the output for recipe "a" has been completely built.
10461 More importantly, package "a" will be marked as depending
10462 on package "b" in a manner that is understood by the
10463 package manager.
10464 </para> 10492 </para>
10465 10493
10466 <para> 10494 <para>
@@ -10480,7 +10508,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
10480 <para> 10508 <para>
10481 Because the <filename>RDEPENDS</filename> variable applies 10509 Because the <filename>RDEPENDS</filename> variable applies
10482 to packages being built, you should always use the variable 10510 to packages being built, you should always use the variable
10483 in a form with an attached package name. 10511 in a form with an attached package name (remember that a
10512 single recipe can build multiple packages).
10484 For example, suppose you are building a development package 10513 For example, suppose you are building a development package
10485 that depends on the <filename>perl</filename> package. 10514 that depends on the <filename>perl</filename> package.
10486 In this case, you would use the following 10515 In this case, you would use the following
@@ -10508,41 +10537,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
10508 </para> 10537 </para>
10509 10538
10510 <para> 10539 <para>
10511 The package name you attach to the 10540 The package names you use with
10512 <filename>RDEPENDS</filename> variable must appear 10541 <filename>RDEPENDS</filename> must appear as they would in
10513 as it would in the <filename>PACKAGES</filename> 10542 the <filename>PACKAGES</filename> variable.
10514 namespace before any renaming of the output package by 10543 The
10515 classes like 10544 <link linkend='var-PKG'><filename>PKG</filename></link>
10516 <link linkend='ref-classes-debian'><filename>debian</filename></link>. 10545 variable allows a different name to be used for
10517 </para> 10546 the final package (e.g. the
10518 10547 <link linkend='ref-classes-debian'><filename>debian</filename></link>
10519 <para> 10548 class uses this to rename packages), but this final package
10520 In many cases you do not need to explicitly add 10549 name cannot be used with <filename>RDEPENDS</filename>,
10521 runtime dependencies using 10550 which makes sense as <filename>RDEPENDS</filename> is meant
10522 <filename>RDEPENDS</filename> since some automatic 10551 to be independent of the package format used.
10523 handling occurs:
10524 <itemizedlist>
10525 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>:
10526 If a runtime package contains a compiled binary,
10527 the build processes the binary in order to
10528 determine any shared libraries
10529 (<filename>.so</filename> files) to which it is
10530 dynamically linked.
10531 The build process adds the packages containing
10532 these libraries to <filename>RDEPENDS</filename>
10533 when creating the runtime package.
10534 In addition, if the shared library is versioned,
10535 the dependency will have the version appended to it
10536 in order to force an upgrade to the appropriate
10537 version if needed.
10538 </para></listitem>
10539 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
10540 the package ships a <filename>pkg-config</filename>
10541 information file, the build process uses this file
10542 to add items to the <filename>RDEPENDS</filename>
10543 variable to create the runtime packages.
10544 </para></listitem>
10545 </itemizedlist>
10546 </para> 10552 </para>
10547 10553
10548 <para> 10554 <para>
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 6bad547e50..e5c8eb83b6 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -979,6 +979,113 @@
979 </section> 979 </section>
980</section> 980</section>
981 981
982<section id='automatically-added-runtime-dependencies'>
983 <title>Automatically Added Runtime Dependencies</title>
984
985 <para>
986 The OpenEmbedded build system automatically adds common types of
987 runtime dependencies between packages, which means you do not need to
988 explicitly declare the packages using
989 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
990 Two automatic mechanisms exist (<filename>shlibdeps</filename> and
991 <filename>pcdeps</filename>) that handle shared libraries and
992 package configuration (pkg-config) modules, respectively.
993 For other types of runtime dependencies, you must manually declare
994 the dependencies.
995 <itemizedlist>
996 <listitem><para>
997 <filename>shlibdeps</filename>:
998 During the
999 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
1000 task of each recipe, all shared libraries installed by the
1001 recipe are located.
1002 For each shared library, the package that contains the shared
1003 library is registered as providing the shared library.
1004 More specifically, the package is registered as providing the
1005 <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink>
1006 of the library.
1007 The resulting shared-library-to-package mapping
1008 is saved globally in
1009 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
1010 by the
1011 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
1012 task.</para>
1013
1014 <para>Simultaneously, all executables and shared libraries
1015 installed by the recipe are inspected to see what shared
1016 libraries they link against.
1017 For each shared library dependency that is found,
1018 <filename>PKGDATA_DIR</filename> is queried to
1019 see if some package (likely from a different recipe) contains
1020 the shared library.
1021 If such a package is found, a runtime dependency is added from
1022 the package that depends on the shared library to the package
1023 that contains the library.</para>
1024
1025 <para>If the library being linked against is versioned
1026 (i.e. includes a version number), then the automatically added
1027 runtime dependency will specify at least that version, as if
1028 "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)"
1029 had been added to
1030 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
1031 This dependency forces an upgrade of the package that provides
1032 the shared library when installing the package that depends on
1033 the library, if needed.</para>
1034
1035 <para>If you want to avoid a package being registered as
1036 providing a particular shared library (e.g. because the library
1037 is for internal use only), then add the library to
1038 <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
1039 inside the package's recipe.
1040 </para></listitem>
1041 <listitem><para>
1042 <filename>pcdeps</filename>:
1043 During the
1044 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
1045 task of each recipe, all pkg-config modules
1046 (<filename>*.pc</filename> files) installed by the recipe are
1047 located.
1048 For each module, the package that contains the module is
1049 registered as providing the module.
1050 The resulting module-to-package mapping is saved globally in
1051 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
1052 by the
1053 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
1054 task.</para>
1055
1056 <para>Simultaneously, all pkg-config modules installed by the
1057 recipe are inspected to see what other modules on which the
1058 pkg-config modules depend.
1059 A module is seen as depending on another module if it contains
1060 a "Requires:" line that specifies the other module.
1061 For each module dependency,
1062 <filename>PKGDATA_DIR</filename> is queried to see if some
1063 package contains the module.
1064 If such a package is found, a runtime dependency is added from
1065 the package that depends on the module to the package that
1066 contains the module.
1067 <note>
1068 The <filename>pcdeps</filename> mechanism most often infers
1069 dependencies between <filename>-dev</filename> packages.
1070 </note>
1071 </para></listitem>
1072 </itemizedlist>
1073 </para>
1074
1075 <para>
1076 The <filename>do_package</filename> task depends on the
1077 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
1078 task of each recipe in
1079 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1080 through use of a
1081 <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>[vardeps]</filename></ulink>
1082 declaration, which guarantees that the required
1083 shared-library/module-to-package mapping information will be available
1084 when needed as long as <filename>DEPENDS</filename> has been
1085 correctly set.
1086 </para>
1087</section>
1088
982<section id='fakeroot-and-pseudo'> 1089<section id='fakeroot-and-pseudo'>
983 <title>Fakeroot and Pseudo</title> 1090 <title>Fakeroot and Pseudo</title>
984 1091