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>

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 @@
         </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>