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>

documentation/dev-manual/dev-manual-common-tasks.xml

@@ -2275,8 +2275,8 @@
                 automatically add a runtime dependency to "mypackage" on
                 "example").
                 See the
-                "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+                "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
-                in the Yocto Project Reference Manual for further details.
+                in the Yocto Project Overview Manual for further details.
             </para>
         </section>
 
@@ -3417,8 +3417,8 @@
                                 allows runtime dependencies between packages
                                 to be added automatically.
                                 See the
-                                "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+                                "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
-                                section in the Yocto Project Reference Manual
+                                section in the Yocto Project Overview Manual
                                 for more information.
                                 </para></listitem>
                         </itemizedlist>

documentation/overview-manual/overview-concepts.xml

@@ -1106,6 +1106,153 @@
         </section>
     </section>
 
+    <section id='automatically-added-runtime-dependencies'>
+        <title>Automatically Added Runtime Dependencies</title>
+
+        <para>
+            The OpenEmbedded build system automatically adds common types of
+            runtime dependencies between packages, which means that you do not
+            need to explicitly declare the packages using
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>.
+            Three automatic mechanisms exist (<filename>shlibdeps</filename>,
+            <filename>pcdeps</filename>, and <filename>depchains</filename>)
+            that handle shared libraries, package configuration (pkg-config)
+            modules, and <filename>-dev</filename> and
+            <filename>-dbg</filename> packages, respectively.
+            For other types of runtime dependencies, you must manually declare
+            the dependencies.
+            <itemizedlist>
+                <listitem><para>
+                    <filename>shlibdeps</filename>:
+                    During the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+                    task of each recipe, all shared libraries installed by the
+                    recipe are located.
+                    For each shared library, the package that contains the
+                    shared library is registered as providing the shared
+                    library.
+                    More specifically, the package is registered as providing
+                    the
+                    <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink>
+                    of the library.
+                    The resulting shared-library-to-package mapping
+                    is saved globally in
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
+                    by the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
+                    task.</para>
+
+                    <para>Simultaneously, all executables and shared libraries
+                    installed by the recipe are inspected to see what shared
+                    libraries they link against.
+                    For each shared library dependency that is found,
+                    <filename>PKGDATA_DIR</filename> is queried to
+                    see if some package (likely from a different recipe)
+                    contains the shared library.
+                    If such a package is found, a runtime dependency is added
+                    from the package that depends on the shared library to the
+                    package that contains the library.</para>
+
+                    <para>The automatically added runtime dependency also
+                    includes a version restriction.
+                    This version restriction specifies that at least the
+                    current version of the package that provides the shared
+                    library must be used, as if
+                    "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)"
+                    had been added to
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>.
+                    This forces an upgrade of the package containing the shared
+                    library when installing the package that depends on the
+                    library, if needed.</para>
+
+                    <para>If you want to avoid a package being registered as
+                    providing a particular shared library (e.g. because the library
+                    is for internal use only), then add the library to
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></ulink>
+                    inside the package's recipe.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>pcdeps</filename>:
+                    During the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+                    task of each recipe, all pkg-config modules
+                    (<filename>*.pc</filename> files) installed by the recipe
+                    are located.
+                    For each module, the package that contains the module is
+                    registered as providing the module.
+                    The resulting module-to-package mapping is saved globally in
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
+                    by the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
+                    task.</para>
+
+                    <para>Simultaneously, all pkg-config modules installed by
+                    the recipe are inspected to see what other pkg-config
+                    modules they depend on.
+                    A module is seen as depending on another module if it
+                    contains a "Requires:" line that specifies the other module.
+                    For each module dependency,
+                    <filename>PKGDATA_DIR</filename> is queried to see if some
+                    package contains the module.
+                    If such a package is found, a runtime dependency is added
+                    from the package that depends on the module to the package
+                    that contains the module.
+                    <note>
+                        The <filename>pcdeps</filename> mechanism most often
+                        infers dependencies between <filename>-dev</filename>
+                        packages.
+                    </note>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>depchains</filename>:
+                    If a package <filename>foo</filename> depends on a package
+                    <filename>bar</filename>, then <filename>foo-dev</filename>
+                    and <filename>foo-dbg</filename> are also made to depend on
+                    <filename>bar-dev</filename> and
+                    <filename>bar-dbg</filename>, respectively.
+                    Taking the <filename>-dev</filename> packages as an
+                    example, the <filename>bar-dev</filename> package might
+                    provide headers and shared library symlinks needed by
+                    <filename>foo-dev</filename>, which shows the need
+                    for a dependency between the packages.</para>
+
+                    <para>The dependencies added by
+                    <filename>depchains</filename> are in the form of
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>.
+                    <note>
+                        By default, <filename>foo-dev</filename> also has an
+                        <filename>RDEPENDS</filename>-style dependency on
+                        <filename>foo</filename>, because the default value of
+                        <filename>RDEPENDS_${PN}-dev</filename> (set in
+                        <filename>bitbake.conf</filename>) includes
+                        "${PN}".
+                    </note></para>
+
+                    <para>To ensure that the dependency chain is never broken,
+                    <filename>-dev</filename> and <filename>-dbg</filename>
+                    packages are always generated by default, even if the
+                    packages turn out to be empty.
+                    See the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></ulink>
+                    variable for more information.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            The <filename>do_package</filename> task depends on the
+            <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
+            task of each recipe in
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+            through use of a
+            <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
+            declaration, which guarantees that the required
+            shared-library/module-to-package mapping information will be available
+            when needed as long as <filename>DEPENDS</filename> has been
+            correctly set.
+        </para>
+    </section>
+
     <section id='x32'>
         <title>x32 psABI</title>
 

