dev-manual, ref-manual: Moved building image to dev-manual

Fixes [YOCTO #12370]

The section in the ref-manual that overviewed the buld process was
redundant and more of a "how-to" topic.  I have moved and merged it
into the dev-manual into a similar area.

(From yocto-docs rev: 44f1351334342629aaa0976f62e64ac4f67166aa)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

4 files changed, 120 insertions, 158 deletions

diff --git a/documentation/Makefile b/documentation/Makefile
index e9ec914df9..c08d912302 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -214,7 +214,7 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \
         figures/wip.png
         else
 TARFILES = mega-manual.html mega-style.css \
-        figures/building-an-image.png figures/YP-flow-diagram.png \
+        figures/YP-flow-diagram.png \
         figures/using-a-pre-built-image.png \
         figures/poky-title.png figures/buildhistory.png \
         figures/buildhistory-web.png \
@@ -282,7 +282,6 @@ XSLTOPTS = --xinclude
 ALLPREQ = html eclipse tarball
 TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
         figures/buildhistory.png figures/buildhistory-web.png \
-        figures/building-an-image.png \
         figures/build-workspace-directory.png \
         eclipse
 MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 4c6c441fe0..dc30659159 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -701,13 +701,16 @@
     </section>
 </section>
 
-<section id='performing-a-simple-build'>
-    <title>Performing a Simple Build</title>
+<section id='dev-building-an-image'>
+    <title>Building an Image</title>
 
     <para>
+        In the development environment, you need to build an image whenever
+        you change hardware support, add or change system libraries, or add
+        or change services that have dependencies.
         Several methods exist that allow you to build an image within the
         Yocto Project.
-        This procedure shows how to build an image using BitBake from a
+        This section shows you how to build an image using BitBake from a
         Linux host.
         <note><title>Notes</title>
             <itemizedlist>
@@ -715,7 +718,7 @@
                     For information on how to build an image using
                     <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>,
                     see the
-                    <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>.
+                    <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster Manual</ulink>.
                     </para></listitem>
                 <listitem><para>
                     For information on how to use
@@ -724,6 +727,12 @@
                     section in the Yocto Project Application Development and
                     the Extensible Software Development Kit (eSDK) manual.
                     </para></listitem>
+                <listitem><para>
+                    For a practical example on how to build an image using the
+                    OpenEmbedded build system, see the
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
+                    section of the Yocto Project Quick Start.
+                    </para></listitem>
             </itemizedlist>
         </note>
     </para>
@@ -736,9 +745,6 @@
         For detailed information on the build process using BitBake, see the
         "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#images-dev-environment'>Images</ulink>"
         section in the Yocto Project Overview Manual.
-        You can also reference the
-        "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
-        section in the Yocto Project Quick Start.
     </para>
 
     <para>
@@ -757,14 +763,30 @@
                 <emphasis>Initialize the Build Environment:</emphasis>
                 Initialize the build environment by sourcing the build
                 environment script (i.e.
-                <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>):
+                <literallayout class='monospaced'>
+     $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>]
+                </literallayout></para>
+
+                <para>When you use the initialization script, the
+                OpenEmbedded build system uses <filename>build</filename> as
+                the default Build Directory in your current work directory.
+                You can use a <replaceable>build_dir</replaceable> argument
+                with the script to specify a different build directory.
+                <note><title>Tip</title>
+                    A common practice is to use a different Build Directory for
+                    different targets.
+                    For example, <filename>~/build/x86</filename> for a
+                    <filename>qemux86</filename> target, and
+                    <filename>~/build/arm</filename> for a
+                    <filename>qemuarm</filename> target.
+                </note>
                 </para></listitem>
             <listitem><para>
                 <emphasis>Make Sure Your <filename>local.conf</filename>
                 File is Correct:</emphasis>
                 Ensure the <filename>conf/local.conf</filename> configuration
-                file, which is found in the
-                <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+                file, which is found in the Build Directory,
                 is set up how you want it.
                 This file defines many aspects of the build environment
                 including the target machine architecture through the
@@ -772,18 +794,100 @@
                 the packaging format used during the build
                 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>),
                 and a centralized tarball download directory through the
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> variable.
                 </para></listitem>
             <listitem><para>
                 <emphasis>Build the Image:</emphasis>
