summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-23 11:29:22 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:29 +0000
commit30b91e6d891fbfa6a44487a27b8ceb5618157614 (patch)
treea55464032253d643fc4ceec7952cc32e656fdc26 /documentation
parent355103f8cf2295fb2de91ce25a084e286bdeadeb (diff)
downloadpoky-30b91e6d891fbfa6a44487a27b8ceb5618157614.tar.gz
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>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-start.xml165
-rw-r--r--documentation/mega-manual/mega-manual.xml3
-rw-r--r--documentation/ref-manual/ref-manual.xml2
-rw-r--r--documentation/ref-manual/usingpoky.xml184
4 files changed, 165 insertions, 189 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 @@
840 </orderedlist> 840 </orderedlist>
841 </para> 841 </para>
842</section> 842</section>
843
844<section id='speeding-up-the-build'>
845 <title>Speeding Up the Build</title>
846
847 <para>
848 Build time can be an issue.
849 By default, the build system uses simple controls to try and maximize
850 build efficiency.
851 In general, the default settings for all the following variables
852 result in the most efficient build times when dealing with single
853 socket systems (i.e. a single CPU).
854 If you have multiple CPUs, you might try increasing the default
855 values to gain more speed.
856 See the descriptions in the glossary for each variable for more
857 information:
858 <itemizedlist>
859 <listitem><para>
860 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename>:</link>
861 The maximum number of threads BitBake simultaneously executes.
862 </para></listitem>
863 <listitem><para>
864 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename>:</ulink>
865 The number of threads BitBake uses during parsing.
866 </para></listitem>
867 <listitem><para>
868 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename>:</link>
869 Extra options passed to the <filename>make</filename> command
870 during the
871 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
872 task in order to specify parallel compilation on the
873 local build host.
874 </para></listitem>
875 <listitem><para>
876 <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename>:</link>
877 Extra options passed to the <filename>make</filename> command
878 during the
879 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
880 task in order to specify parallel installation on the
881 local build host.
882 </para></listitem>
883 </itemizedlist>
884 As mentioned, these variables all scale to the number of processor
885 cores available on the build system.
886 For single socket systems, this auto-scaling ensures that the build
887 system fundamentally takes advantage of potential parallel operations
888 during the build based on the build machine's capabilities.
889 </para>
890
891 <para>
892 Following are additional factors that can affect build speed:
893 <itemizedlist>
894 <listitem><para>
895 File system type:
896 The file system type that the build is being performed on can
897 also influence performance.
898 Using <filename>ext4</filename> is recommended as compared
899 to <filename>ext2</filename> and <filename>ext3</filename>
900 due to <filename>ext4</filename> improved features
901 such as extents.
902 </para></listitem>
903 <listitem><para>
904 Disabling the updating of access time using
905 <filename>noatime</filename>:
906 The <filename>noatime</filename> mount option prevents the
907 build system from updating file and directory access times.
908 </para></listitem>
909 <listitem><para>
910 Setting a longer commit:
911 Using the "commit=" mount option increases the interval
912 in seconds between disk cache writes.
913 Changing this interval from the five second default to
914 something longer increases the risk of data loss but decreases
915 the need to write to the disk, thus increasing the build
916 performance.
917 </para></listitem>
918 <listitem><para>
919 Choosing the packaging backend:
920 Of the available packaging backends, IPK is the fastest.
921 Additionally, selecting a singular packaging backend also
922 helps.
923 </para></listitem>
924 <listitem><para>
925 Using <filename>tmpfs</filename> for
926 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
927 as a temporary file system:
928 While this can help speed up the build, the benefits are
929 limited due to the compiler using
930 <filename>-pipe</filename>.
931 The build system goes to some lengths to avoid
932 <filename>sync()</filename> calls into the
933 file system on the principle that if there was a significant
934 failure, the
935 <link linkend='build-directory'>Build Directory</link>
936 contents could easily be rebuilt.
937 </para></listitem>
938 <listitem><para>
939 Inheriting the
940 <link linkend='ref-classes-rm-work'><filename>rm_work</filename></link>
941 class:
942 Inheriting this class has shown to speed up builds due to
943 significantly lower amounts of data stored in the data
944 cache as well as on disk.
945 Inheriting this class also makes cleanup of
946 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
947 faster, at the expense of being easily able to dive into the
948 source code.
949 File system maintainers have recommended that the fastest way
950 to clean up large numbers of files is to reformat partitions
951 rather than delete files due to the linear nature of partitions.
952 This, of course, assumes you structure the disk partitions and
953 file systems in a way that this is practical.
954 </para></listitem>
955 </itemizedlist>
956 Aside from the previous list, you should keep some trade offs in
957 mind that can help you speed up the build:
958 <itemizedlist>
959 <listitem><para>
960 Remove items from
961 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
962 that you might not need.
963 </para></listitem>
964 <listitem><para>
965 Exclude debug symbols and other debug information:
966 If you do not need these symbols and other debug information,
967 disabling the <filename>*-dbg</filename> package generation
968 can speed up the build.
969 You can disable this generation by setting the
970 <link linkend='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></link>
971 variable to "1".
972 </para></listitem>
973 <listitem><para>
974 Disable static library generation for recipes derived from
975 <filename>autoconf</filename> or <filename>libtool</filename>:
976 Following is an example showing how to disable static
977 libraries and still provide an override to handle exceptions:
978 <literallayout class='monospaced'>
979 STATICLIBCONF = "--disable-static"
980 STATICLIBCONF_sqlite3-native = ""
981 EXTRA_OECONF += "${STATICLIBCONF}"
982 </literallayout>
983 <note><title>Notes</title>
984 <itemizedlist>
985 <listitem><para>
986 Some recipes need static libraries in order to work
987 correctly (e.g. <filename>pseudo-native</filename>
988 needs <filename>sqlite3-native</filename>).
989 Overrides, as in the previous example, account for
990 these kinds of exceptions.
991 </para></listitem>
992 <listitem><para>
993 Some packages have packaging code that assumes the
994 presence of the static libraries.
995 If so, you might need to exclude them as well.
996 </para></listitem>
997 </itemizedlist>
998 </note>
999 </para></listitem>
1000 </itemizedlist>
1001 </para>
1002</section>
1003
1004
1005
1006
1007
843</chapter> 1008</chapter>
844<!-- 1009<!--
845vim: expandtab tw=80 ts=4 1010vim: expandtab tw=80 ts=4
diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml
index 1d6b83e24a..f44e8c4e65 100644
--- a/documentation/mega-manual/mega-manual.xml
+++ b/documentation/mega-manual/mega-manual.xml
@@ -240,9 +240,6 @@
240 xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-terms.xml"/> 240 xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-terms.xml"/>
241 241
242 <xi:include 242 <xi:include
243 xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/usingpoky.xml"/>
244
245 <xi:include
246 xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-release-process.xml"/> 243 xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-release-process.xml"/>
247 244
248 <xi:include 245 <xi:include
diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml
index f17d850ce3..dbcc28bcd6 100644
--- a/documentation/ref-manual/ref-manual.xml
+++ b/documentation/ref-manual/ref-manual.xml
@@ -170,8 +170,6 @@
170 170
171 <xi:include href="ref-terms.xml"/> 171 <xi:include href="ref-terms.xml"/>
172 172
173 <xi:include href="usingpoky.xml"/>
174
175 <xi:include href="ref-release-process.xml"/> 173 <xi:include href="ref-release-process.xml"/>
176 174
177 <xi:include href="migration.xml"/> 175 <xi:include href="migration.xml"/>
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
deleted file mode 100644
index e6b71b1565..0000000000
--- a/documentation/ref-manual/usingpoky.xml
+++ /dev/null
@@ -1,184 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='usingpoky'>
6<title>Using the Yocto Project</title>
7
8 <para>
9 This chapter describes common usage for the Yocto Project.
10 The information is introductory in nature as other manuals in the Yocto Project
11 documentation set provide more details on how to use the Yocto Project.
12 </para>
13
14
15
16OLD START WAS HERE.
17
18
19OLD END WAS HERE.
20
21
22<section id='speeding-up-the-build'>
23 <title>Speeding Up the Build</title>
24
25 <para>
26 Build time can be an issue.
27 By default, the build system uses simple controls to try and maximize
28 build efficiency.
29 In general, the default settings for all the following variables
30 result in the most efficient build times when dealing with single
31 socket systems (i.e. a single CPU).
32 If you have multiple CPUs, you might try increasing the default
33 values to gain more speed.
34 See the descriptions in the glossary for each variable for more
35 information:
36 <itemizedlist>
37 <listitem><para>
38 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename>:</link>
39 The maximum number of threads BitBake simultaneously executes.
40 </para></listitem>
41 <listitem><para>
42 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename>:</ulink>
43 The number of threads BitBake uses during parsing.
44 </para></listitem>
45 <listitem><para>
46 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename>:</link>
47 Extra options passed to the <filename>make</filename> command
48 during the
49 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
50 task in order to specify parallel compilation on the
51 local build host.
52 </para></listitem>
53 <listitem><para>
54 <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename>:</link>
55 Extra options passed to the <filename>make</filename> command
56 during the
57 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
58 task in order to specify parallel installation on the
59 local build host.
60 </para></listitem>
61 </itemizedlist>
62 As mentioned, these variables all scale to the number of processor
63 cores available on the build system.
64 For single socket systems, this auto-scaling ensures that the build
65 system fundamentally takes advantage of potential parallel operations
66 during the build based on the build machine's capabilities.
67 </para>
68
69 <para>
70 Following are additional factors that can affect build speed:
71 <itemizedlist>
72 <listitem><para>
73 File system type:
74 The file system type that the build is being performed on can
75 also influence performance.
76 Using <filename>ext4</filename> is recommended as compared
77 to <filename>ext2</filename> and <filename>ext3</filename>
78 due to <filename>ext4</filename> improved features
79 such as extents.
80 </para></listitem>
81 <listitem><para>
82 Disabling the updating of access time using
83 <filename>noatime</filename>:
84 The <filename>noatime</filename> mount option prevents the
85 build system from updating file and directory access times.
86 </para></listitem>
87 <listitem><para>
88 Setting a longer commit:
89 Using the "commit=" mount option increases the interval
90 in seconds between disk cache writes.
91 Changing this interval from the five second default to
92 something longer increases the risk of data loss but decreases
93 the need to write to the disk, thus increasing the build
94 performance.
95 </para></listitem>
96 <listitem><para>
97 Choosing the packaging backend:
98 Of the available packaging backends, IPK is the fastest.
99 Additionally, selecting a singular packaging backend also
100 helps.
101 </para></listitem>
102 <listitem><para>
103 Using <filename>tmpfs</filename> for
104 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
105 as a temporary file system:
106 While this can help speed up the build, the benefits are
107 limited due to the compiler using
108 <filename>-pipe</filename>.
109 The build system goes to some lengths to avoid
110 <filename>sync()</filename> calls into the
111 file system on the principle that if there was a significant
112 failure, the
113 <link linkend='build-directory'>Build Directory</link>
114 contents could easily be rebuilt.
115 </para></listitem>
116 <listitem><para>
117 Inheriting the
118 <link linkend='ref-classes-rm-work'><filename>rm_work</filename></link>
119 class:
120 Inheriting this class has shown to speed up builds due to
121 significantly lower amounts of data stored in the data
122 cache as well as on disk.
123 Inheriting this class also makes cleanup of
124 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
125 faster, at the expense of being easily able to dive into the
126 source code.
127 File system maintainers have recommended that the fastest way
128 to clean up large numbers of files is to reformat partitions
129 rather than delete files due to the linear nature of partitions.
130 This, of course, assumes you structure the disk partitions and
131 file systems in a way that this is practical.
132 </para></listitem>
133 </itemizedlist>
134 Aside from the previous list, you should keep some trade offs in
135 mind that can help you speed up the build:
136 <itemizedlist>
137 <listitem><para>
138 Remove items from
139 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
140 that you might not need.
141 </para></listitem>
142 <listitem><para>
143 Exclude debug symbols and other debug information:
144 If you do not need these symbols and other debug information,
145 disabling the <filename>*-dbg</filename> package generation
146 can speed up the build.
147 You can disable this generation by setting the
148 <link linkend='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></link>
149 variable to "1".
150 </para></listitem>
151 <listitem><para>
152 Disable static library generation for recipes derived from
153 <filename>autoconf</filename> or <filename>libtool</filename>:
154 Following is an example showing how to disable static
155 libraries and still provide an override to handle exceptions:
156 <literallayout class='monospaced'>
157 STATICLIBCONF = "--disable-static"
158 STATICLIBCONF_sqlite3-native = ""
159 EXTRA_OECONF += "${STATICLIBCONF}"
160 </literallayout>
161 <note><title>Notes</title>
162 <itemizedlist>
163 <listitem><para>
164 Some recipes need static libraries in order to work
165 correctly (e.g. <filename>pseudo-native</filename>
166 needs <filename>sqlite3-native</filename>).
167 Overrides, as in the previous example, account for
168 these kinds of exceptions.
169 </para></listitem>
170 <listitem><para>
171 Some packages have packaging code that assumes the
172 presence of the static libraries.
173 If so, you might need to exclude them as well.
174 </para></listitem>
175 </itemizedlist>
176 </note>
177 </para></listitem>
178 </itemizedlist>
179 </para>
180</section>
181</chapter>
182<!--
183vim: expandtab tw=80 ts=4
184-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 18:59:03 +0000