summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2010-10-28 08:27:28 -0700
committerRichard Purdie <rpurdie@linux.intel.com>2010-11-04 20:20:06 +0000
commit30e92723e12558cf26c941fcdeb18b7e6ac427e3 (patch)
treea26006f2e5f3d79568a83f056ae72fd8ebdd5924
parentceef5c20cf675ffcb57c6b772e3e753ed177cf81 (diff)
downloadpoky-30e92723e12558cf26c941fcdeb18b7e6ac427e3.tar.gz
General text edits through section 2.4.4 "General Bitbak Problems"
Extensive language and consistency edits being applied to the manual. During the 0.9 push I did not have time to make a pass through the document. Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
-rw-r--r--documentation/poky-ref-manual/usingpoky.xml255
1 files changed, 140 insertions, 115 deletions
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
index 70fa5102f5..c2e102ce37 100644
--- a/documentation/poky-ref-manual/usingpoky.xml
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -13,27 +13,33 @@
13 <title>Poky Overview</title> 13 <title>Poky Overview</title>
14 14
15 <para> 15 <para>
16 At the core of Poky is the bitbake task executor together with various types of 16 The bitbake task executor together with various types of configuration files form the core of Poky.
17 configuration files. This section gives an overview of bitbake and the 17 This section overviews the bitbake task executor and the
18 configuration files, in particular what they are used for, and how they 18 configuration files by describing what they are used for and they they interact.
19 interact.
20 </para> 19 </para>
21 20
22 <para> 21 <para>
23 Bitbake handles the parsing and execution of the data 22 Bitbake handles the parsing and execution of the data files.
24 files. The data itself is of various types; recipes which give 23 The data itself is of various types:
25 details about particular pieces of software, class data which is an 24 <itemizedlist>
26 abstraction of common build information (e.g. how to build a Linux kernel) 25 <listitem><para>Recipes: Provides details about particular pieces of software</para></listitem>
27 and configuration data for machines, policy decisions, etc., which acts as 26 <listitem><para>Class Data: An abstraction of common build information (e.g. how to build a
28 a glue and binds everything together. Bitbake knows how to combine multiple 27 Linux kernel).</para></listitem>
29 data sources together, each data source being referred to as a <link 28 <listitem><para>Configuration Data: Defines machine-specific settings, policy decisions, etc.
30 linkend='usingpoky-changes-layers'>'layer'</link>. 29 Configuration data acts a the glue to bind everything together.</para></listitem>
30 </itemizedlist>
31 </para>
32
33 <para>
34 Bitbake knows how to combine multiple data sources together and refers to each data source
35 as a <link linkend='usingpoky-changes-layers'>'layer'</link>.
31 </para> 36 </para>
32 37
33 <para> 38 <para>
34 The <link linkend='ref-structure'>directory structure walkthrough</link> 39 Following are some brief details on these core components.
35 section gives details on the meaning of specific directories but some 40 For more detailed information on these components see the
36 brief details on the core components follows: 41 <link linkend='ref-structure'>'Reference: Directory Structure'</link>
42 appendix.
37 </para> 43 </para>
38 44
39 <section id='usingpoky-components-bitbake'> 45 <section id='usingpoky-components-bitbake'>
@@ -42,23 +48,30 @@
42 <para> 48 <para>
43 Bitbake is the tool at the heart of Poky and is responsible 49 Bitbake is the tool at the heart of Poky and is responsible
44 for parsing the metadata, generating a list of tasks from it 50 for parsing the metadata, generating a list of tasks from it
45 and then executing them. To see a list of the options it 51 and then executing them. To see a list of the options bitbake
46 supports look at <command>bitbake --help</command>. 52 supports look at 'bitbake --help'.
47 </para> 53 </para>
48 54
49 <para> 55 <para>
50 The most common usage is <command>bitbake packagename</command> where 56 The most common usage for bitbake is <filename>bitbake &lt;packagename&gt;</filename>, where
51 packagename is the name of the package you wish to build 57 packagename is the name of the package you want to build (referred to as the 'target'
52 (from now on called the target). This often equates to the first part of a .bb 58 in this manual).
53 filename, so to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you 59 The target often equates to the first part of a <filename>.bb</filename> filename.
54 might type <command>bitbake matchbox-desktop</command>. 60 So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
55 Several different versions of matchbox-desktop might exist and 61 might type the following:
56 bitbake will choose the one selected by the distribution configuration 62 <literallayout class='monospaced'>
57 (more details about how bitbake chooses between different versions 63 $ bitbake matchbox-desktop
58 and providers is available in the <link linkend='ref-bitbake-providers'> 64 </literallayout>
59 'Preferences and Providers' section</link>). Bitbake will also try to execute any 65 Several different versions of <filename>matchbox-desktop</filename> might exist.
60 dependent tasks first so before building matchbox-desktop it 66 Bitbake chooses the one selected by the distribution configuration.
61 would build a cross compiler and glibc if not already built. 67 You can get more details about how bitbake chooses between different versions
68 and providers in the <link linkend='ref-bitbake-providers'>
69 'Preferences and Providers' section</link>.
70 </para>
71 <para>
72 Bitbake also tries to execute any dependent tasks first.
73 So for example, before building <filename>matchbox-desktop</filename> bitbake
74 would build a cross compiler and glibc if they had not already been built.
62 </para> 75 </para>
63 76
64 </section> 77 </section>
@@ -67,17 +80,17 @@
67 <title>Metadata (Recipes)</title> 80 <title>Metadata (Recipes)</title>
68 81
69 <para> 82 <para>
70 The .bb files are usually referred to as 'recipes'. In general, a 83 The <filename>.bb</filename> files are usually referred to as 'recipes'.
71 recipe contains information about a single piece of software such 84 In general, a recipe contains information about a single piece of software such
72 as where to download the source, any patches that are needed, 85 as from where to download the source patches (if any are needed), which special
73 any special configuration options, how to compile the source files 86 configuration options to apply, how to compile the source files, and how to
74 and how to package the compiled output. 87 package the compiled output.
75 </para> 88 </para>
76 89
77 <para> 90 <para>
78 'package' can also be used to describe recipes but since the same 91 The term 'package' can also be used to describe recipes.
79 word is used for the packaged output from Poky (i.e. .ipk or .deb 92 However, since the same word is used for the packaged output from Poky (i.e. .ipk or .deb
80 files), this document will avoid it. 93 files), this document avoids it.
81 </para> 94 </para>
82 95
83 </section> 96 </section>
@@ -86,11 +99,12 @@
86 <title>Classes</title> 99 <title>Classes</title>
87 100
88 <para> 101 <para>
89 Class (.bbclass) files contain information which is useful to share 102 Class files (<filename>.bbclass</filename>) contain information that is useful to share
90 between metadata files. An example is the autotools class which contains 103 between metadata files.
91 the common settings that any application using autotools would use. The 104 An example is the autotools class, which contains
92 <link linkend='ref-classes'>classes reference section</link> gives details 105 common settings for any application that autotools uses.
93 on common classes and how to use them. 106 The <link linkend='ref-classes'>Reference: Classes</link> appendix provides details
107 about common classes and how to use them.
94 </para> 108 </para>
95 </section> 109 </section>
96 110
@@ -98,18 +112,17 @@
98 <title>Configuration</title> 112 <title>Configuration</title>
99 113
100 <para> 114 <para>
101 The configuration (.conf) files define various configuration variables 115 The configuration files (<filename>.conf</filename>) define various configuration variables
102 which govern what Poky does. These are split into several areas, such 116 that govern what Poky does.
103 as machine configuration options, distribution configuration options, 117 These files are split into several areas that define machine configuration options,
104 compiler tuning options, general common configuration and user 118 distribution configuration options, compiler tuning options, general common configuration
105 configuration (local.conf). 119 options and user configuration options (<filename>local.conf</filename>).
106 </para> 120 </para>
107 </section> 121 </section>
108 122
109</section> 123</section>
110 124
111 125
112
113<section id='usingpoky-build'> 126<section id='usingpoky-build'>
114 <title>Running a Build</title> 127 <title>Running a Build</title>
115 128
@@ -122,14 +135,14 @@ $ source poky-init-build-env [build_dir]
122</literallayout> 135</literallayout>
123 </para> 136 </para>
124 <para> 137 <para>
125 The build_dir is the dir containing all the building object files. The default 138 The build_dir is the dir containing all the build's object files. The default
126 build dir is poky-dir/build. Multiple build_dir can be used for different targets. 139 build dir is poky-dir/build. A different build_dir can be used for each of the targets.
127 For example, ~/build/x86 for qemux86 target, and ~/build/arm for qemuarm target. 140 For example, ~/build/x86 for a qemux86 target, and ~/build/arm for a qemuarm target.
128 Please refer to <link linkend="structure-core-script">poky-init-build-env</link> 141 Please refer to <link linkend="structure-core-script">poky-init-build-env</link>
129 for detail info 142 for more detailed information.
130 </para> 143 </para>
131 <para> 144 <para>
132 Once the Poky build environment is set up, a target can now be built using: 145 Once the Poky build environment is set up, a target can be built using:
133 </para> 146 </para>
134 <para> 147 <para>
135 <literallayout class='monospaced'> 148 <literallayout class='monospaced'>
@@ -137,11 +150,13 @@ $ bitbake &lt;target&gt;
137</literallayout> 150</literallayout>
138 </para> 151 </para>
139 <para> 152 <para>
140 The target is the name of the recipe you want to build. Common targets are the 153 The target is the name of the recipe you want to build.
141 images (in <filename class="directory">meta/packages/images/</filename>) 154 Common targets are the images in <filename>meta/recipes-core/images</filename>),
142 or the name of a recipe for a specific piece of software like 155 <filename>/meta/recipes-sato/images</filename>, etc.
143 <application>busybox</application>. More details about the standard images 156 Or, the target can be the name of a recipe for a specific piece of software such as
144 are available in the <link linkend='ref-images'>image reference section</link>. 157 <application>busybox</application>.
158 For more details about the standard images available, see the
159 <link linkend="ref-images">'Reference: Images'</link> appendix.
145 </para> 160 </para>
146</section> 161</section>
147 162
@@ -149,11 +164,15 @@ $ bitbake &lt;target&gt;
149 <title>Installing and Using the Result</title> 164 <title>Installing and Using the Result</title>
150 165
151 <para> 166 <para>
152 Once an image has been built it often needs to be installed. The images/kernels built 167 Once an image has been built it often needs to be installed.
153 by Poky are placed in the <filename class="directory">tmp/deploy/images</filename> 168 The images/kernels built by Poky are placed in the
154 directory. Running qemux86 and qemuarm images is covered in the <link 169 <filename class="directory">tmp/deploy/images</filename> directory.
155 linkend='intro-quickstart-qemu'>Running an Image</link> section. See your 170 Running qemux86 and qemuarm images is described in the
156 board/machine documentation for information about how to install these images. 171 'Using Pre-Built Binaries and QEMU' section of the Yocto Project Quick Start.
172 See <ulink url="http://www.yoctoproject.org//docs/yocto-quick-start/yocto-project-qs.html"></ulink>
173 for the guide.
174 For information about how to install these images, see the documentation for your
175 particular board/machine.
157 </para> 176 </para>
158 177
159</section> 178</section>
@@ -163,66 +182,73 @@ $ bitbake &lt;target&gt;
163 182
164 <para> 183 <para>
165 The exact method for debugging Poky depends on the nature of the 184 The exact method for debugging Poky depends on the nature of the
166 bug(s) and which part of the system they might be from. Standard 185 problem and on the system's area from which the bug originates.
167 debugging practises such as comparing to the last 186 Standard debugging practises such as comparison against the last
168 known working version and examining the changes, reapplying the 187 known working version with examination of the changes and the reapplication of steps
169 changes in steps to identify the one causing the problem etc. are 188 to identify the one causing the problem are
170 valid for Poky just like any other system. It's impossible to detail 189 valid for Poky just as they are for any other system.
171 every possible potential failure here but there are some general 190 It's impossible to detail every possible potential failure but here are some general
172 tips to aid debugging: 191 tips to aid in debugging:
173 </para> 192 </para>
174 193
175 <section id='usingpoky-debugging-taskfailures'> 194 <section id='usingpoky-debugging-taskfailures'>
176 <title>Task Failures</title> 195 <title>Task Failures</title>
177 196
178 <para>The log file for shell tasks is available in <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. 197 <para>The log file for shell tasks is available in <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
179 For the compile task of busybox 1.01 on the ARM spitz machine, this 198 For example, the compile task of busybox 1.01 on the ARM spitz machine might be
180 might be <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename> 199 <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename>.
181 for example. To see what bitbake ran to generate that log, look at the <filename>run.do_taskname.pid </filename> 200 To see what bitbake runs to generate that log, look at the corresponding
182 file in the same directory. 201 <filename>run.do_taskname.pid </filename> file located in the same directory.
183 </para> 202 </para>
184 203
185 <para>The output from python tasks is sent directly to the console at present.</para> 204 <para>Presently, the output from python tasks is sent directly to the console.</para>
186 </section> 205 </section>
187 206
188 <section id='usingpoky-debugging-taskrunning'> 207 <section id='usingpoky-debugging-taskrunning'>
189 <title>Running specific tasks</title> 208 <title>Running specific tasks</title>
190 209
191 <para> Any given package consists of a set of tasks, in most 210 <para> Any given package consists of a set of tasks.
192 cases the series is fetch, unpack, patch, configure, 211 In most cases the series is: fetch, unpack, patch, configure,
193 compile, install, package, package_write and build. The 212 compile, install, package, package_write and build.
194 default task is "build" and any tasks this depends on are 213 The default task is "build" and any tasks on which it depends build first - hence,
195 built first hence the standard bitbake behaviour. There are 214 the standard bitbake behaviour.
196 some tasks such as devshell which are not part of the 215 Some tasks exist, such as devshell, that are not part of the default build chain.
197 default build chain. If you wish to run such a task you can 216 If you wish to run a task that is not part of the default build chain you can use the
198 use the "-c" option to bitbake e.g. <command>bitbake 217 "-c" option in bitbake as follows:
199 matchbox-desktop -c devshell</command>. 218 <literallayout class='monospaced'>
219$ bitbake matchbox-desktop -c devshell
220 </literallayout>
200 </para> 221 </para>
201 222
202 <para> 223 <para>
203 If you wish to rerun a task you can use the force option 224 If you wish to rerun a task use the force option "-f".
204 "-f". A typical usage session might look like: </para> 225 For example, the following sequence forces recompilation after changing files in the
226 working directory.
227 </para>
205 228
206 <para> 229 <para>
207 <literallayout class='monospaced'> 230 <literallayout class='monospaced'>
208% bitbake matchbox-desktop 231$ bitbake matchbox-desktop
209[change some source in the WORKDIR for example] 232[make some changes to the source code in the WORKDIR]
210% bitbake matchbox-desktop -c compile -f 233$ bitbake matchbox-desktop -c compile -f
211% bitbake matchbox-desktop</literallayout> 234$ bitbake matchbox-desktop
235 </literallayout>
212 </para> 236 </para>
213 237
214 <para> 238 <para>
215 which would build matchbox-desktop, then recompile it. The 239 This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it.
216 final command reruns all tasks after the compile (basically 240 The last command reruns all tasks, basically the packaging tasks, after the compile.
217 the packaging tasks) since bitbake will notice that the 241 Bitbake recognizes that the compile task was rerun and therefore understands that the other
218 compile has been rerun and hence the other tasks also need 242 tasks also need to be run again.
219 to run again.
220 </para> 243 </para>
221 244
222 <para> 245 <para>
223 You can view a list of tasks in a given package by running 246 You can view a list of tasks in a given package by running the listtasks task.
224 the listtasks task e.g. <command>bitbake matchbox-desktop -c 247 For example:
225 listtasks</command>, and the result is in file ${WORKDIR}/temp/log.do_listtasks. 248 <literallayout class='monospaced'>
249$ bitbake matchbox-desktop -c
250 </literallayout>
251 The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
226 </para> 252 </para>
227 </section> 253 </section>
228 254
@@ -230,16 +256,13 @@ $ bitbake &lt;target&gt;
230 <title>Dependency Graphs</title> 256 <title>Dependency Graphs</title>
231 257
232 <para> 258 <para>
233 Sometimes it can be hard to see why bitbake wants to build 259 Sometimes it can be hard to see why bitbake wants to build some other packages before a given
234 some other packages before a given package you've specified. 260 package you've specified.
235 <command>bitbake -g targetname</command> will create 261 The <filename>bitbake -g targetname</filename> command creates the <filename>depends.dot</filename> and
236 <filename>depends.dot</filename> and 262 <filename>task-depends.dot</filename> files in the current directory.
237 <filename>task-depends.dot</filename> files in the current 263 These files show the package and task dependencies and are useful for debugging problems.
238 directory. They show 264 You can use the <filename>bitbake -g -u depexp targetname</filename> command to display the results
239 which packages and tasks depend on which other packages and 265 in a more human-readable form.
240 tasks and are useful for debugging purposes.
241 <command>"bitbake -g -u depexp targetname"</command> will show result
242 in more human-readable GUI style.
243 </para> 266 </para>
244 </section> 267 </section>
245 268
@@ -247,17 +270,19 @@ $ bitbake &lt;target&gt;
247 <title>General Bitbake Problems</title> 270 <title>General Bitbake Problems</title>
248 271
249 <para> 272 <para>
250 Debug output from bitbake can be seen with the "-D" option. 273 You can see debug output from bitbake by using the "-D" option.
251 The debug output gives more information about what bitbake 274 The debug output gives more information about what bitbake
252 is doing and/or why. Each -D option increases the logging 275 is doing and the reason behind it.
253 level, the most common usage being "-DDD". 276 Each "-D" option you use increases the logging level.
277 The most common usage is <filename>-DDD</filename>.
254 </para> 278 </para>
255 279
256 <para> 280 <para>
257 The output from <command>bitbake -DDD -v targetname</command> can reveal why 281 The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
258 a certain version of a package might be chosen, why bitbake 282 bitbake chose a certain version of a package or why bitbake
259 picked a certain provider or help in other situations where 283 picked a certain provider.
260 bitbake does something you're not expecting. 284 This command could also help you in a situation where you think bitbake did something
285 unexpected.
261 </para> 286 </para>
262 </section> 287 </section>
263 288