ref-manual: Added new "Checking for Missing Build-Time Dependencies" section.

I added a new suggest section to the existing "Debugging Build
Failures" section.  This section describes how to check for
build-time dependencies.

Fixes [YOCTO #9976]

(From yocto-docs rev: 54cd7161593ba35b63a26ade312cc4aee17e3515)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 71 insertions, 0 deletions

diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 40e39b5578..61d5fbf877 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -246,6 +246,77 @@
         </para>
     </section>
 
+    <section id='checking-for-missing-build-time-dependencies'>
+        <title>Checking for Missing Build-Time Dependencies</title>
+
+        <para>
+            A recipe might build successfully even though some of its
+            build-time dependencies are missing from
+            <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
+            Following are the two most common ways in which that can happen:
+            <itemizedlist>
+                <listitem><para>
+                    The build-time dependency just happens to already exist in
+                    the staging sysroot
+                    (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>)
+                    by the time the recipe is built.
+                    This situation occurs when the build-time dependency is
+                    built earlier during recipe processing.
+                    </para></listitem>
+                <listitem><para>
+                    The component built by the recipe conditionally enables
+                    functionality depending on whether it can find the
+                    build-time dependency in the staging sysroot.
+                    If the build-time dependency is missing, the corresponding
+                    functionality is disabled.
+                    This condition is known as a "floating dependency".
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Because, dealing with the second case is more complex, focus will
+            be on the first case.
+            The
+            <link linkend='ref-classes-insane'><filename>build-deps</filename></link>
+            QA check checks that every library the component linked against is
+            declared as a build-time dependency.
+            If that is not the case, then the first situation described in the
+            previous list exists, and <filename>build-deps</filename> reports
+            a missing build-time dependency.
+        </para>
+
+        <para>
+            Another, more manual, way to check a recipe for missing build-time
+            dependencies of the first type is to build with an empty staging
+            sysroot.
+            An easy way to do this build is to simply remove
+            <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
+            which is usually
+            <filename>${</filename><link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link><filename>}/tmp</filename>,
+            as it includes the staging sysroots.
+        </para>
+
+        <para>
+            Another, faster method to remove the staging sysroot is to use the
+            <filename>scripts/wipe-sysroot</filename> script, which removes
+            just the staging sysroots and keeps everything else in
+            <filename>TMPDIR</filename>.
+            <note>
+                The <filename>scripts/</filename> directory appears in
+                <filename>PATH</filename> after running the build environment
+                initialization script (i.e.
+                <link linkend='structure-core-script'><filename>oe-init-build-env</filename></link>
+                or
+                <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>),
+                which results in the ability to to run
+                <filename>wipe-sysroot</filename> immediately.
+            </note>
+        </para>
+
+    </section>
+
+
     <section id='usingpoky-debugging-dependencies'>
         <title>Dependency Graphs</title>