YOCTO #1088: documentation - Added text to partially address package bug

This bug was filed by Gary Thomas and was requesting more information
on the "hows" and "whys" of setting up your own package repositories.
At this point, I have added information to help the user understand
build performance issues when choosing between the RPM and IPKG packaging
systems.  Likely, there is more that needs to be added to fully address
this bug.

For now, I added explanations in the packaging class and glossary areas
of the YP reference manual, a new paragraph in the YP QS just prior to
firing off a build, and a new bit of information in the configuring
PMS in the ADT Manual.

(From yocto-docs rev: d0025f862cb85ca741787b4737dca286e3ebfb45)

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

2 files changed, 59 insertions, 5 deletions

diff --git a/documentation/poky-ref-manual/ref-classes.xml b/documentation/poky-ref-manual/ref-classes.xml
index cf396800df..93e9ea8d43 100644
--- a/documentation/poky-ref-manual/ref-classes.xml
+++ b/documentation/poky-ref-manual/ref-classes.xml
@@ -265,17 +265,59 @@
         The packaging classes add support for generating packages from a build's
         output. 
         The core generic functionality is in <filename>package.bbclass</filename>.
-        The code specific 
-        to particular package types is contained in various sub-classes such as
+        The code specific to particular package types is contained in various sub-classes such as
         <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>,
         and <filename>package_rpm.bbclass</filename>. 
         Most users will want one or more of these classes.
+    </para>
+ 
+    <para>
         You can control the list of resulting package formats by using the 
         <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename> 
-        variable. 
-        The first class listed in this  variable is be used for image generation. 
+        variable defined in the <filename>local.conf</filename> configuration file 
+        found in the Yocto Project file's <filename>conf</filename> directory. 
+        When defining the variable, you can specify one or more package types.
         Since images are generated from packages, a packaging class is 
         needed to enable image generation.
+        The first class listed in this variable is used for image generation. 
+    </para>
+
+    <para>
+        The package class you choose can affect build-time performance and has space
+        ramifications.
+        In general, building a package with RPM takes about thirty percent more time as 
+        compared to using IPK to build the same or similar package.
+        This comparison takes into account a complete build of the package with all 
+        dependencies previously built.
+        The reason for this discrepancy is because the RPM package manager creates and 
+        processes more metadata than the IPK package manager.
+        Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename>
+        to "package_ipk" if you are building smaller systems.
+    </para>
+
+    <para>
+        Keep in mind, however, that RPM starts to provide more abilities than IPK due to 
+        the fact that it processes more metadata.
+        For example, this information includes individual file types, file checksum generation
+        and evaluation on install, sparse file support, conflict detection and resolution
+        for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks.
+    </para>
+
+    <para>
+        Another consideration for packages built using the RPM package manager is space.
+        For smaller systems, the extra space used for the Berkley Database and the amount 
+        of metadata can affect your ability to do on-device upgrades.
+    </para>
+
+    <para>
+        You can find additional information on the effects of the package class at these 
+        two Yocto Project mailing list links:
+        <itemizedlist>
+            <listitem><para><ulink url='https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html'>
+                https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
+            <listitem><para><ulink url='https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html'>
+                https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
+        </itemizedlist>
     </para>
 </section>
 
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 7f51fc9885..0bde65915c 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -679,7 +679,19 @@
 
         <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
             <glossdef>
-                <para>Specifies the list of resulting package formats.</para>
+                <para>This variable, which is set in the <filename>local.conf</filename> configuration
+                    file found in the Yocto Project file's <filename>conf</filename> directory,
+                    specifies the package manager to use when packaging data.
+                    You can provide one or more arguments for the variable with the first 
+                    argument being the package manager used to create images:
+                    <literallayout class='monospaced'>
+     PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
+                    </literallayout>
+                    For information on build performance effects as a result of the 
+                    package manager use, see
+                    <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link>
+                    in this manual.
+                </para>
             </glossdef>
         </glossentry>