1 files changed, 139 insertions, 0 deletions
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 1a211ca78a..030448df0b 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -89,6 +89,145 @@
    </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>

diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml index 1a211ca78a..030448df0b 100644 --- a/documentation/ref-manual/usingpoky.xml +++ b/documentation/ref-manual/usingpoky.xml
@@ -89,6 +89,145 @@
89	</section>	89	</section>
90	</section>	90	</section>
91		91
		92	<section id='speeding-up-the-build'>
		93	<title>Speeding Up the Build</title>
		94
		95	<para>
		96	Build time can be an issue.
		97	By default, the build system uses three simple controls to try and
		98	maximize build efficiency:
		99	<itemizedlist>
		100	<listitem><para>
		101	<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
		102	</para></listitem>
		103	<listitem><para>
		104	<ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
		105	</para></listitem>
		106	<listitem><para>
		107	<link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
		108	</para></listitem>
		109	</itemizedlist>
		110	These three variables all scale to the number of processor cores
		111	available on the build system.
		112	This auto-scaling ensures that the build system fundamentally takes
		113	advantage of potential parallel operations during the build
		114	based on the build machine's capabilities.
		115	</para>
		116
		117	<para>
		118	If you need to achieve even faster builds than what the build system
		119	produces by default, you can consider and implement some of the
		120	following:
		121	<itemizedlist>
		122	<listitem><para>
		123	<filename>BB_NUMBER_THREADS</filename>,
		124	<filename>BB_NUMBER_PARSE_THREADS</filename>, and
		125	<filename>PARALLEL_MAKE</filename>:
		126	As previously mentioned, the build system scales the values
		127	for these variables.
		128	However, you can manually override them in your
		129	<filename>local.conf</filename> file if you are not satisfied
		130	with the defaults.
		131	</para></listitem>
		132	<listitem><para>
		133	File system type:
		134	The file system type that the build is being performed on can
		135	also influence performance.
		136	Using <filename>ext4</filename> is recommended as compared
		137	to <filename>ext2</filename> and <filename>ext3</filename>
		138	due to <filename>ext4</filename> improved features
		139	such as extents.
		140	</para></listitem>
		141	<listitem><para>
		142	Disabling the updating of access time using
		143	<filename>noatime</filename>:
		144	The <filename>noatime</filename> mount option prevents the
		145	build system from updating file and directory access times.
		146	</para></listitem>
		147	<listitem><para>
		148	Setting a longer commit:
		149	Richard - I need some sort of general summary here about this.
		150	I don't know the context.
		151	</para></listitem>
		152	<listitem><para>
		153	The packaging backend:
		154	Of the available packaging backends, IPK is the fastest.
		155	Additionally, selecting a singular packaging backend also
		156	helps.
		157	</para></listitem>
		158	<listitem><para>
		159	Using <filename>/tmp</filename> as a temporary file system:
		160	While this can help speed up the build, the benefits are
		161	limited due to the compiler using
		162	<filename>-pipe</filename>.
		163	The build system goes to some lengths to avoid
		164	<filename>sync()</filename> calls into the
		165	file system on the principle that if there was a significant
		166	failure, the
		167	<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
		168	contents could easily be rebuilt.
		169	</para></listitem>
		170	<listitem><para>
		171	Inheriting the
		172	<link linkend='ref-classes-rm-work'><filename>rm_work</filename></link>
		173	class:
		174	Inheriting this class has shown to speed up builds due to
		175	significantly lower amounts of data stored in the data
		176	cache as well as on disk.
		177	Inheriting this class also makes cleanup of
		178	<link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
		179	faster, at the expense of being easily able to dive into the
		180	source code.
		181	File system maintainers have recommended that the fastest way
		182	to clean up large numbers of files is to reformat partitions
		183	rather than delete files due to the linear nature of partitions.
		184	This, of course, assumes you structure the disk partitions and
		185	file systems in a way that this is practical.
		186	</para></listitem>
		187	</itemizedlist>
		188	Aside from the previous list, you should keep some trade offs in
		189	mind that can help you speed up the build:
		190	<itemizedlist>
		191	<listitem><para>
		192	Exclude debug symbols and other debug information:
		193	If you do not need these symbols and other debug information,
		194	disabling the <filename>*-dbg</filename> package generation
		195	can speed up the build.
		196	You can disable this generation by setting the
		197	<link linkend='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></link>
		198	variable to "1".
		199	</para></listitem>
		200	<listitem><para>
		201	Disable static library generation for recipes derived from
		202	<filename>autoconf</filename> or <filename>libtool</filename>:
		203	Following is an example showing how to disable static
		204	libraries and still provide an override to handle exceptions:
		205	<literallayout class='monospaced'>
		206	STATICLIBCONF = "--disable-static"
		207	STATICLIBCONF_sqlite3-native = ""
		208	EXTRA_OECONF += "${STATICLIBCONF}"
		209	</literallayout>
		210	<note><title>Notes</title>
		211	<itemizedlist>
		212	<listitem><para>
		213	Some recipes need static libraries in order to work
		214	correctly (e.g. <filename>pseudo-native</filename>
		215	needs <filename>sqlite3-native</filename>).
		216	Overrides, as in the previous example, account for
		217	these kinds of exceptions.
		218	</para></listitem>
		219	<listitem><para>
		220	Some packages have packaging code that assumes the
		221	presence of the static libraries.
		222	If so, you might need to exclude them as well.
		223	</para></listitem>
		224	</itemizedlist>
		225	</note>
		226	</para></listitem>
		227	</itemizedlist>
		228	</para>
		229	</section>
		230
92	<section id='usingpoky-install'>	231	<section id='usingpoky-install'>
93	<title>Installing and Using the Result</title>	232	<title>Installing and Using the Result</title>
94		233