dev-manual: Moved "Speeding Up the Build" and renamed it.

Renamed to "Speeding Up a Build" and moved out of the setting up
chapter to the common tasks chapter. Fixed a couple links in the
ref-manual.

(From yocto-docs rev: c53fddd353230c8ef1abc21c7a2d2b1f492f034a)

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

1 files changed, 158 insertions, 3 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index d4b99bc69f..9e8dd5fa92 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -6224,11 +6224,166 @@
 
 
 
+    <section id='speeding-up-a-build'>
+        <title>Speeding Up a 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>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename>:</ulink>
+                    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>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename>:</ulink>
+                    Extra options passed to the <filename>make</filename> command
+                    during the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
+                    task in order to specify parallel compilation on the
+                    local build host.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename>:</ulink>
+                    Extra options passed to the <filename>make</filename> command
+                    during the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+                    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
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+                    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
+                    <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+                    contents could easily be rebuilt.
+                    </para></listitem>
+                <listitem><para>
+                    Inheriting the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink>
+                    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
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+                    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
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
+                    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
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></ulink>
+                    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>
 
     <section id="platdev-working-with-libraries">
         <title>Working With Libraries</title>