diff options
Diffstat (limited to 'documentation/poky-ref-manual/usingpoky.xml')
-rw-r--r-- | documentation/poky-ref-manual/usingpoky.xml | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml new file mode 100644 index 0000000000..ad6bda2545 --- /dev/null +++ b/documentation/poky-ref-manual/usingpoky.xml | |||
@@ -0,0 +1,316 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | ||
3 | <chapter id='usingpoky'> | ||
4 | <title>Using Poky</title> | ||
5 | |||
6 | <para> | ||
7 | This section gives an overview of the components that make up Poky | ||
8 | following by information about running poky builds and dealing with any | ||
9 | problems that may arise. | ||
10 | </para> | ||
11 | |||
12 | <section id='usingpoky-components'> | ||
13 | <title>Poky Overview</title> | ||
14 | |||
15 | <para> | ||
16 | At the core of Poky is the bitbake task executor together with various types of | ||
17 | configuration files. This section gives an overview of bitbake and the | ||
18 | configuration files, in particular what they are used for, and how they | ||
19 | interact. | ||
20 | </para> | ||
21 | |||
22 | <para> | ||
23 | Bitbake handles the parsing and execution of the data | ||
24 | files. The data itself is of various types; recipes which give | ||
25 | details about particular pieces of software, class data which is an | ||
26 | abstraction of common build information (e.g. how to build a Linux kernel) | ||
27 | and configuration data for machines, policy decisions, etc., which acts as | ||
28 | a glue and binds everything together. Bitbake knows how to combine multiple | ||
29 | data sources together, each data source being referred to as a <link | ||
30 | linkend='usingpoky-changes-layers'>'layer'</link>. | ||
31 | </para> | ||
32 | |||
33 | <para> | ||
34 | The <link linkend='ref-structure'>directory structure walkthrough</link> | ||
35 | section gives details on the meaning of specific directories but some | ||
36 | brief details on the core components follows: | ||
37 | </para> | ||
38 | |||
39 | <section id='usingpoky-components-bitbake'> | ||
40 | <title>Bitbake</title> | ||
41 | |||
42 | <para> | ||
43 | Bitbake is the tool at the heart of Poky and is responsible | ||
44 | for parsing the metadata, generating a list of tasks from it | ||
45 | and then executing them. To see a list of the options it | ||
46 | supports look at <command>bitbake --help</command>. | ||
47 | </para> | ||
48 | |||
49 | <para> | ||
50 | The most common usage is <command>bitbake packagename</command> where | ||
51 | packagename is the name of the package you wish to build | ||
52 | (from now on called the target). This often equates to the first part of a .bb | ||
53 | filename, so to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you | ||
54 | might type <command>bitbake matchbox-desktop</command>. | ||
55 | Several different versions of matchbox-desktop might exist and | ||
56 | bitbake will choose the one selected by the distribution configuration | ||
57 | (more details about how bitbake chooses between different versions | ||
58 | and providers is available in the <link linkend='ref-bitbake-providers'> | ||
59 | 'Preferences and Providers' section</link>). Bitbake will also try to execute any | ||
60 | dependent tasks first so before building matchbox-desktop it | ||
61 | would build a cross compiler and glibc if not already built. | ||
62 | </para> | ||
63 | |||
64 | </section> | ||
65 | |||
66 | <section id='usingpoky-components-metadata'> | ||
67 | <title>Metadata (Recipes)</title> | ||
68 | |||
69 | <para> | ||
70 | The .bb files are usually referred to as 'recipes'. In general, a | ||
71 | recipe contains information about a single piece of software such | ||
72 | as where to download the source, any patches that are needed, | ||
73 | any special configuration options, how to compile the source files | ||
74 | and how to package the compiled output. | ||
75 | </para> | ||
76 | |||
77 | <para> | ||
78 | 'package' can also be used to describe recipes but since the same | ||
79 | word is used for the packaged output from Poky (i.e. .ipk or .deb | ||
80 | files), this document will avoid it. | ||
81 | </para> | ||
82 | |||
83 | </section> | ||
84 | |||
85 | <section id='usingpoky-components-classes'> | ||
86 | <title>Classes</title> | ||
87 | |||
88 | <para> | ||
89 | Class (.bbclass) files contain information which is useful to share | ||
90 | between metadata files. An example is the autotools class which contains | ||
91 | the common settings that any application using autotools would use. The | ||
92 | <link linkend='ref-classes'>classes reference section</link> gives details | ||
93 | on common classes and how to use them. | ||
94 | </para> | ||
95 | </section> | ||
96 | |||
97 | <section id='usingpoky-components-configuration'> | ||
98 | <title>Configuration</title> | ||
99 | |||
100 | <para> | ||
101 | The configuration (.conf) files define various configuration variables | ||
102 | which govern what Poky does. These are split into several areas, such | ||
103 | as machine configuration options, distribution configuration options, | ||
104 | compiler tuning options, general common configuration and user | ||
105 | configuration (local.conf). | ||
106 | </para> | ||
107 | </section> | ||
108 | |||
109 | </section> | ||
110 | |||
111 | |||
112 | |||
113 | <section id='usingpoky-build'> | ||
114 | <title>Running a Build</title> | ||
115 | |||
116 | <para> | ||
117 | First the Poky build environment needs to be set up using the following command: | ||
118 | </para> | ||
119 | <para> | ||
120 | <literallayout class='monospaced'> | ||
121 | $ source poky-init-build-env [build_dir] | ||
122 | </literallayout> | ||
123 | </para> | ||
124 | <para> | ||
125 | The build_dir is the dir containing all the building object files. The default | ||
126 | build dir is poky-dir/build. Multiple build_dir can be used for different targets. | ||
127 | For example, ~/build/x86 for qemux86 target, and ~/build/arm for qemuarm target. | ||
128 | Please refer to <link linkend="structure-core-script">poky-init-build-env</link> | ||
129 | for detail info | ||
130 | </para> | ||
131 | <para> | ||
132 | Once the Poky build environment is set up, a target can now be built using: | ||
133 | </para> | ||
134 | <para> | ||
135 | <literallayout class='monospaced'> | ||
136 | $ bitbake <target> | ||
137 | $ bitbake qemu-native | ||
138 | </literallayout> | ||
139 | </para> | ||
140 | <para> | ||
141 | The target is the name of the recipe you want to build. Common targets are the | ||
142 | images (in <filename class="directory">meta/packages/images/</filename>) | ||
143 | or the name of a recipe for a specific piece of software like | ||
144 | <application>busybox</application>. More details about the standard images | ||
145 | are available in the <link linkend='ref-images'>image reference section</link>. | ||
146 | The qemu-native target will build the poky customized qemu, and will be used | ||
147 | by runqemu script later. | ||
148 | </para> | ||
149 | </section> | ||
150 | |||
151 | <section id='usingpoky-install'> | ||
152 | <title>Installing and Using the Result</title> | ||
153 | |||
154 | <para> | ||
155 | Once an image has been built it often needs to be installed. The images/kernels built | ||
156 | by Poky are placed in the <filename class="directory">tmp/deploy/images</filename> | ||
157 | directory. Running qemux86 and qemuarm images is covered in the <link | ||
158 | linkend='intro-quickstart-qemu'>Running an Image</link> section. See your | ||
159 | board/machine documentation for information about how to install these images. | ||
160 | </para> | ||
161 | |||
162 | </section> | ||
163 | |||
164 | <section id='usingpoky-debugging'> | ||
165 | <title>Debugging Build Failures</title> | ||
166 | |||
167 | <para> | ||
168 | The exact method for debugging Poky depends on the nature of the | ||
169 | bug(s) and which part of the system they might be from. Standard | ||
170 | debugging practises such as comparing to the last | ||
171 | known working version and examining the changes, reapplying the | ||
172 | changes in steps to identify the one causing the problem etc. are | ||
173 | valid for Poky just like any other system. It's impossible to detail | ||
174 | every possible potential failure here but there are some general | ||
175 | tips to aid debugging: | ||
176 | </para> | ||
177 | |||
178 | <section id='usingpoky-debugging-taskfailures'> | ||
179 | <title>Task Failures</title> | ||
180 | |||
181 | <para>The log file for shell tasks is available in <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. | ||
182 | For the compile task of busybox 1.01 on the ARM spitz machine, this | ||
183 | might be <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename> | ||
184 | for example. To see what bitbake ran to generate that log, look at the <filename>run.do_taskname.pid </filename> | ||
185 | file in the same directory. | ||
186 | </para> | ||
187 | |||
188 | <para>The output from python tasks is sent directly to the console at present.</para> | ||
189 | </section> | ||
190 | |||
191 | <section id='usingpoky-debugging-taskrunning'> | ||
192 | <title>Running specific tasks</title> | ||
193 | |||
194 | <para> Any given package consists of a set of tasks, in most | ||
195 | cases the series is fetch, unpack, patch, configure, | ||
196 | compile, install, package, package_write and build. The | ||
197 | default task is "build" and any tasks this depends on are | ||
198 | built first hence the standard bitbake behaviour. There are | ||
199 | some tasks such as devshell which are not part of the | ||
200 | default build chain. If you wish to run such a task you can | ||
201 | use the "-c" option to bitbake e.g. <command>bitbake | ||
202 | matchbox-desktop -c devshell</command>. | ||
203 | </para> | ||
204 | |||
205 | <para> | ||
206 | If you wish to rerun a task you can use the force option | ||
207 | "-f". A typical usage session might look like: </para> | ||
208 | |||
209 | <para> | ||
210 | <literallayout class='monospaced'> | ||
211 | % bitbake matchbox-desktop | ||
212 | [change some source in the WORKDIR for example] | ||
213 | % bitbake matchbox-desktop -c compile -f | ||
214 | % bitbake matchbox-desktop</literallayout> | ||
215 | </para> | ||
216 | |||
217 | <para> | ||
218 | which would build matchbox-desktop, then recompile it. The | ||
219 | final command reruns all tasks after the compile (basically | ||
220 | the packaging tasks) since bitbake will notice that the | ||
221 | compile has been rerun and hence the other tasks also need | ||
222 | to run again. | ||
223 | </para> | ||
224 | |||
225 | <para> | ||
226 | You can view a list of tasks in a given package by running | ||
227 | the listtasks task e.g. <command>bitbake matchbox-desktop -c | ||
228 | listtasks</command>, and the result is in file ${WORKDIR}/temp/log.do_listtasks.pid. | ||
229 | </para> | ||
230 | </section> | ||
231 | |||
232 | <section id='usingpoky-debugging-dependencies'> | ||
233 | <title>Dependency Graphs</title> | ||
234 | |||
235 | <para> | ||
236 | Sometimes it can be hard to see why bitbake wants to build | ||
237 | some other packages before a given package you've specified. | ||
238 | <command>bitbake -g targetname</command> will create | ||
239 | <filename>depends.dot</filename> and | ||
240 | <filename>task-depends.dot</filename> files in the current | ||
241 | directory. They show | ||
242 | which packages and tasks depend on which other packages and | ||
243 | tasks and are useful for debugging purposes. | ||
244 | <command>"bitbake -g -u depexp targetname"</command> will show result | ||
245 | in more human-readable GUI style. | ||
246 | </para> | ||
247 | </section> | ||
248 | |||
249 | <section id='usingpoky-debugging-bitbake'> | ||
250 | <title>General Bitbake Problems</title> | ||
251 | |||
252 | <para> | ||
253 | Debug output from bitbake can be seen with the "-D" option. | ||
254 | The debug output gives more information about what bitbake | ||
255 | is doing and/or why. Each -D option increases the logging | ||
256 | level, the most common usage being "-DDD". | ||
257 | </para> | ||
258 | |||
259 | <para> | ||
260 | The output from <command>bitbake -DDD -v targetname</command> can reveal why | ||
261 | a certain version of a package might be chosen, why bitbake | ||
262 | picked a certain provider or help in other situations where | ||
263 | bitbake does something you're not expecting. | ||
264 | </para> | ||
265 | </section> | ||
266 | |||
267 | <section id='usingpoky-debugging-buildfile'> | ||
268 | <title>Building with no dependencies</title> | ||
269 | |||
270 | <para> | ||
271 | If you really want to build a specific .bb file, you can use | ||
272 | the form <command>bitbake -b somepath/somefile.bb</command>. Note that this | ||
273 | will not check the dependencies so this option should only | ||
274 | be used when you know its dependencies already exist. You | ||
275 | can specify fragments of the filename and bitbake will see | ||
276 | if it can find a unique match. | ||
277 | </para> | ||
278 | |||
279 | </section> | ||
280 | |||
281 | <section id='usingpoky-debugging-variables'> | ||
282 | <title>Variables</title> | ||
283 | |||
284 | <para> | ||
285 | The "-e" option will dump the resulting environment for | ||
286 | either the configuration (no package specified) or for a | ||
287 | specific package when specified with the "-b" option. | ||
288 | </para> | ||
289 | </section> | ||
290 | |||
291 | <section id='usingpoky-debugging-others'> | ||
292 | <title>Other Tips</title> | ||
293 | |||
294 | <tip> | ||
295 | <para>When adding new packages it is worth keeping an eye open for bad | ||
296 | things creeping into compiler commandlines such as references to local | ||
297 | system files (<filename>/usr/lib/</filename> or <filename>/usr/include/</filename> etc.). | ||
298 | </para> | ||
299 | </tip> | ||
300 | |||
301 | <tip> | ||
302 | <para> | ||
303 | If you want to remove the psplash boot splashscreen, add "psplash=false" | ||
304 | to the kernel commandline and psplash won't load allowing you to see | ||
305 | the console. It's also possible to switch out of the splashscreen by | ||
306 | switching virtual console (Fn+Left or Fn+Right on a Zaurus). | ||
307 | </para> | ||
308 | </tip> | ||
309 | |||
310 | </section> | ||
311 | </section> | ||
312 | |||
313 | </chapter> | ||
314 | <!-- | ||
315 | vim: expandtab tw=80 ts=4 | ||
316 | --> | ||