ref-manual, mega-manual: New section on package creation

Fixes [YOCTO #2808]

Added a new section to the expanded discussion on how builds
are done.  This section is on package creation.  A new figure
was added to both the ref-manual and mega-manual figures
directories.

(From yocto-docs rev: e31e5aeb7d93f3cfa4fc9c12e324f03a27b5f8ed)

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

3 files changed, 54 insertions, 0 deletions

diff --git a/documentation/mega-manual/figures/analysis-for-package-splitting.png b/documentation/mega-manual/figures/analysis-for-package-splitting.png
new file mode 100644
index 0000000000..5edf62c706
--- /dev/null
+++ b/documentation/mega-manual/figures/analysis-for-package-splitting.png
diff --git a/documentation/ref-manual/figures/analysis-for-package-splitting.png b/documentation/ref-manual/figures/analysis-for-package-splitting.png
new file mode 100644
index 0000000000..5edf62c706
--- /dev/null
+++ b/documentation/ref-manual/figures/analysis-for-package-splitting.png
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 260766191a..1b67ca7424 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -1125,6 +1125,60 @@
                 </itemizedlist>
             </para>
         </section>
+
+        <section id='package-splitting-dev-environment'>
+            <title>Package Splitting</title>
+
+            <para>
+                After source code configured and compiled, BitBake analyzes
+                the results and splits the output into package:
+                <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
+            </para>
+
+            <para>
+                The <filename>do_package</filename> and
+                <filename>do_packagedata</filename> tasks combine to analyze
+                the data found in the
+                <link linkend='var-D'><filename>D</filename></link> directory
+                and split it into subsets based on available packages and
+                files.
+                The analyzing process involves splitting out debugging symbols,
+                looking at shared library dependencies between packages, and
+                looking at package relationships.
+                The <filename>do_packagedata</filename> task puts package
+                metadata based on the analysis such that BitBake can generate
+                the final packages.
+                Intermediate results of the package analysis and splitting
+                end up in the
+                <link linkend='var-PKGDEST'><filename>PKGDEST</filename></link>
+                directory with the
+                <link linkend='var-FILES'><filename>FILES</filename></link>
+                variable defining the files that go into the packages.
+                If you want some details on how this is accomplished, you can
+                look at
+                <link linkend='ref-classes-package'><filename>package.bbclass</filename></link>.
+            </para>
+
+            <para>
+                Depending on the type of packages being created (RPM, DEB, or
+                IPK), the <filename>do_packagewrite_*</filename> task
+                creates the actual packages and places them in the
+                Package Feed area, which is
+                <filename>${TMPDIR}/deploy</filename>.
+                You can see the
+                "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+                section for more detail on that part of the build process.
+                <note>
+                    Support for creating feeds directly from the
+                    <filename>deploy/*</filename> directories does not exist.
+                    Creating such feeds usually requires some kind of feed
+                    maintenance mechanism that would upload the new packages
+                    into an official package feed (e.g. angstrom).
+                    Providing such a piece for the user is not feasible since
+                    it is very distribution-specific.
+                </note>
+            </para>
+        </section>
     </section>
 </section>