[PATCH] ref-manual/devtool-reference: add warning note on deploy-target and shared objects

[Antonin Godard <antonin.godard@bootlin.com>]

The command `devtool deploy-target` does not handle any dependency of
the application, even when properly listed in DEPENDS or RDEPENDS. While
the current documentation was clear on that, it felt needed to add a
note on the fact that build-time dependencies may also result in
runtime dependencies, especially for people new to the project.

Add a warning block below the existing deploy-target documentation.
Also, link to the Overview and Concepts page, which explains it
thoroughly.

[ YOCTO #14377 ]

Reported-By: Robert Berger <pokylinux@reliableembeddedsystems.com>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/devtool-reference.rst | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index d74d5c29aedb9541a5b0dc337a4780c2a59c04be..a6ea00c2103109397ef08ba896f2bf51577c1563 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -553,6 +553,26 @@ 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.
 
+.. warning::
+
+   Runtime dependencies can be explicitly listed in the :term:`RDEPENDS`
+   variable, but may also be the result of a :term:`DEPENDS` assignment in your
+   application's recipe. This is usually the case when your application depends
+   on libraries for compilation: these libraries are listed as build-time
+   dependencies in the :term:`DEPENDS` variable in your application's recipe.
+   However these may also be runtime dependencies if they install shared objects
+   on which your application will dynamically link to at runtime (e.g. shared
+   libraries ending with ``.so``).
+
+   These runtime dependencies are automatically resolved by the
+   :term:`OpenEmbedded Build System` during the packaging phase. Since
+   ``devtool`` ignores packaging dependencies, they will not be installed
+   automatically with ``devtool deploy-target``.
+
+   For more information on how the :term:`OpenEmbedded Build System` handles
+   packaging, see the :ref:`overview-manual/concepts:Automatically Added Runtime
+   Dependencies` section of the Yocto Project Overview and Concepts Manual.
+
 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.

---
base-commit: 4b904539d05fdac123ed96c3952613fbbe612c39
change-id: 20241223-devtool-deploy-target-27d9f6e8a250

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>