From 9f36b1fe16a5d4548d285b6292d09b3c4b685423 Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <scott.m.rifenbark@intel.com>
Date: Tue, 27 Sep 2011 10:19:06 -0700
Subject: [PATCH] documentation/poky-ref-manual/ref-variables.xml: update
 RDEPENDS and RRECOMMENDS

Provided better descriptions of these variables and some examples on
how to use them.

(From yocto-docs rev: 3a5cce8c9ba02f90b3554a6f800f69c2e8e77911)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 .../poky-ref-manual/ref-variables.xml         | 68 +++++++++++++++----
 1 file changed, 56 insertions(+), 12 deletions(-)

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 5d4e5b1ab3..9089ccb65c 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -902,16 +902,28 @@
         <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
             <glossdef>
                 <para>
-                    A list of run-time dependencies for a package. 
-                    These packages need to be installed alongside the package to which
-                    they apply. 
-                    This enables the package to run correctly. 
-                    For example, consider a Perl script, which depends on the Perl package. 
-                    Since this variable applies to 
-                    output packages, there should always be an override attached 
-                    to this variable specifying the runtime package to which to add the 
-                    dependency (e.g. <filename>RDEPENDS_${PN}-dev</filename>). 
-                    Names in this field must appear as they appear in the
+                    A list of packages that must be installed alongside a package being 
+                    built because the package being build has runtime dependencies on 
+                    them.
+                    In other words, in order for the package being built to run correctly, 
+                    it depends on these listed packages.
+                    If a package in this list cannot be found during the build, the build
+                    will not complete.
+                </para>
+                <para>
+                    Because the <filename>RDEPENDS</filename> variable applies to packages 
+                    being built, you should 
+                    always attach an override to the variable to specify the particular runtime package
+                    that has the dependency.
+                    For example, suppose you are building a development package that depends
+                    on the <filename>perl</filename> package.
+                    In this case, you would use the following <filename>RDEPENDS</filename>
+                    statement:
+                    <literallayout class='monospaced'>
+     RDEPENDS_${PN}-dev += "perl"
+                    </literallayout>
+                    In the example, the package name (<filename>${PN}-dev</filename>) must 
+                    appear as it would in the 
                     <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any 
                     renaming of the output package by classes like <filename>debian.bbclass</filename>.
                 </para>
@@ -943,8 +955,40 @@
 
         <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
             <glossdef>
-                <para>The list of packages that extend usability of the package. 
-                    The packages are automatically installed but can be removed by user.</para>
+                <para>
+                    A list of packages that extend the usability of a package being 
+                    built.
+                    The package being built does not depend on this list of packages in 
+                    order to successfully built, but needs them for the extended usability.
+                    To specify runtime dependencies for packages, see the 
+                    <link linkend='var-RDEPENDS'>RDEPENDS</link> variable.
+                </para>
+                <para>
+                    The Yocto Project build process automatically installs the list of packages
+                    as part of the build package.
+                    However, you can remove them later if you want.
+                    If, during the build, a package from the list cannot be found, the build
+                    process continues without an error.
+                </para>
+                <para>
+                    Because the <filename>RRECOMMENDS</filename> variable applies to packages 
+                    being built, you should 
+                    always attach an override to the variable to specify the particular package
+                    whose usability is being extended.
+                    For example, suppose you are building a development package that is extended
+                    to support wireless functionality.
+                    In this case, you would use the following <filename>RRECOMMENDS</filename>
+                    statement:
+                    <literallayout class='monospaced'>
+     RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
+                    </literallayout>
+                    In the example, the package name (<filename>${PN}-dev</filename>) must 
+                    appear as it would in the 
+                    <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any 
+                    renaming of the output package by classes like <filename>debian.bbclass</filename>.
+                    Also, you would provide the actual name of the package that supports the wireless
+                    capabilities.
+                </para>
             </glossdef>
         </glossentry>