ref-manual; mega-manual: Edits to further define packaging process

In response to community input where developers were attempting to
locate information on how to write packages out to a directory
other than ${DEPLOY_DIR}/<package_type>, I updated the "Package
Feeds" section, added several new DEPLOY_DIR_* variables, updated
four classes, and updated four tasks.  Here are some details:

 * Made changes to the "Package Feeds" section to provide more
   accurate information in the package feeds directory structure
   used by the build system in build/tmp.  These changes included
   updating the figure itself and some explanatory text.

 * Updated the DEPLOY_DIR variable description.

 * Added new variable descriptions for DEPLOY_DIR_DEB, DEPLOY_DIR_IPK,
   DEPLOY_DIR_RPM, and DEPLOY_DIR_TAR.

 * Updated the related classes: package_deb, package_ipk, package_rpm,
   and package_tar.

 * Updated the related tasks: do_package_write_deb, do_package_write_ipk,
   do_package_write_rpm, and do_package_write_tar.

Reported-by: Trieu Nguyen <trieu.t.nguyen@intel.com>
(From yocto-docs rev: e8742267506bf9359346cfcd3965f762ed2c7d6f)

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

1 files changed, 41 insertions, 13 deletions

diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index eaf07d665f..27f674ae2f 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -640,7 +640,9 @@
 
         <para>
             Package feeds are an intermediary step in the build process.
-            BitBake generates packages whose types are defined by the
+            The OpenEmbedded build system provides classes to generate
+            different package types, and you specify which classes to enable
+            through the
             <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
             variable.
             Before placing the packages into package feeds,
@@ -651,22 +653,41 @@
         </para>
 
         <para>
-            The package feed area resides in
-            <filename>tmp/deploy</filename> of the Build Directory.
-            Folders are created that correspond to the package type
-            (IPK, DEB, or RPM) created.
-            Further organization is derived through the value of the
-            <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
-            variable for each package.
-            For example, packages can exist for the i586 or qemux86
-            architectures.
-            The package files themselves reside within the appropriate
-            architecture folder.
+            The package feed area resides in the Build Directory.
+            The directory the build system uses to temporarily store packages
+            is determined by a combination of variables and the particular
+            package manager in use.
+            See the "Package Feeds" box in the illustration and note the
+            information to the right of that area.
+            In particular, the following defines where package files are
+            kept:
+            <itemizedlist>
+                <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
+                    Defined as <filename>tmp/deploy</filename> in the Build
+                    Directory.
+                    </para></listitem>
+                <listitem><para><filename>DEPLOY_DIR_*</filename>:
+                    Depending on the package manager used, the package type
+                    sub-folder.
+                    Given RPM, IPK, or DEB packaging and tarball creation, the
+                    <link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link>,
+                    <link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link>,
+                    <link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link>,
+                    or
+                    <link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link>,
+                    variables are used, respectively.
+                    </para></listitem>
+                <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>:
+                    Defines architecture-specific sub-folders.
+                    For example, packages could exist for the i586 or qemux86
+                    architectures.
+                    </para></listitem>
+            </itemizedlist>
         </para>
 
         <para>
             BitBake uses the <filename>do_package_write_*</filename> tasks to
-            place generated packages into the package holding area (e.g.
+            generate packages and place them into the package holding area (e.g.
             <filename>do_package_write_ipk</filename> for IPK packages).
             See the
             "<link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>",
@@ -675,6 +696,13 @@
             and
             "<link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>"
             sections for additional information.
+            As an example, consider a scenario where an IPK packaging manager
+            is being used and package architecture support for both i586
+            and qemux86 exist.
+            Packages for the i586 architecture are placed in
+            <filename>build/tmp/deploy/ipk/i586</filename>, while packages for
+            the qemux86 architecture are placed in
+            <filename>build/tmp/deploy/ipk/qemux86</filename>.
         </para>
     </section>