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: a8d499850dec72f8decd81ec6714809c3a580ffc)

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

6 files changed, 252 insertions, 53 deletions

diff --git a/documentation/mega-manual/figures/package-feeds.png b/documentation/mega-manual/figures/package-feeds.png
index 4bc311f..37c9c32 100644
--- a/documentation/mega-manual/figures/package-feeds.png
+++ b/documentation/mega-manual/figures/package-feeds.png
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index eaf07d6..27f674a 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>
 
diff --git a/documentation/ref-manual/figures/package-feeds.png b/documentation/ref-manual/figures/package-feeds.png
index 4bc311f..37c9c32 100644
--- a/documentation/ref-manual/figures/package-feeds.png
+++ b/documentation/ref-manual/figures/package-feeds.png
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 880badd..4eb61c5 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -2263,11 +2263,12 @@
 
     <para>
         The <filename>package_deb</filename> class
-        provides support for creating packages that use the
-        <filename>.deb</filename> file format.
-        The class ensures the packages are written out to the
-        <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/deb</filename>
-        directory in a <filename>.deb</filename> file format.
+        provides support for creating packages that use the Debian
+        (i.e. <filename>.deb</filename>) file format.
+        The class ensures the packages are written out in a
+        <filename>.deb</filename> file format to the
+        <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename>
+        directory.
     </para>
 
     <para>
@@ -2284,11 +2285,12 @@
 
     <para>
         The <filename>package_ipk</filename> class
-        provides support for creating packages that use the
-        <filename>.ipk</filename> file format.
-        The class ensures the packages are written out to the
-        <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/ipk</filename>
-        directory in a <filename>.ipk</filename> file format.
+        provides support for creating packages that use the IPK
+        (i.e. <filename>.ipk</filename>) file format.
+        The class ensures the packages are written out in a
+        <filename>.ipk</filename> file format to the
+        <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename>
+        directory.
     </para>
 
     <para>
@@ -2305,11 +2307,12 @@
 
     <para>
         The <filename>package_rpm</filename> class
-        provides support for creating packages that use the
-        <filename>.rpm</filename> file format.
-        The class ensures the packages are written out to the
-        <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/rpm</filename>
-        directory in a <filename>.rpm</filename> file format.
+        provides support for creating packages that use the RPM
+        (i.e. <filename>.rpm</filename>) file format.
+        The class ensures the packages are written out in a
+        <filename>.rpm</filename> file format to the
+        <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename>
+        directory.
     </para>
 
     <para>
@@ -2324,19 +2327,13 @@
 <section id='ref-classes-package_tar'>
     <title><filename>package_tar.bbclass</filename></title>
 
-    <note><title>Warning</title>
-        The <filename>package_tar</filename> class is broken and is not
-        supported.
-        It is recommended that you do not use it.
-    </note>
-
     <para>
-        The <filename>package_tar</filename>
-        class provides support for creating packages that use the
-        <filename>.tar</filename> file format.
-        The class ensures the packages are written out to the
-        <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/tar</filename>
-        directory in a <filename>.tar</filename> file format.
+        The <filename>package_tar</filename> class
+        provides support for creating tarballs.
+        The class ensures the packages are written out in a
+        tarball format to the
+        <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename>
+        directory.
     </para>
 
     <para>
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
index 2b30315..59b4d96 100644
--- a/documentation/ref-manual/ref-tasks.xml
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -144,9 +144,13 @@
         <title><filename>do_package_write_deb</filename></title>
 
         <para>
-            Creates the actual DEB packages and places them in the
-            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
-            area.
+            Creates Debian packages (i.e. <filename>*.deb</filename> files) and
+            places them in the
+            <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename>
+            directory in the package feeds area.
+            For more information, see the
+            "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+            section.
         </para>
     </section>
 
@@ -154,9 +158,13 @@
         <title><filename>do_package_write_ipk</filename></title>
 
         <para>
-            Creates the actual IPK packages and places them in the
-            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
-            area.
+            Creates IPK packages (i.e. <filename>*.ipk</filename> files) and
+            places them in the
+            <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename>
+            directory in the package feeds area.
+            For more information, see the
+            "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+            section.
         </para>
     </section>
 
@@ -164,9 +172,13 @@
         <title><filename>do_package_write_rpm</filename></title>
 
         <para>
-            Creates the actual RPM packages and places them in the
-            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
-            area.
+            Creates RPM packages (i.e. <filename>*.rpm</filename> files) and
+            places them in the
+            <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename>
+            directory in the package feeds area.
+            For more information, see the
+            "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+            section.
         </para>
     </section>
 
@@ -174,9 +186,12 @@
         <title><filename>do_package_write_tar</filename></title>
 
         <para>
-            Creates tar archives for packages and places them in the
-            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
-            area.
+            Creates tarballs and places them in the
+            <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename>
+            directory in the package feeds area.
+            For more information, see the
+            "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+            section.
         </para>
     </section>
 
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index c0cae81..ecac2b6 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -2686,13 +2686,55 @@
                     section.
                     For more detail on the contents of the
                     <filename>deploy</filename> directory, see the
