ref-manual, Makefile: New section on BitBake for expanded build

Fixes [YOCTO #2808]

Created a new section called "BitBake" that will provide an
expanded discussion of the basic YP build process.  The
"BitBake" section has a new sub-section called "Source Fetching."

Part of the new section is a new figure named source-fetching.png.
The figure must reside in the "figures" directory in both the
ref-manual and the mega-manual.  It must also be listed for each
of these manuals in the TARBALL statement in the Makefile.

(From yocto-docs rev: 41eff3e755a98ff31cadccfb1cd7dfcf569b4d9e)

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

4 files changed, 74 insertions, 2 deletions

diff --git a/documentation/Makefile b/documentation/Makefile
index e3a0db4c22..90efc0542b 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -198,7 +198,8 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures
         figures/sched-wakeup-profile.png figures/sysprof-callers.png \
         figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png figures/cross-development-toolchains.png \
         figures/yocto-environment-ref.png figures/user-configuration.png figures/source-input.png \
-        figures/package-feeds.png figures/layer-input.png figures/images.png figures/sdk.png
+        figures/package-feeds.png figures/layer-input.png figures/images.png figures/sdk.png \
+        figures/source-fetching.png
         endif
 
 MANUALS = $(DOC)/$(DOC).html
@@ -215,7 +216,7 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
         figures/cross-development-toolchains.png figures/layer-input.png \
         figures/package-feeds.png figures/source-input.png \
         figures/user-configuration.png figures/yocto-environment-ref.png \
-        figures/images.png figures/sdk.png
+        figures/images.png figures/sdk.png figures/source-fetching.png
 MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
 FIGURES = figures
 STYLESHEET = $(DOC)/*.css
diff --git a/documentation/mega-manual/figures/source-fetching.png b/documentation/mega-manual/figures/source-fetching.png
new file mode 100644
index 0000000000..ff8414280b
--- /dev/null
+++ b/documentation/mega-manual/figures/source-fetching.png
diff --git a/documentation/ref-manual/figures/source-fetching.png b/documentation/ref-manual/figures/source-fetching.png
new file mode 100644
index 0000000000..ff8414280b
--- /dev/null
+++ b/documentation/ref-manual/figures/source-fetching.png
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 400bbd6e4e..a3dd6f0cb0 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -961,6 +961,77 @@
             </itemizedlist>
         </para>
     </section>
+
+    <section id='bitbake-dev-environment'>
+        <title>BitBake</title>
+
+        <para>
+            The OpenEmbedded build system uses BitBake to produce images.
+            You can see from the
+            <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
+            figure, the BitBake area consists of several functional areas.
+            This section takes a closer look at each of those areas.
+        </para>
+
+        <section id='source-fetching-dev-environment'>
+            <title>Source Fetching</title>
+
+            <para>
+                The first stages of building a recipe are to fetch and unpack
+                the source code:
+                <imagedata fileref="figures/source-fetching.png" align="center" width="6in" depth="4in" />
+            </para>
+
+            <para>
+                The <filename>do_fetch</filename> and
+                <filename>do_unpack</filename> tasks fetch the source files
+                and unpack them into a working directory.
+                By default, everything is accomplished in the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
+                which has a defined structure.
+                For additional general information on the Build Directory,
+                see the
+                "<link linkend='structure-core-build'><filename>build/</filename></link>"
+                section.
+            </para>
+
+            <para>
+                Unpacked source source files are pointed to by the
+                <link linkend='var-S'><filename>S</filename></link> variable.
+                Each recipe has an area in the Build Directory where the
+                unpacked source code resides.
+                The name of directory for any given recipe is defined from
+                several different variables.
+                You can see the variables that define these directories
+                by looking at the figure:
+                <itemizedlist>
+                    <listitem><para><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PN'><filename>PN</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PV'><filename>PV</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PR'><filename>PR</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-S'><filename>S</filename></link>
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Briefly, the <filename>S</filename> directory contains the
+                unpacked source files for a recipe.
+                The <filename>WORKDIR</filename> directory is where all the
+                building goes on for a given recipe.
+            </para>
+        </section>
+    </section>
 </section>
 
 <section id="cross-development-toolchain-generation">