documentation: poky-ref-manual - Variable descriptions edited.

Adjust the descriptions so that it is clearer that these are specific
to a machine and should appear in the machine's .conf file, and are
intended to affect the image contents, not the dependencies of a
specific package. Also change the examples so that they demonstrate more
realistic usage scenarios for these variables.

(From yocto-docs rev: 3c3b8b117b09d78637ae8c4d27f77194cf197ea9)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 63 insertions, 64 deletions

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index abeec67..bc3d286 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1362,8 +1362,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para></para>
                 <para>
-                    A list of required packages to install as part of the package being
-                    built.
+                    A list of required machine-specific packages to install as part of
+                    the image being built.
                     The build process depends on these packages being present.
                     Furthermore, because this is a "machine essential" variable, the list of 
                     packages are essential for the machine to boot.
@@ -1373,16 +1373,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     This variable is similar to the 
                     <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
-                    variable with the exception that the package being built has a build 
+                    variable with the exception that the image being built has a build 
                     dependency on the variable's list of packages.
                     In other words, the image will not build if a file in this list is not found.
                 </para>
                 <para>
-                    For example, suppose you are building a runtime package that depends
-                    on a certain disk driver.
-                    In this case, you would use the following:
+                    For example, suppose the machine for which you are building requires
+                    a specific program to be run during boot to initialise the hardware.
+                    In this case, assuming the package name for the program was
+                    <filename>example-init</filename>, you would use the following in the
+                    <filename>.conf</filename> file for the machine:
                     <literallayout class='monospaced'>
-     MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "&lt;disk_driver&gt;"
+     MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
                     </literallayout>
                 </para>
             </glossdef>
@@ -1392,8 +1394,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para></para>
                 <para>
-                    A list of recommended packages to install as part of the package being 
-                    built. 
+                    A list of recommended machine-specific packages to install as part of
+                    the image being built.
                     The build process does not depend on these packages being present.
                     Furthermore, because this is a "machine essential" variable, the list of 
                     packages are essential for the machine to boot.
@@ -1403,46 +1405,42 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     This variable is similar to the 
                     <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
-                    variable with the exception that the package being built does not have a build 
+                    variable with the exception that the image being built does not have a build 
                     dependency on the variable's list of packages.
-                    In other words, the image will build if a file in this list is not found.
-                    However, because this is one of the "essential" variables, the resulting image
-                    might not boot on the machine. 
-                    Or, if the machine does boot using the image, the machine might not be fully 
-                    functional.
-                </para>
-                <para>
-                    Consider an example where you have a custom kernel with a disk driver
-                    built into the kernel itself, rather than using the driver built as a module.
-                    If you include the package that has the driver module as part of 
-                    the variable's list, the 
-                    build process will not find that package.  
-                    However, because these packages are "recommends" packages, the build will 
-                    not fail due to the missing package.
-                    Not accounting for any other problems, the custom kernel would still boot the machine.
+                    In other words, the image will still build if a package in this list is not found.
+                    Typically, this variable is used to handle essential kernel modules, whose
+                    functionality may be selected to be built into the kernel rather than as a module,
+                    in which case a package will not be produced.
+                </para>
+                <para>
+                    Consider an example where you have a custom kernel where a specific touchscreen
+                    driver is required for the machine to be usable, but may be built as a module or
+                    into the kernel depending on the kernel configuration.
+                    If the driver is built as a module, you want it to be installed.
+                    However if
+                    the driver is built into the kernel you still want the build to succeed.
+                    This variable sets up a "recommends" relationship so that in the latter case,
+                    the build will not fail due to the missing package.
+                    To accomplish this, assuming the package for the module was called
+                    <filename>kernel-module-ab123</filename>, you would use the
+                    following in the <filename>.conf</filename> file for the machine:
+                    <literallayout class='monospaced'>
+     MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
+                    </literallayout>
                 </para>
                 <para>
-                    Some example packages of these machine essentials are flash, screen, keyboard, mouse, 
+                    Some examples of these machine essentials are flash, screen, keyboard, mouse, 
                     or touchscreen drivers (depending on the machine).
                 </para>