-                    "<link linkend='images-dev-environment'>Images</link>" and
+                    "<link linkend='images-dev-environment'>Images</link>",
+                    "<link linkend='package-feeds-dev-environment'>Package Feeds</link>",
+                    and
                     "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
                     sections.
                 </para>
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-DEPLOY_DIR_DEB'><glossterm>DEPLOY_DIR_DEB</glossterm>
+            <info>
+                DEPLOY_DIR_DEB[doc] = "Points to a Debian-specific area that the OpenEmbedded build system uses to place images, packages, SDKs and other output files that are ready to be used outside of the build system."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Points to the area that the OpenEmbedded build system uses
+                    to place Debian packages that are ready to be used outside
+                    of the build system.
+                    This variable applies only when
+                    <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+                    contains "package_deb".
+                </para>
+
+                <para>
+                    The BitBake configuration file initially defines the
+                    <filename>DEPLOY_DIR_DEB</filename> variable as a
+                    sub-folder of
+                    <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
+                    <literallayout class='monospaced'>
+     DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
+                    </literallayout>
+                </para>
+
+                <para>
+                    The
+                    <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>
+                    class uses the
+                    <filename>DEPLOY_DIR_DEB</filename> variable to make sure
+                    the
+                    <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>
+                    task writes Debian packages into the appropriate folder.
+                    For more information on how packaging works, see the
+                    "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
             <info>
                 DEPLOY_DIR_IMAGE[doc] = "Points to the area that the OpenEmbedded build system uses to place images and other associated output files that are ready to be deployed onto the target machine."
@@ -2724,6 +2766,123 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-DEPLOY_DIR_IPK'><glossterm>DEPLOY_DIR_IPK</glossterm>
+            <info>
+                DEPLOY_DIR_IPK[doc] = "Points to a IPK-specific area that the OpenEmbedded build system uses to place images, packages, SDKs and other output files that are ready to be used outside of the build system."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Points to the area that the OpenEmbedded build system uses
+                    to place IPK packages that are ready to be used outside of
+                    the build system.
+                    This variable applies only when
+                    <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+                    contains "package_ipk".
+                </para>
+
+                <para>
+                    The BitBake configuration file initially defines this
+                    variable as a sub-folder of
+                    <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
+                    <literallayout class='monospaced'>
+     DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
+                    </literallayout>
+                </para>
+
+                <para>
+                    The
+                    <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>
+                    class uses the
+                    <filename>DEPLOY_DIR_IPK</filename> variable to make sure
+                    the
+                    <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
+                    task writes IPK packages into the appropriate folder.
+                    For more information on how packaging works, see the
+                    "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DEPLOY_DIR_RPM'><glossterm>DEPLOY_DIR_RPM</glossterm>
+            <info>
+                DEPLOY_DIR_RPM[doc] = "Points to a RPM-specific area that the OpenEmbedded build system uses to place images, packages, SDKs and other output files that are ready to be used outside of the build system."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Points to the area that the OpenEmbedded build system uses
+                    to place RPM packages that are ready to be used outside
+                    of the build system.
+                    This variable applies only when
+                    <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+                    contains "package_rpm".
+                </para>
+
+                <para>
+                    The BitBake configuration file initially defines this
+                    variable as a sub-folder of
+                    <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
+                    <literallayout class='monospaced'>
+     DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
+                    </literallayout>
+                </para>
+
+                <para>
+                    The
+                    <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>
+                    class uses the
+                    <filename>DEPLOY_DIR_RPM</filename> variable to make sure
+                    the
+                    <link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>
+                    task writes RPM packages into the appropriate folder.
+                    For more information on how packaging works, see the
+                    "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DEPLOY_DIR_TAR'><glossterm>DEPLOY_DIR_TAR</glossterm>
+            <info>
+                DEPLOY_DIR_TAR[doc] = "Points to a tarball area that the OpenEmbedded build system uses to place images, packages, SDKs and other output files that are ready to be used outside of the build system."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Points to the area that the OpenEmbedded build system uses
+                    to place tarballs that are ready to be used outside of
+                    the build system.
+                    This variable applies only when
+                    <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+                    contains "package_tar".
+                </para>
+
+                <para>
+                    The BitBake configuration file initially defines this
+                    variable as a sub-folder of
+                    <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
+                    <literallayout class='monospaced'>
+     DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
+                    </literallayout>
+                </para>
+
+                <para>
+                    The
+                    <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
+                    class uses the
+                    <filename>DEPLOY_DIR_TAR</filename> variable to make sure
+                    the
+                    <link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>
+                    task writes TAR packages into the appropriate folder.
+                    For more information on how packaging works, see the
+                    "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
             <info>
                 DEPLOYDIR[doc] = "For recipes that inherit the deploy class, the DEPLOYDIR points to a temporary work area for deployed files."