[gnome-continuous-yocto/gnomeostree-3.28-rocko: 5304/8267] ref-manual: Added information about pre-installed dependencies

[Emmanuele Bassi <ebassi src gnome org>]

commit 478c7c304351838c16ddd322aaded236ae2c0259
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Sat Mar 18 12:32:33 2017 -0700

    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>

 documentation/ref-manual/ref-devtool-reference.xml |   45 ++++++++++++++++++++
 1 files changed, 45 insertions(+), 0 deletions(-)
---
diff --git a/documentation/ref-manual/ref-devtool-reference.xml 
b/documentation/ref-manual/ref-devtool-reference.xml
index 1764f01..90330f1 100644
--- 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'>