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>

2 files changed, 71 insertions, 0 deletions

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">