documentation/ref-manual/ref-tasks.xml

@@ -342,8 +342,8 @@
             For additional information, see the
             <link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link>
             variable and the
-            "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
+            "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
-            section.
+            section in the Yocto Project Overview Manual.
         </para>
     </section>
 

documentation/ref-manual/ref-variables.xml

@@ -3263,8 +3263,9 @@
                                 add any runtime dependencies between the
                                 packages produced by the two recipes.
                                 However, as explained in the
-                                "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
+                                "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
-                                section, runtime dependencies will often be
+                                section in the Yocto Project Overview Manual,
+                                runtime dependencies will often be
                                 added automatically, meaning
                                 <filename>DEPENDS</filename> alone is
                                 sufficient for most recipes.
@@ -10407,10 +10408,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
      ${STAGING_DIR_HOST}/pkgdata
                     </literallayout>
                     For examples of how this data is used, see the
-                    "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
+                    "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
-                    section and the
+                    section in the Yocto Project Overview Manual and the
                     "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"
-                    section.
+                    section elsewhere in this manual.
                 </para>
             </glossdef>
         </glossentry>
@@ -10914,8 +10915,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
 
                 <para>
                     For more information, see the
-                    "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
+                    "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
-                    section.
+                    section in the Yocto Project Overview Manual.
                 </para>
             </glossdef>
         </glossentry>
@@ -11231,8 +11232,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     Therefore, most recipes do not need to set
                     <filename>RDEPENDS</filename>.
                     For more information, see the
-                    "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
+                    "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
-                    section.
+                    section in the Yocto Project Overview Manual.
                 </para>
 
                 <para>

documentation/ref-manual/technical-details.xml

@@ -13,150 +13,6 @@
         x32, Wayland support, and Licenses.
     </para>
 