-                Build the image using the <filename>bitbake</filename> command.
-                For example, the following command builds the
+                Build the image using the <filename>bitbake</filename> command:
+                <literallayout class='monospaced'>
+     $ bitbake <replaceable>target</replaceable>
+                </literallayout>
+                <note>
+                    For information on BitBake, see the
+                    <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+                </note>
+                The <replaceable>target</replaceable> is the name of the
+                recipe you want to build.
+                Common targets are the images in
+                <filename>meta/recipes-core/images</filename>,
+                <filename>meta/recipes-sato/images</filename>, etc. all found
+                in the
+                <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+                Or, the target can be the name of a recipe for a specific
+                piece of software such as BusyBox.
+                For more details about the images the OpenEmbedded build
+                system supports, see the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+                chapter in the Yocto Project Reference Manual.</para>
+
+                <para>As an example, the following command builds the
                 <filename>core-image-minimal</filename> image:
                 <literallayout class='monospaced'>
      $ bitbake core-image-minimal
                 </literallayout>
-                For information on BitBake, see the
-                <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+                Once an image has been built, it often needs to be installed.
+                The images and kernels built by the OpenEmbedded build system
+                are placed in the Build Directory in
+                <filename class="directory">tmp/deploy/images</filename>.
+                For information on how to run pre-built images such as
+                <filename>qemux86</filename> and <filename>qemuarm</filename>,
+                see the
+                <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+                manual.
+                For information about how to install these images, see the
+                documentation for your particular board or machine.
+                <note><title>Build Notes</title>
+                    <itemizedlist>
+                        <listitem><para>
+                            If you experience a build error due to resources
+                            temporarily being unavailable and it appears you
+                            should not be having this issue, it might be due
+                            to the combination of a 4.3+ Linux kernel and
+                            <filename>systemd</filename> version 228+
+                            (i.e. see this
+                            <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink>
+                            for information).</para>
+
+                            <para>To work around this issue, you can try either
+                            of the following:
+                            <itemizedlist>
+                                <listitem><para>
+                                    Try the build again.
+                                    </para></listitem>
+                                <listitem><para>
+                                    Modify the "DefaultTasksMax"
+                                    <filename>systemd</filename> parameter
+                                    by uncommenting it and setting it to
+                                    "infinity".
+                                    You can find this parameter in the
+                                    <filename>system.conf</filename> file
+                                    located in
+                                    <filename>/etc/systemd</filename>
+                                    on most systems.
+                                    </para></listitem>
+                            </itemizedlist>
+                            </para></listitem>
+                        <listitem><para>
+                            Building an image without GNU General Public
+                            License Version 3 (GPLv3), or similarly licensed,
+                            components is supported for only minimal and
+                            base images.
+                            See the
+                            "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+                            chapter in the Yocto Project Reference Manual
+                            for more information.
+                            </para></listitem>
+                        <listitem><para>
+                            When building an image using GPL components,
+                            you need to maintain your original settings and
+                            not switch back and forth applying different
+                            versions of the GNU General Public License.
+                            If you rebuild using different versions of GPL,
+                            dependency errors might occur due to some components
+                            not being rebuilt.
+                            </para></listitem>
+                    </itemizedlist>
+                </note>
                 </para></listitem>
         </orderedlist>
     </para>
diff --git a/documentation/ref-manual/figures/building-an-image.png b/documentation/ref-manual/figures/building-an-image.png
deleted file mode 100755
index 1fbea5ab00..0000000000
--- a/documentation/ref-manual/figures/building-an-image.png
+++ /dev/null
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 73b5df88dd..bfca60a99b 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -11,147 +11,6 @@
         documentation set provide more details on how to use the Yocto Project.
     </para>
 
