ref-manual: WIP - Edits for the speed section.

(From yocto-docs rev: 3a158dbefe32fb1e87718558462c0562077052c8)

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

1 files changed, 142 insertions, 139 deletions

diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 030448df0b..41f872c07e 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -89,145 +89,6 @@
     </section>
 </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 three simple controls to try and
-        maximize build efficiency:
-        <itemizedlist>
-            <listitem><para>
-                <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
-                </para></listitem>
-            <listitem><para>
-                <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
-                </para></listitem>
-            <listitem><para>
-                <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
-                </para></listitem>
-        </itemizedlist>
-        These three variables all scale to the number of processor cores
-        available on the build system.
-        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>
-        If you need to achieve even faster builds than what the build system
-        produces by default, you can consider and implement some of the
-        following:
-        <itemizedlist>
-            <listitem><para>
-                <filename>BB_NUMBER_THREADS</filename>,
-                <filename>BB_NUMBER_PARSE_THREADS</filename>, and
-                <filename>PARALLEL_MAKE</filename>:
-                As previously mentioned, the build system scales the values
-                for these variables.
-                However, you can manually override them in your
-                <filename>local.conf</filename> file if you are not satisfied
-                with the defaults.
-                </para></listitem>
-            <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:
-                Richard - I need some sort of general summary here about this.
-                I don't know the context.
-                </para></listitem>
-            <listitem><para>
-                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>/tmp</filename> 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_DEV_URL;#build-directory'>Build Directory</ulink>
-                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>
-                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>
-
 <section id='usingpoky-install'>
     <title>Installing and Using the Result</title>
 
@@ -1027,6 +888,148 @@
     </section>
 </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 three simple controls to try and
+        maximize build efficiency:
+        <itemizedlist>
+            <listitem><para>
+                <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
+                </para></listitem>
+            <listitem><para>
+                <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
+                </para></listitem>
+            <listitem><para>
+                <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
+                </para></listitem>
+        </itemizedlist>
+        These three variables all scale to the number of processor cores
+        available on the build system.
+        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>
+        If you need to achieve even faster builds than what the build system
+        produces by default, you can consider and implement some of the
+        following:
+        <itemizedlist>
+            <listitem><para>
+                <filename>BB_NUMBER_THREADS</filename>,
+                <filename>BB_NUMBER_PARSE_THREADS</filename>, and
+                <filename>PARALLEL_MAKE</filename>:
+                As previously mentioned, the build system scales the values
+                for these variables.
+                However, you can manually override them in your
+                <filename>local.conf</filename> file if you are not satisfied
+                with the defaults.
+                </para></listitem>
+            <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>/tmp</filename> 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_DEV_URL;#build-directory'>Build Directory</ulink>
+                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>
+                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