-                <para>
-                    For example, suppose you are building a runtime package that depends
-                    on a mouse driver.
-                    In this case, you would use the following:
-                    <literallayout class='monospaced'>
-     MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "&lt;mouse_driver&gt;"
-                    </literallayout>
-                </para>
             </glossdef>
         </glossentry>
 
          <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
             <glossdef>
                 <para>
-                    A list of optional but non-machine essential packages to install as 
-                    part of the package being built.
-                    Even though these packages are not essential for the machine to boot,  
-                    the build process depends on them being present.
+                    A list of machine-specific packages that are not essential for booting to install as 
+                    part of the image being built.
+                    The build process for more fully-featured images depends on them being present.
                     The impact of this variable affects all images based on
                     <filename>packagegroup-base</filename>, which does not include the 
                     <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> 
@@ -1451,22 +1449,23 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     This variable is similar to the 
                     <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
-                    variable with the exception that the package being built has a build 
+                    variable with the exception that the image being built has a build 
                     dependency on the variable's list of packages.
                     In other words, the image will not build if a file in this list is not found.
                 </para>
                 <para>
-                    An example is a machine that might or might not have a WiFi card.
-                    The package containing the WiFi support is not essential for the 
-                    machine to boot the image.
-                    If it is not there, the machine will boot but not be able to use the 
-                    WiFi functionality.
-                    However, if you include the package with the WiFi support as part of the 
-                    variable's package list, the build 
-                    process depends on finding the package.
-                    In this case, you would use the following:
+                    An example is a machine that has WiFi capability.
+                    WiFi being enabled is not essential for the machine to boot the image.
+                    However, if you are building a more fully-featured image, you want to enable
+                    the WiFi. 
+                    The package containing the firmware for the WiFi hardware is always 
+                    expected to exist, so it is acceptable for the build process to depend upon
+                    finding the package.
+                    In this case, assuming the package for the firmware was called
+                    <filename>wifidriver-firmware</filename>, you would use the following in the
+                    <filename>.conf</filename> file for the machine:
                     <literallayout class='monospaced'>
-     MACHINE_EXTRA_RDEPENDS += "&lt;wifi_driver&gt;"
+     MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
                     </literallayout>
                 </para>
             </glossdef>
@@ -1476,9 +1475,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para></para>
                 <para>
-                    A list of optional but non-machine essential packages to install as 
-                    part of the package being built.
-                    The package being built has no build dependency on the list of packages 
+                    A list of machine-specific packages that are not essential for booting
+                    to install as part of the image being built, if present.
+                    The image being built has no build dependency on the list of packages 
                     with this variable.  
                     The impact of this variable affects only images based on 
                     <filename>packagegroup-base</filename>, which does not include the 
@@ -1488,23 +1487,23 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     This variable is similar to the 
                     <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
-                    variable with the exception that the package being built does not have a build 
+                    variable with the exception that the image being built does not have a build 
                     dependency on the variable's list of packages.
                     In other words, the image will build if a file in this list is not found.
                 </para>
                 <para>
-                    An example is a machine that might or might not have a WiFi card.
-                    The package containing the WiFi support is not essential for the 
-                    machine to boot the image.
-                    If it is not there, the machine will boot but not be able to use the 
-                    WiFi functionality.
-                    You are free to either include or not include the 
-                    the package with the WiFi support as part of the 
-                    variable's package list, the build 
-                    process does not depend on finding the package.
-                    If you include the package, you would use the following:
+                    An example is a machine that has WiFi capability.
+                    WiFi being enabled is not essential for the machine to boot the image.
+                    However if you are building a more fully-featured image, you want to enable
+                    WiFi. 
+                    However, the package containing the WiFi kernel module will not be produced
+                    if the WiFi driver is built into the kernel, in which case you still want the
+                    build to succeed instead of failing because the package could not be found.
+                    To accomplish this, assuming the package for the module was called
+                    <filename>kernel-module-examplewifi</filename>, you would use the
+                    following in the <filename>.conf</filename> file for the machine:
                     <literallayout class='monospaced'>
-     MACHINE_EXTRA_RRECOMMENDS += "&lt;wifi_driver&gt;"
+     MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
                     </literallayout>
                 </para>
             </glossdef>