-<section id='usingpoky-build'>
-    <title>Running a Build</title>
-
-    <para>
-        This section provides a summary of the build process and provides information
-        for less obvious aspects of the build process.
-        For general information on how to build an image using the OpenEmbedded build
-        system, see the
-        "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
-        section of the Yocto Project Quick Start.
-    </para>
-
-    <section id='build-overview'>
-        <title>Build Overview</title>
-
-        <para>
-            In the development environment you will need to build an image whenever you change hardware
-            support, add or change system libraries, or add or change services that have dependencies.
-        </para>
-
-        <mediaobject>
-            <imageobject>
-                <imagedata fileref="figures/building-an-image.png" format="PNG" align='center' scalefit='1'/>
-            </imageobject>
-            <caption>
-                <para>Building an Image</para>
-            </caption>
-        </mediaobject>
-
-        <para>
-            The first thing you need to do is set up the OpenEmbedded build
-            environment by sourcing the environment setup script
-            (i.e.
-            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
-            Here is an example:
-            <literallayout class='monospaced'>
-     $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>]
-            </literallayout>
-        </para>
-
-        <para>
-            The <replaceable>build_dir</replaceable> argument is optional and specifies the directory the
-            OpenEmbedded build system uses for the build -
-            the
-            <link linkend='build-directory'>Build Directory</link>.
-            If you do not specify a Build Directory, it defaults to a directory
-            named <filename>build</filename> in your current working directory.
-            A common practice is to use a different Build Directory for different targets.
-            For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
-            target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
-        </para>
-
-        <para>
-            Once the build environment is set up, you can build a target using:
-            <literallayout class='monospaced'>
-     $ bitbake <replaceable>target</replaceable>
-            </literallayout>
-            <note>
-                <para>
-                    If you experience a build error due to resources
-                    temporarily being unavailable and it appears you
-                    should not be having this issue, it might be due
-                    to the combination of a 4.3+ Linux kernel and
-                    <filename>systemd</filename> version 228+
-                    (i.e. see this
-                    <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink>
-                    for information).
-                </para>
-
-                <para>
-                    To work around this issue, you can try either
-                    of the following:
-                    <itemizedlist>
-                        <listitem><para>
-                            Try the build again.
-                            </para></listitem>
-                        <listitem><para>
-                            Modify the "DefaultTasksMax"
-                            <filename>systemd</filename> parameter
-                            by uncommenting it and setting it to
-                            "infinity".
-                            You can find this parameter in the
-                            <filename>system.conf</filename> file
-                            located in
-                            <filename>/etc/systemd</filename>
-                            on most systems.
-                            </para></listitem>
-                    </itemizedlist>
-                </para>
-            </note>
-        </para>
-
-        <para>
-            The <replaceable>target</replaceable> is the name of the recipe you want to build.
-            Common targets are the images in <filename>meta/recipes-core/images</filename>,
-            <filename>meta/recipes-sato/images</filename>, etc. all found in the
-            <link linkend='source-directory'>Source Directory</link>.
-            Or, the target can be the name of a recipe for a specific piece of software such as
-            BusyBox.
-            For more details about the images the OpenEmbedded build system supports, see the
-            "<link linkend="ref-images">Images</link>" chapter.
-        </para>
-
-        <note>
-            Building an image without GNU General Public License Version
-            3 (GPLv3), or similarly licensed, components is supported for
-            only minimal and base images.
-            See the "<link linkend='ref-images'>Images</link>" chapter for more information.
-        </note>
-    </section>
-
-    <section id='building-an-image-using-gpl-components'>
-        <title>Building an Image Using GPL Components</title>
-
-        <para>
-            When building an image using GPL components, you need to maintain your original
-            settings and not switch back and forth applying different versions of the GNU
-            General Public License.
-            If you rebuild using different versions of GPL, dependency errors might occur
-            due to some components not being rebuilt.
-        </para>
-    </section>
-</section>
-
-<section id='usingpoky-install'>
-    <title>Installing and Using the Result</title>
-
-    <para>
-        Once an image has been built, it often needs to be installed.
-        The images and kernels built by the OpenEmbedded build system are placed in the
-        <link linkend='build-directory'>Build Directory</link> in
-        <filename class="directory">tmp/deploy/images</filename>.
-        For information on how to run pre-built images such as <filename>qemux86</filename>
-        and <filename>qemuarm</filename>, see the
-        <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
-        manual.
-        For information about how to install these images, see the documentation for your
-        particular board or machine.
-    </para>
-</section>
-
 <section id='usingpoky-debugging-tools-and-techniques'>
     <title>Debugging Tools and Techniques</title>