-<section id='automatically-added-runtime-dependencies'>
-    <title>Automatically Added Runtime Dependencies</title>
-
-    <para>
-        The OpenEmbedded build system automatically adds common types of
-        runtime dependencies between packages, which means that you do not
-        need to explicitly declare the packages using
-        <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
-        Three automatic mechanisms exist (<filename>shlibdeps</filename>,
-        <filename>pcdeps</filename>, and <filename>depchains</filename>) that
-        handle shared libraries, package configuration (pkg-config) modules,
-        and <filename>-dev</filename> and <filename>-dbg</filename> packages,
-        respectively.
-        For other types of runtime dependencies, you must manually declare
-        the dependencies.
-        <itemizedlist>
-            <listitem><para>
-                <filename>shlibdeps</filename>:
-                During the
-                <link linkend='ref-tasks-package'><filename>do_package</filename></link>
-                task of each recipe, all shared libraries installed by the
-                recipe are located.
-                For each shared library, the package that contains the shared
-                library is registered as providing the shared library.
-                More specifically, the package is registered as providing the
-                <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink>
-                of the library.
-                The resulting shared-library-to-package mapping
-                is saved globally in
-                <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
-                by the
-                <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
-                task.</para>
-
-                <para>Simultaneously, all executables and shared libraries
-                installed by the recipe are inspected to see what shared
-                libraries they link against.
-                For each shared library dependency that is found,
-                <filename>PKGDATA_DIR</filename> is queried to
-                see if some package (likely from a different recipe) contains
-                the shared library.
-                If such a package is found, a runtime dependency is added from
-                the package that depends on the shared library to the package
-                that contains the library.</para>
-
-                <para>The automatically added runtime dependency also includes
-                a version restriction.
-                This version restriction specifies that at least the current
-                version of the package that provides the shared library must be
-                used, as if
-                "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)"
-                had been added to
-                <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
-                This forces an upgrade of the package containing the shared
-                library when installing the package that depends on the
-                library, if needed.</para>
-
-                <para>If you want to avoid a package being registered as
-                providing a particular shared library (e.g. because the library
-                is for internal use only), then add the library to
-                <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
-                inside the package's recipe.
-                </para></listitem>
-            <listitem><para>
-                <filename>pcdeps</filename>:
-                During the
-                <link linkend='ref-tasks-package'><filename>do_package</filename></link>
-                task of each recipe, all pkg-config modules
-                (<filename>*.pc</filename> files) installed by the recipe are
-                located.
-                For each module, the package that contains the module is
-                registered as providing the module.
-                The resulting module-to-package mapping is saved globally in
-                <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
-                by the
-                <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
-                task.</para>
-
-                <para>Simultaneously, all pkg-config modules installed by the
-                recipe are inspected to see what other pkg-config modules they
-                depend on.
-                A module is seen as depending on another module if it contains
-                a "Requires:" line that specifies the other module.
-                For each module dependency,
-                <filename>PKGDATA_DIR</filename> is queried to see if some
-                package contains the module.
-                If such a package is found, a runtime dependency is added from
-                the package that depends on the module to the package that
-                contains the module.
-                <note>
-                    The <filename>pcdeps</filename> mechanism most often infers
-                    dependencies between <filename>-dev</filename> packages.
-                </note>
-                </para></listitem>
-            <listitem><para>
-                <filename>depchains</filename>:
-                If a package <filename>foo</filename> depends on a package
-                <filename>bar</filename>, then <filename>foo-dev</filename>
-                and <filename>foo-dbg</filename> are also made to depend on
-                <filename>bar-dev</filename> and <filename>bar-dbg</filename>,
-                respectively.
-                Taking the <filename>-dev</filename> packages as an example,
-                the <filename>bar-dev</filename> package might provide
-                headers and shared library symlinks needed by
-                <filename>foo-dev</filename>, which shows the need
-                for a dependency between the packages.</para>
-
-                <para>The dependencies added by <filename>depchains</filename>
-                are in the form of
-                <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>.
-                <note>
-                    By default, <filename>foo-dev</filename> also has an
-                    <filename>RDEPENDS</filename>-style dependency on
-                    <filename>foo</filename>, because the default value of
-                    <filename>RDEPENDS_${PN}-dev</filename> (set in
-                    <filename>bitbake.conf</filename>) includes
-                    "${PN}".
-                </note></para>
-
-                <para>To ensure that the dependency chain is never broken,
-                <filename>-dev</filename> and <filename>-dbg</filename>
-                packages are always generated by default, even if the packages
-                turn out to be empty.
-                See the
-                <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>
-                variable for more information.
-                </para></listitem>
-        </itemizedlist>
-    </para>
-
-    <para>
-        The <filename>do_package</filename> task depends on the
-        <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
-        task of each recipe in
-        <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
-        through use of a
-        <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
-        declaration, which guarantees that the required
-        shared-library/module-to-package mapping information will be available
-        when needed as long as <filename>DEPENDS</filename> has been
-        correctly set.
-    </para>
-</section>
-
 <section id='fakeroot-and-pseudo'>
     <title>Fakeroot and Pseudo</title>