documentation/poky-ref-manual: Updates to IMAGE_INSTALL

Updated the glossary entry for the IMAGE_INSTALL variable.
It was not complete.  I also updated the section that describes
how to modify the image through the local.conf file.  These
edits are out on review with Richard and could undergo some
further tweaks.

Fixes [YOCTO #1897]

(From yocto-docs rev: 41124cdd9e69b9f17300a609cce2ae4c9ce57b54)

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

2 files changed, 85 insertions, 74 deletions

diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
index 8c1e343889..4fef075360 100644
--- a/documentation/poky-ref-manual/extendpoky.xml
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -472,37 +472,58 @@
             <title>Customizing Images Using <filename>local.conf</filename></title>
 
             <para>
-                While not recommended, it is possible to include or exclude packages in the 
-                image by setting variables in the <filename>conf/local.conf</filename> file in 
-                the Yocto Project build directory.
-                <note>
-                    The best way to add packages to an image is to create a layer that contains
-                    recipes to specifically add the packages.
-                    Using variables with the <filename>local.conf</filename> to add things 
-                    to images could result in ordering problems or even leave you with a 
-                    build system that seemingly adds "random" packages to the image.
-                    For example, if you use the same or a copied <filename>local.conf</filename>
-                    for another project, you might have forgotten about something you added
-                    for a previous project.
-                </note>  
-                This section describes some of the ways you could include or exclude packages 
-                in the image through use of the <filename>conf/local.conf</filename> file.
+                It is possible to customize image contents by using variables from your
+                local configuration in your <filename>conf/local.conf</filename> file. 
+                Because it is limited to local use, this method generally only allows you to 
+                add packages and is not as flexible as creating your own customized image.
+                When you add packages using local variables this way, you need to realize that 
+                these variable changes affect all images at the same time and might not be
+                what you require.
             </para>
 
             <section id='adding-packages'>
                 <title>Adding Packages</title>
 
                 <para>
-                    Following are some methods to add packages to the image through the 
-                    use of variables in the <filename>conf/local.conf</filename>:
-                    <itemizedlist>
-                        <listitem><para><emphasis><filename>IMAGE_INSTALL_append</filename> - </emphasis>
-                        Some explanation</para></listitem>
-                        <listitem><para><emphasis><filename>POKY_EXTRA_append</filename> - </emphasis>
-                        Some explanation</para></listitem>
-                        <listitem><para><emphasis><filename>POKY_EXTRA_INSTALL</filename> - </emphasis>
-                        Some explanation</para></listitem>
-                    </itemizedlist>
+                    The simplest way to add extra packages to all images is by using the 
+                    <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
+                    variable with the <filename>_append</filename> operator:
+                    <literallayout class='monospaced'>
+     IMAGE_INSTALL_append = " strace"
+                    </literallayout>
+                    Use of the syntax is important.
+                    Specifically, the space between the quote and the package name, which is
+                    <filename>strace</filename> in this example.
+                    This space is required since the <filename>_append</filename>
+                    operator does not add the space.
+                </para>
+
+                <para>
+                    Furthermore, you must use <filename>_append</filename> instead of the <filename>+=</filename> 
+                    operator if you want to avoid ordering issues. 
+                    The reason for this is because doing so uncondtionally appends to the variable and 
+                    avoids ordering problems due to the variable being set in image recipes and 
+                    <filename>.bbclass</filename> files with operators like <filename>?=</filename>.
+                    Using <filename>_append</filename> ensures the operation takes affect.
+                </para>
+
+                <para>
+                    As shown in its simplest use, <filename>IMAGE_INSTALL_append</filename> affects
+                    all images.
+                    It is possible to extend the syntax so that the variable applies to a specific image only.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
+                    </literallayout>
+                    This example adds <filename>strace</filename> to <filename>core-image-minimal</filename>
+                    only.
+                </para>
+
+                <para>
+                    You can add packages using a similar approach through the  
+                    <filename><link linkend='var-POKY_EXTRA_INSTALL'>POKY_EXTRA_INSTALL</link></filename> 
+                    variable.
+                    If you use this variable, only <filename>core-image-*</filename> images are affected.
                 </para>
             </section>
 
@@ -513,7 +534,7 @@
                     It is possible to filter or mask out recipe and recipe append files such that 
                     BitBake ignores them.  
                     You can do this by providing an expression with the 
-                    <filename>BBMASK</filename> variable. 
+                    <filename><link linkend='var-BBMASK'>BBMASK</link></filename> variable. 
                     Here is an example:
                     <literallayout class='monospaced'>
      BBMASK = ".*/meta-mymachine/recipes-maybe/"
@@ -523,53 +544,6 @@
                     process.
                 </para>
             </section>
-<!--
-THIS IS THE ORIGINAL STUFF
-
-        <section id='usingpoky-extend-customimage-localconf'>
-            <title>Customizing Images Using <filename>local.conf</filename></title>
-
-            <para>
-                It is possible to customize image contents by using variables used by distribution 
-                maintainers in the <filename>local.conf</filename> found in the Yocto Project 
-                build directory.
-                This method only allows the addition of packages and is not recommended.
-            </para>
-
-            <para>
-                For example, to add the <filename>strace</filename> package into the image,
-                you would add this package to the <filename>local.conf</filename> file:
-                <literallayout class='monospaced'>
-     DISTRO_EXTRA_RDEPENDS += "strace"
-                </literallayout>
-            </para>
-
-            <para>
-                However, since the 
-                <filename><link linkend='var-DISTRO_EXTRA_RDEPENDS'>DISTRO_EXTRA_RDEPENDS</link></filename> 
-                variable is for distribution maintainers, adding packages using this method is not 
-                as simple as adding them using a custom <filename>.bb</filename> file. 
-                Using the <filename>local.conf</filename> file method could result in some packages 
-                needing to be recreated.
-                For example, if packages were previously created and the image was rebuilt, then the packages
-                would need to be recreated.
-            </para>
-
-            <para>
-                Cleaning <filename>task-*</filename> packages are required because they use the
-                <filename>DISTRO_EXTRA_RDEPENDS</filename> variable. 
-                You do not have to build them by hand because Yocto Project images depend on the 
-                packages they contain.
-                This means dependencies are automatically built when the image builds. 
-                For this reason we do not use the <filename>rebuild</filename> task.
-                In this case the <filename>rebuild</filename> task does not care about
-                dependencies - it only rebuilds the specified package.
-                <literallayout class='monospaced'>
-     $ bitbake -c clean task-boot task-base task-poky
-     $ bitbake core-image-sato
-                </literallayout>
-            </para>
-        </section> -->
         </section>
     </section>
 
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 1a958773b9..8efd46a848 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -533,7 +533,44 @@
 
         <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
             <glossdef>
-                <para>The list of packages used to build images.</para>
+                <para>
+                    Specifies the packages to install into an image.
+                    The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image
+                    recipe and you should use it with care to avoid ordering issues.
+                </para>
+
+                <para>
+                    Image recipes set <filename>IMAGE_INSTALL</filename> to specify the 
+                    packages to install into an image through <filename>image.bbclass</filename>.
+                    Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
+                    that can take 
+                    <filename><link linkend='var-IMAGE_FEATURE'>IMAGE_FEATURE</link></filename> lists
+                    and turn these into auto-generated entries in 
+                    <filename>IMAGE_INSTALL</filename> in addition to its default contents.
+                </para>
+
+                <para>
+                    Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
+                    operator from the <filename>/conf/local.conf</filename> file or from within 
+                    an image recipe is not recommended as it can cause ordering issues. 
+                    Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename> 
+                    to a default value using the <filename>?=</filename> operator, using a  
+                    <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename> 
+                    previously from the <filename>/conf/local.conf</filename> will almost always fail.
+                    Furthermore, the same operation from with an image recipe may or may not 
+                    succeed depending on the specific situation.
+                    In both these cases, the behavior is contrary to how most users expect 
+                    the <filename>+=</filename> append operator to work. 
+                </para>
+
+                <para>
+                    When you use this variable, it is best to use it as follows:
+                    <literallayout class='monospaced'>
+     IMAGE_INSTALL_append " package-name"
+                    </literallayout>
+                    Be sure to include the space between the quotation character and the start of the
+                    package name.
+                </para>
             </glossdef>
         </glossentry>