documentation: Removed "usingpoky" chapter from ref-manual

Fixes [YOCTO #12370]

All of the information from the "usingpoky" chapter in the
ref-manual has been distributed out over the rest of the
YP manual set.  Primarily, this information went into the
dev-manual and the overview-manual.  Because the chapter is
no more, I had to update the mega-manual.xml to not include that
chapter. Also, had to update ref-manual to exclude the chapter
as part of the Make process.

(From yocto-docs rev: b988cab06d42f0ac2220cefe66949c5ab6cbf803)

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

1 files changed, 165 insertions, 0 deletions

diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 02635f4127..21f5e9ed5e 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -840,6 +840,171 @@
         </orderedlist>
     </para>
 </section>
+
+<section id='speeding-up-the-build'>
+    <title>Speeding Up the Build</title>
+
+    <para>
+        Build time can be an issue.
+        By default, the build system uses simple controls to try and maximize
+        build efficiency.
+        In general, the default settings for all the following variables
+        result in the most efficient build times when dealing with single
+        socket systems (i.e. a single CPU).
+        If you have multiple CPUs, you might try increasing the default
+        values to gain more speed.
+        See the descriptions in the glossary for each variable for more
+        information:
+        <itemizedlist>
+            <listitem><para>
+                <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename>:</link>
+                The maximum number of threads BitBake simultaneously executes.
+                </para></listitem>
+            <listitem><para>
+                <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename>:</ulink>
+                The number of threads BitBake uses during parsing.
+                </para></listitem>
+            <listitem><para>
+                <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename>:</link>
+                Extra options passed to the <filename>make</filename> command
+                during the
+                <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
+                task in order to specify parallel compilation on the
+                local build host.
+                </para></listitem>
+            <listitem><para>
+                <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename>:</link>
+                Extra options passed to the <filename>make</filename> command
+                during the
+                <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+                task in order to specify parallel installation on the
+                local build host.
+                </para></listitem>
+        </itemizedlist>
+        As mentioned, these variables all scale to the number of processor
+        cores available on the build system.
+        For single socket systems, this auto-scaling ensures that the build
+        system fundamentally takes advantage of potential parallel operations
+        during the build based on the build machine's capabilities.
+    </para>
+
+    <para>
+        Following are additional factors that can affect build speed:
+        <itemizedlist>
+            <listitem><para>
+                File system type:
+                The file system type that the build is being performed on can
+                also influence performance.
+                Using <filename>ext4</filename> is recommended as compared
+                to <filename>ext2</filename> and <filename>ext3</filename>
+                due to <filename>ext4</filename> improved features
+                such as extents.
+                </para></listitem>
+            <listitem><para>
+                Disabling the updating of access time using
+                <filename>noatime</filename>:
+                The <filename>noatime</filename> mount option prevents the
+                build system from updating file and directory access times.
+                </para></listitem>
+            <listitem><para>
+                Setting a longer commit:
+                Using the "commit=" mount option increases the interval
+                in seconds between disk cache writes.
+                Changing this interval from the five second default to
+                something longer increases the risk of data loss but decreases
+                the need to write to the disk, thus increasing the build
+                performance.
+                </para></listitem>
+            <listitem><para>
+                Choosing the packaging backend:
+                Of the available packaging backends, IPK is the fastest.
+                Additionally, selecting a singular packaging backend also
+                helps.
+                </para></listitem>
+            <listitem><para>
+                Using <filename>tmpfs</filename> for
+                <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+                as a temporary file system:
+                While this can help speed up the build, the benefits are
+                limited due to the compiler using
+                <filename>-pipe</filename>.
+                The build system goes to some lengths to avoid
+                <filename>sync()</filename> calls into the
+                file system on the principle that if there was a significant
+                failure, the
+                <link linkend='build-directory'>Build Directory</link>
+                contents could easily be rebuilt.
+                </para></listitem>
+            <listitem><para>
+                Inheriting the
+                <link linkend='ref-classes-rm-work'><filename>rm_work</filename></link>
+                class:
+                Inheriting this class has shown to speed up builds due to
+                significantly lower amounts of data stored in the data
+                cache as well as on disk.
+                Inheriting this class also makes cleanup of
+                <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+                faster, at the expense of being easily able to dive into the
+                source code.
+                File system maintainers have recommended that the fastest way
+                to clean up large numbers of files is to reformat partitions
+                rather than delete files due to the linear nature of partitions.
+                This, of course, assumes you structure the disk partitions and
+                file systems in a way that this is practical.
+                </para></listitem>
+        </itemizedlist>
+        Aside from the previous list, you should keep some trade offs in
+        mind that can help you speed up the build:
+        <itemizedlist>
+            <listitem><para>
+                Remove items from
+                <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
+                that you might not need.
+                </para></listitem>
+            <listitem><para>
+                Exclude debug symbols and other debug information:
+                If you do not need these symbols and other debug information,
+                disabling the <filename>*-dbg</filename> package generation
+                can speed up the build.
+                You can disable this generation by setting the
+                <link linkend='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></link>
+                variable to "1".
+                </para></listitem>
+            <listitem><para>
+                Disable static library generation for recipes derived from
+                <filename>autoconf</filename> or <filename>libtool</filename>:
+                Following is an example showing how to disable static
+                libraries and still provide an override to handle exceptions:
+                <literallayout class='monospaced'>
+     STATICLIBCONF = "--disable-static"
+     STATICLIBCONF_sqlite3-native = ""
+     EXTRA_OECONF += "${STATICLIBCONF}"
+                </literallayout>
+                <note><title>Notes</title>
+                    <itemizedlist>
+                        <listitem><para>
+                            Some recipes need static libraries in order to work
+                            correctly (e.g. <filename>pseudo-native</filename>
+                            needs <filename>sqlite3-native</filename>).
+                            Overrides, as in the previous example, account for
+                            these kinds of exceptions.
+                            </para></listitem>
+                        <listitem><para>
+                            Some packages have packaging code that assumes the
+                            presence of the static libraries.
+                            If so, you might need to exclude them as well.
+                            </para></listitem>
+                    </itemizedlist>
+                </note>
+            </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+
+
+
+
 </chapter>
 <!--
 vim: expandtab tw=80 ts=4