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>

4 files changed, 81 insertions, 6 deletions

diff --git a/documentation/adt-manual/adt-package.xml b/documentation/adt-manual/adt-package.xml
index f7b236f8d5..c035c2d011 100644
--- a/documentation/adt-manual/adt-package.xml
+++ b/documentation/adt-manual/adt-package.xml
@@ -52,6 +52,13 @@
         See the configuration file for details.
     </para>
 
+    <note>
+        For build performance information related to the PMS, see
+        <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-classes-package'>Packaging - <filename>package*.bbclass</filename></ulink> 
+        in <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html'>
+        The Yocto Project Reference Manual</ulink>.
+    </note>
+
     <para>
         As an example, consider a scenario where you are using OPKG and you want to add 
         the <filename>libglade</filename> package to the target sysroot.
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>
 
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index 62280b619f..c95e1a02ab 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -330,7 +330,8 @@
              <filename>conf/local.conf</filename> file.</para></listitem>
          </itemizedlist>
          <para>
-             Take some time to examine your <filename>conf/local.conf</filename> file.  
+             Take some time to examine your <filename>conf/local.conf</filename> file found in the
+             Yocto Project file's <filename>conf</filename>.  
              The defaults should work fine.  
              However, if you have a multi-core CPU you might want to set the variable
              BB_NUMBER_THREADS equal to twice the number of processor cores your system has.
@@ -338,6 +339,19 @@
              Setting these variables can significantly shorten your build time.
              By default, these variables are commented out.
          </para>
+
+        <para>
+            Another consideration before you build is the package manager used when creating 
+            the image. 
+            By default, the Yocto Project build system uses the RPM package manager.
+            You can control this configuration by using the 
+            <filename><ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#var-PACKAGE_CLASSES'>PACKAGE_CLASSES</ulink></filename> variable.  
+             For additional package manager selection information, see 
+             <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-classes-package'>Packaging - <filename>package*.bbclass</filename></ulink> in 
+             <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html'>
+             The Yocto Project Reference Manual</ulink>.
+        </para>
+
          <para>
              Continue with the following command to build an OS image for the target, which is 
              <filename>core-image-sato</filename> in this example.