ref-manual: Added information about pre-installed dependencies

Fixes [YOCTO #10350]

A situation exists where a user deploys a new application using
devtool target-deploy and the new application has runtime dependencies
that are not already on the target.  When this situation exists, the
application misbehaves if it calls a missing function.  I added the
explanation of this situation to the section that describes the
devtool deploy-target command.  Also, put a pointer in the section
on devtool add for cross-reference purposes.

(From yocto-docs rev: 694151e397ff40871b3ec8700c39d32a15814535)

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

diff --git a/documentation/ref-manual/ref-devtool-reference.xml b/documentation/ref-manual/ref-devtool-reference.xml
index 1764f0196f6d30c9b3dc2f31d87a28366d220307..90330f1a35b5a3b438eb18b7d073556305a082e6 100644 (file)
--- a/documentation/ref-manual/ref-devtool-reference.xml
+++ b/documentation/ref-manual/ref-devtool-reference.xml
@@ -215,6 +215,17 @@
             The <filename>.bbappend</filename> file is created to point
             to the external source tree.
         </para>
+
+        <note>
+            If your recipe has runtime dependencies defined, you must be sure
+            that these packages exist on the target hardware before attempting
+            to run your application.
+            If dependent packages (e.g. libraries) do not exist on the target,
+            your application, when run, will fail to find those functions.
+            For more information, see the
+            "<link linkend='devtool-deploying-your-software-on-the-target-machine'>Deploying Your Software on the Target Machine</link>"
+            section.
+        </note>
     </section>
 
     <section id='devtool-extracting-the-source-for-an-existing-recipe'>
@@ -501,6 +512,40 @@
                 </para>
             </note>
         </para>
+
+        <para>
+            Some conditions exist that could prevent a deployed application
+            from behaving as expected.
+            When both of the following conditions exist, your application has
+            the potential to not behave correctly when run on the target:
+            <itemizedlist>
+                <listitem><para>
+                    You are deploying a new application to the target that
+                    has correctly defined runtime dependencies defined in
+                    recipe you used to build the application.
+                    </para></listitem>
+                <listitem><para>
+                    The target does not physically have the packages on which
+                    the application depends installed.
+                    </para></listitem>
+            </itemizedlist>
+            If both of these conditions exist, your application will not
+            behave as expected.
+            The reason for this misbehavior is because the
+            <filename>devtool deploy-target</filename> command does not deploy
+            the packages (e.g. libraries) on which your new application
+            depends.
+            The assumption is that the packages are already on the target.
+            Consequently, when a runtime call is made in the application
+            for a dependent function (e.g. a library call), the function
+            cannot be found.
+        </para>
+
+        <para>
+            To be sure you have all the dependencies local to the target, you
+            need to be sure that the packages are pre-deployed (installed)
+            on the target before attempting to run your application.
+        </para>
     </section>
 
     <section id='devtool-removing-your-software-from-the-target-machine'>